Skip to content

Hologres connector

Alibaba Cloud Hologres speaks the PostgreSQL wire protocol, so it rides the same driver as the PostgreSQL connector and inherits its decode strategy verbatim: prepare for type OIDs, read values as text, sessions pinned to UTC. Compiled SQL is generated as PostgreSQL.

Three things are Hologres-specific: the endpoint carries its own port, the credentials are an AccessKey pair, and multi-statement scripts are sent one statement at a time. Gated by exec-hologres.

Connection profile

datasources:
  hologres:
    type: hologres
    host: ${HOLOGRES_HOST}                    # or host:port
    port: ${HOLOGRES_PORT:-80}
    username: ${HOLOGRES_ACCESS_KEY_ID}       # alias: access_key_id
    password: ${HOLOGRES_ACCESS_KEY_SECRET}   # alias: access_key_secret
    database: ${HOLOGRES_DATABASE}
    schema: public                            # default
    sslmode: disable                          # public :80 endpoints are plaintext

Parameters

Key Type Required Default Notes
type string yes — hologres
host string yes — <instance>.hologres.aliyuncs.com, optionally with :port. A URI scheme, user info or path is rejected — this is a hostname, not a URL.
port int no 80 The port Hologres publishes, not 5432. A port in host: and a port: key must agree.
username / access_key_id string no — Aliases. Setting both spellings is an error.
password / access_key_secret string no — Aliases, same rule. Prefer ${VAR}.
database string no —
schema string no public Pins search_path.
uri string no — A full postgres:// DSN. It replaces the discrete keys and skips the endpoint normalization above, so the port must be right in the DSN itself.
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, compat_mode, account, role, warehouse, catalog.

The AccessKey spellings are Hologres-only: using access_key_id: on any other type: is an error rather than a silently dropped credential.

Authentication

Credentials are an Alibaba Cloud AccessKey pair. Write them as either username/password or access_key_id/access_key_secret — one spelling, not both.

TLS

The same sslmode/sslrootcert ladder as PostgreSQL. Note that public Hologres endpoints on port 80 are plaintext, so sslmode: disable is the normal setting there; use a verifying mode when your instance is reached over a TLS-terminated endpoint.

Limitations

  • Batches are not transactional. Hologres rejects a transaction that mixes DDL with DML, so a multi-statement script is split (respecting string literals, quoted identifiers, dollar-quoted bodies and comments) and sent statement by statement on the same connection. A script that fails halfway leaves the earlier statements applied.
  • DATEDIFF exists, with the unit last. Hologres spells it DATEDIFF(end, start, 'day') where models are written unit-first. The compiler rotates the argument list for you, fixing unit position and sign together; a call already written in Hologres' spelling is left alone. The unit vocabulary is a subset — no week, no quarter.
  • C collation. Text sorts by byte, so ORDER BY on text can differ from a stock en_US.UTF-8 PostgreSQL. This matches DuckDB.
  • Integer division truncates, as on PostgreSQL.

The UTC session pin matters more here than on PostgreSQL: Hologres does not accept DATE for DATE_TRUNC, so a date widens to TIMESTAMPTZ and carries a zone — and instances default to PRC (+08). The pin keeps time-grain buckets zone-less.

Verify the connection

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

Troubleshooting

Message Cause and fix
datasource "x" (hologres) is missing required field "host" The endpoint is mandatory; the hint shows the shape.
datasource "x": hologres host "https://…" must not include a URI scheme Give a bare hostname (with an optional :port).
datasource "x": hologres host "…" must not contain user information Put the AccessKey in username/password, not in the host.
datasource "x": hologres endpoint port 80 conflicts with port: 5432 Set the port in host: or in port:, not both.
datasource "x": sets both "username" and "access_key_id" They are aliases — keep exactly one. Same for password/access_key_secret.
datasource "x": access_key_id/access_key_secret are hologres-only spellings, but type is postgres Use username:/password: on other connectors.
server rejected SQL (<code>): <message> Hologres refused the statement; the text is the server's.

Reference