跳转至

Hologres 连接器

阿里云 Hologres 讲 PostgreSQL 线协议，所以它复用和 PostgreSQL 连接器同一套驱动，解码策略也原样继承：prepare 拿类型 OID、文本方式取值、会话固定 UTC。编译出的 SQL 按 PostgreSQL 生成。

有三件事是 Hologres 特有的：Endpoint 自带端口、凭据是 AccessKey 对、多语句脚本要逐条发送。由 exec-hologres 控制。

连接配置

datasources:
  hologres:
    type: hologres
    host: ${HOLOGRES_HOST}                    # 也可以写成 host:port
    port: ${HOLOGRES_PORT:-80}
    username: ${HOLOGRES_ACCESS_KEY_ID}       # 别名：access_key_id
    password: ${HOLOGRES_ACCESS_KEY_SECRET}   # 别名：access_key_secret
    database: ${HOLOGRES_DATABASE}
    schema: public                            # 默认值
    sslmode: disable                          # 公网 :80 Endpoint 是明文的

参数

键 类型 必填 默认 说明
type string 是 — hologres
host string 是 — <instance>.hologres.aliyuncs.com，可以带 :port。带上 URI scheme、用户信息或路径会直接报错——这里要的是主机名，不是 URL。
port int 否 80 Hologres 对外公布的端口，不是 5432。host: 里的端口和 port: 必须一致。
username / access_key_id string 否 — 互为别名。两种拼写同时写会报错。
password / access_key_secret string 否 — 同样互为别名。尽量用 ${VAR}。
database string 否 —
schema string 否 public 固定 search_path。
uri string 否 — 完整的 postgres:// DSN。它会取代那些离散键，并跳过上面的 Endpoint 规整逻辑，所以端口要在 DSN 里写对。
sslmode string 否 prefer 与 PostgreSQL 同一套阶梯。
sslrootcert path 否 — 校验类模式必填。
default bool 否 false 见连接配置。

本连接器解析但不使用的键： arrow_flight_port、compat_mode、account、role、warehouse、catalog。

AccessKey 那两个拼写是 Hologres 专用的：在别的 type: 上写 access_key_id: 会报错，而不是把凭据悄悄丢掉。

认证

凭据是一对阿里云 AccessKey。写成 username/password 或 access_key_id/access_key_secret 都行——只用一种，别两种都写。

TLS

与 PostgreSQL 完全相同的 sslmode/sslrootcert 阶梯。注意公网 Hologres Endpoint 在 80 端口上是明文的，所以那里通常就是 sslmode: disable；走 TLS 终结的 Endpoint 时再用校验类模式。

已知限制

  • 批量执行不是事务性的。 Hologres 拒绝在同一个事务里混用 DDL 和 DML，所以多语句脚本会被切开（切分时会正确跳过字符串字面量、带引号的标识符、美元引号块和注释），在同一条连接上逐条发送。脚本跑到一半失败时，前面已经执行的语句不会回滚。
  • DATEDIFF 存在，但单位参数在最后。 Hologres 写作 DATEDIFF(end, start, 'day')，而模型是单位在前的写法。编译器会替你旋转参数顺序，一次把单位位置和正负号都修正；已经按 Hologres 写法写的调用则原样保留。它的单位词汇表是个子集——没有 week，没有 quarter。
  • C collation。 文本按字节排序，所以 ORDER BY 的结果可能和默认 en_US.UTF-8 的 PostgreSQL 不一样。这一点与 DuckDB 一致。
  • 整数除法截断，和 PostgreSQL 一样。

UTC 会话固定在这里比在 PostgreSQL 上更要紧：Hologres 的 DATE_TRUNC 不接受 DATE，日期会被拓宽成 TIMESTAMPTZ 并带上时区——而实例默认时区是 PRC（+08）。固定 UTC 才能让时间粒度分桶保持无时区。

本地验证连接

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

排错

报错 原因与处理
datasource "x" (hologres) is missing required field "host" Endpoint 必填；提示里给了格式。
datasource "x": hologres host "https://…" must not include a URI scheme 写裸主机名（可带 :port）。
datasource "x": hologres host "…" must not contain user information AccessKey 放到 username/password，别塞进 host。
datasource "x": hologres endpoint port 80 conflicts with port: 5432 端口写在 host: 或 port: 其中一处，不要两处都写。
datasource "x": sets both "username" and "access_key_id" 两者是别名，只保留一个。password/access_key_secret 同理。
datasource "x": access_key_id/access_key_secret are hologres-only spellings, but type is postgres 其它连接器请用 username:/password:。
server rejected SQL (<code>): <message> Hologres 拒了这条语句；文字是服务端的原话。

参考链接