Skip to content

GaussDB / openGauss connector

Huawei GaussDB and openGauss are PostgreSQL-derived, so compiled SQL is generated as PostgreSQL and the decode strategy is the PostgreSQL connector's verbatim.

The wire protocol is what sets them apart. GaussDB replaces PostgreSQL's SASL authentication with a private SHA256 handshake whose auth-code numbers collide with PostgreSQL's — stock drivers (libpq, tokio-postgres) fail before the password is checked. This connector therefore uses a dedicated driver that speaks that handshake natively, which means servers with pg_hba method sha256 — the production default — work with no server-side change.

Gated by exec-gaussdb.

Connection profile

datasources:
  gaussdb:
    type: gaussdb
    host: gauss.internal
    port: 8000                       # GaussDB(DWS) default; openGauss uses 5432
    username: dosi
    password: ${GAUSSDB_PASSWORD}
    database: analytics
    schema: main                     # optional
    compat_mode: PG                  # optional: PG | A | B — verified on connect
    sslmode: require                 # managed instances enable ssl=on
    # sslrootcert: /etc/ssl/gauss-ca.pem   # only for verify-ca / verify-full

Parameters

Key Type Required Default Notes
type string yes — gaussdb — also the value for openGauss.
host string yes* — *Unless uri: is given.
port int no driver default GaussDB(DWS) commonly 8000, openGauss 5432.
username string no —
password string no — Prefer ${VAR}. See authentication for the storage rules.
database string no —
schema string no — Pins search_path.
uri string no — A postgres:// DSN. It replaces the discrete connection keys; an explicit sslmode: still wins over the DSN's.
compat_mode string no — PG, A or B. When set, the executor probes the database on first connect and refuses to run on a mismatch.
sslmode string no prefer Same ladder as PostgreSQL.
sslrootcert path no — Required by the verifying modes.
default bool no false See connection profiles.

Parsed and ignored on this connector: arrow_flight_port, account, role, warehouse, catalog.

Authentication

What works depends on the server's pg_hba method and on how the account's password is stored (password_encryption_type at the time the password was set):

password storage hba md5 sha256
MD5 (type=0) works works (server falls back to MD5)
SHA256 (type=2, the default) rejected with a hint¹ works, native SHA256
MD5 + SHA256 (type=1) works works, native SHA256

¹ In that combination the server omits the PBKDF2 iteration count from the handshake, so no client can derive the key. The error says so: re-set the password under password_encryption_type = 1 (dual storage), or switch the hba method to sha256. SM3-stored passwords (type=3) are rejected the same way.

TLS

The same sslmode/sslrootcert ladder as PostgreSQL. Managed Huawei-cloud instances typically enable ssl=on with a self-signed certificate, where sslmode: require is the right setting.

Compatibility modes

A GaussDB database is created in PG, A (Oracle-style — the GaussDB default) or B (MySQL-style) compatibility mode; newer kernels add M (full MySQL).

PG, A and B are supported. Declare which one you expect with compat_mode: and the executor verifies it on first connect, failing loudly on a mismatch — a wrong assumption changes query semantics silently, which is worse than a refusal.

M-compatibility databases are refused at connect: M is not a semantic variant but a different SQL dialect, where even CAST(x AS varchar) is a syntax error, so PostgreSQL-dialect SQL cannot run there.

Two mode-specific semantics live in the stored data rather than in queries, so they are declared rather than rewritten:

  • In A mode the empty string is NULL — writing '' stores NULL and col = '' never matches. Use col = '' OR col IS NULL for a portable emptiness test.
  • In B mode string equality ignores trailing spaces (MySQL PAD SPACE), and ORDER BY sorts NULLs first ascending.

Limitations

  • No 3-argument DATEDIFF, inherited from PostgreSQL: the same SQLSTATE 42883 rejection, so a metric using it is refused at compile time for this dialect.
  • Integer division yields reals in every compatibility mode — a kernel behavior, not a mode behavior, and the opposite of stock PostgreSQL.

Verify the connection

$ dosi query --model model.yaml --metrics revenue --execute --connection gaussdb

A compat_mode: mismatch surfaces here rather than in wrong numbers later.

Troubleshooting

Message Cause and fix
An auth error carrying the hint about password_encryption_type The hba-method × password-storage combination in the table above cannot work. Re-set the password under password_encryption_type = 1, or switch the hba method to sha256.
connection "x": the database reports DBCOMPATIBILITY 'A' but the profile declares compat_mode: PG Fix compat_mode:, or point the profile at a database created with the declared mode.
connection "x": DBCOMPATIBILITY 'M' databases speak MySQL-dialect SQL, which this executor's PostgreSQL-dialect pipeline cannot target Use a PG, A or B database.
connection "x": bad url: <e> The uri: is not a valid postgres:// DSN.
this build has no gaussdb executor (feature "exec-gaussdb" not enabled) Published binaries include it; a hand-built one needs --features exec-gaussdb.

Reference