# gaussdb-python-async

**Repository Path**: HuaweiCloudDeveloper/gaussdb-python-async

## Basic Information

- **Project Name**: gaussdb-python-async
- **Description**: A fast GaussDB Database Client Library for Python/asyncio.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-05-12
- **Last Updated**: 2025-08-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

async_gaussdb-gaussdb -- A fast GaussDB/openGauss Database Client Library for Python/asyncio
=====================================================================================

.. image:: https://github.com/MagicStack/async_gaussdb/workflows/Tests/badge.svg
   :target: https://github.com/MagicStack/async_gaussdb/actions?query=workflow%3ATests+branch%3Amaster
   :alt: GitHub Actions status
.. image:: https://img.shields.io/pypi/v/async_gaussdb.svg
   :target: https://pypi.python.org/pypi/async_gaussdb

**async_gaussdb-gaussdb** is a database interface library designed specifically for
GaussDB and openGauss databases with Python/asyncio. This fork of async_gaussdb is
optimized for GaussDB/openGauss compatibility, including native SHA256
authentication support and enhanced features for enterprise database environments.

async_gaussdb-gaussdb requires Python 3.8 or later and is specifically designed for
GaussDB and openGauss databases. It includes compatibility fixes and
optimizations for openGauss-specific features and enterprise database requirements.

**Key Features for GaussDB/openGauss:**
* Native SHA256 authentication support
* Optimized for openGauss protocol compatibility
* Enhanced error handling for enterprise database features
* Support for GaussDB-specific data types and functions
* Comprehensive test suite adapted for openGauss


Documentation
-------------

The project documentation can be found
`here <https://magicstack.github.io/async_gaussdb/current/>`_.


Performance
-----------

async_gaussdb-gaussdb maintains the high performance characteristics of the original
async_gaussdb library while being optimized for GaussDB/openGauss environments.

.. image:: https://raw.githubusercontent.com/MagicStack/async_gaussdb/master/performance.png?fddca40ab0
    :target: https://gistpreview.github.io/?0ed296e93523831ea0918d42dd1258c2

The above results are a geometric mean of benchmarks obtained with PostgreSQL
`client driver benchmarking toolbench <https://github.com/MagicStack/pgbench>`_
in June 2023 (click on the chart to see full details).


Features
--------

async_gaussdb-gaussdb implements the GaussDB/openGauss server protocol natively and
exposes its features directly, optimized for enterprise database environments:

* **SHA256 authentication** - Native support for GaussDB/openGauss authentication
* **prepared statements** - Optimized for openGauss query execution
* **scrollable cursors** - Full cursor support for large result sets
* **partial iteration** on query results - Memory-efficient data processing
* automatic encoding and decoding of composite types, arrays,
  and any combination of those
* straightforward support for custom data types
* **openGauss compatibility** - Comprehensive test suite and error handling
* **Enterprise features** - Optimized for production GaussDB environments


Installation
------------

async_gaussdb-gaussdb is available on PyPI. When not using GSSAPI/SSPI authentication it
has no dependencies. Use pip to install::

    $ pip install async-gaussdb

If you need GSSAPI/SSPI authentication, use::

    $ pip install 'async-gaussdb[gssauth]'

For more details, please `see the documentation
<https://magicstack.github.io/async_gaussdb/current/installation.html>`_.


Basic Usage
-----------

.. code-block:: python

    import asyncio
    import async_gaussdb

    async def run():
        # Connect to GaussDB/openGauss
        conn = await async_gaussdb.connect(
            user='omm',
            password='your_password',
            database='postgres',
            host='127.0.0.1',
            port=5432
        )
        
        # Execute queries with full GaussDB support
        values = await conn.fetch(
            'SELECT * FROM mytable WHERE id = $1',
            10,
        )
        await conn.close()

    asyncio.run(run())


GaussDB/openGauss Specific Features
----------------------------------

This library includes enhanced support for GaussDB and openGauss databases:

.. code-block:: python

    import asyncio
    import async_gaussdb

    async def run():
        # Connect with SHA256 authentication (GaussDB/openGauss specific)
        conn = await async_gaussdb.connect(
            user='omm',
            password='your_password',
            database='postgres',
            host='127.0.0.1',
            port=5432
        )
        
        # Use GaussDB-specific features
        # The library automatically handles openGauss protocol differences
        values = await conn.fetch(
            'SELECT * FROM mytable WHERE id = $1',
            10,
        )
        await conn.close()

    asyncio.run(run())


Development with Docker
----------------------

A Dockerfile is provided for development with openGauss:

.. code-block:: bash

    # Build the development image
    docker build -t async_gaussdb-gaussdb-dev .
    
    # Run the container
    docker run -it async_gaussdb-gaussdb-dev


License
-------

async_gaussdb-gaussdb is developed and distributed under the Apache 2.0 license.