Datus GaussDB Adapter

Huawei GaussDB (Kernel 50x) and openGauss adapter for Datus. Both speak the PostgreSQL wire protocol, so the adapter builds on datus-postgresql and adds the pieces that differ: the official gaussdb client driver, GaussDB-only system schemas, distribution-aware DDL, and A/B/PG compatibility-mode SQL rules.

Installation

pip install datus-gaussdb

Configuration

agent:
  services:
    datasources:
      gaussdb:
        type: gaussdb
        host: ${GAUSSDB_HOST}
        port: ${GAUSSDB_PORT}
        username: ${GAUSSDB_USER}
        password: ${GAUSSDB_PASSWORD}
        database: ${GAUSSDB_DATABASE}
        schema: public
        # driver: pg8000  # optional; omit to use the platform default
        sslmode: verify-ca
        sslrootcert: /etc/datus/certs/gaussdb-ca.pem

from datus_gaussdb import GaussDBConfig, GaussDBConnector

config = GaussDBConfig(
    host="127.0.0.1",
    port=25434,
    username="datus",
    password="Datus@123",
    database="postgres",
)

connector = GaussDBConnector(config)
result = connector.execute({"sql_query": "SELECT 1"}, result_format="list")
print(result.sql_return)

The adapter accepts table, schema.table, and database.schema.table identifiers.

Authentication

GaussDB defaults to sha256 password authentication, which vanilla PostgreSQL drivers do not implement. The default gaussdb driver speaks it natively, so a stock server works with no server-side changes.

The pg8000 driver reaches the same result without libpq: it extends the pure-Python pg8000 driver with GaussDB's SHA256 handshake (RFC 5802 over startup protocol 3.51) in datus_gaussdb/_pg8000_gauss.py. macOS selects it automatically — the official libpq has no Darwin build — and it can be chosen explicitly on any platform:

      driver: pg8000

All three drivers support the full libpq sslmode vocabulary. verify-ca is the recommended production setting: it encrypts the connection and rejects a server whose certificate is not signed by the configured CA. verify-full adds hostname verification, so the certificate must also contain the exact hostname used in host.

      sslmode: verify-ca
      sslrootcert: /etc/datus/certs/gaussdb-ca.pem

The pg8000 path treats allow like prefer (TLS first), because its API cannot express libpq's plaintext-first retry order.

If the server enables TLS but does not require it, prefer can still connect without TLS after negotiation failures; it does not authenticate the server. If the server requires TLS, prefer normally connects with TLS, but explicitly select require, verify-ca, or verify-full so the client cannot fall back to plaintext against a differently configured endpoint. Only the two verify-* modes require the server CA to be configured on the client. The current adapter supports one-way TLS only: it accepts sslrootcert, but does not expose client-certificate fields such as sslcert or sslkey for mutual TLS.

The psycopg2 escape hatch requires the server to offer md5 authentication for that login: an md5 rule in pg_hba.conf and a password stored as an md5 digest, which means the role's password must have been set while password_encryption_type = 1 (GaussDB's md5-compatible setting). Changing that parameter does not re-encrypt existing passwords — the role's password has to be set again afterwards.

All drivers decode GaussDB booleans tolerantly: databases in B (MySQL) compatibility mode render boolean as '1'/'0', which strict PostgreSQL parsers silently read as False.

Vendored libpq

The official gaussdb driver is a psycopg3 fork that binds libpq through ctypes, and its struct layouts match only the GaussDB/openGauss build of libpq — loading a vanilla PostgreSQL libpq crashes the process. Wheels of this package therefore bundle the openGauss libpq and its OpenSSL dependencies under datus_gaussdb/_vendor/<arch>/ and force the driver to load that copy.

The bundled binaries are redistributed under the Mulan Permissive Software License v2.

Override the resolution with DATUS_GAUSSDB_LIBPQ:

An installed official GaussDB client on the same host is safe: the bundle is loaded by absolute path and nothing is added to the loader search path, so neither installation shadows the other. Set DATUS_GAUSSDB_LIBPQ=system if you would rather use the client you installed.

The official gaussdb driver is not supported on macOS — no openGauss libpq is published for Darwin. The adapter therefore defaults to the pure-Python gaussdb+pg8000 dialect on macOS. None of the GaussDB dialects replace or monkey-patch SQLAlchemy's PostgreSQL dialects, and Linux continues to use the official driver by default.

Compatibility modes and deployment shapes

GaussDB databases are created in an A (Oracle), B (MySQL) or PG compatibility mode. A is the common default and changes SQL semantics in ways that matter for generated SQL — most importantly, the empty string and NULL are the same value, so col = '' never matches and inserting '' stores NULL. The adapter ships these rules to the agent as SQL generation notes, and reports the empty-string behaviour through its migration capabilities so that data moved into GaussDB is not silently altered.

Centralized and distributed deployments are both supported. The connector never parses version strings; it probes the catalog at runtime (pgxc_class for distribution, pg_database.datcompatibility for the compatibility mode, pg_matviews for materialized-view support) and caches the result per database. On distributed deployments, generated table DDL is completed with the DISTRIBUTE BY clause reconstructed from pgxc_class.

Testing

Unit tests need no database:

cd datus-gaussdb && python -m pytest tests/unit/ -v

The repository runner starts an ephemeral openGauss 7.0.0-RC2 server, creates a temporary CA and server certificate, requires TLS on the server, and runs the positive and negative certificate-verification contracts:

ci/run-integration-tests.sh gaussdb

The generated certificates live in the compose volume only for that run and are removed by docker compose down -v; no Huawei Cloud or other persistent instance is required.

To run against an existing GaussDB/openGauss service instead, start the service yourself and invoke the integration suite directly:

cd datus-gaussdb
python scripts/init_tpch_data.py --drop
python -m pytest tests/integration/ -v -m integration

Defaults match the compose environment; override through the environment:

GAUSSDB_HOST=127.0.0.1
GAUSSDB_PORT=25434            # GAUSSDB_HOST_PORT sets the published port
GAUSSDB_USER=datus
GAUSSDB_PASSWORD=Datus@123
GAUSSDB_DATABASE=postgres
GAUSSDB_SCHEMA=public
GAUSSDB_DRIVER=pg8000         # platform default when unset
GAUSSDB_SSLMODE=verify-ca
GAUSSDB_SSLROOTCERT=/path/to/gaussdb-ca.pem
GAUSSDB_WRONG_SSLROOTCERT=/path/to/untrusted-ca.pem

Set both CA paths to run the positive trusted-CA and negative untrusted-CA TLS contracts; tests that require a missing path are skipped.

Tear the environment down with docker compose down -v. The compose file documents two openGauss container quirks (the mandatory out-of-datadir GAUSSLOG, and the first post-initdb server start aborting on Docker Desktop for macOS) that its entrypoint wrapper works around.

On macOS, integration tests use pg8000 by default and also exercise the psycopg2 escape hatch in the dedicated TLS contract. To exercise the official driver, run on Linux; GAUSSDB_DRIVER=pg8000 selects the pure-Python path on any platform.

Source checkouts

Wheels ship the vendored libpq; a git checkout does not. Populate it once before running anything against a real server:

python scripts/fetch_vendor_libpq.py

The script extracts libpq from a digest-pinned openGauss image and replaces its old OpenSSL build with checksum-pinned, security-maintained openEuler 22.03 LTS SP4 packages. It supports one or both architectures (--arch x86_64|aarch64|all), so Docker must be available. Exact image/RPM provenance is recorded in datus_gaussdb/_vendor/README.md.