Redshift 连接器¶

Dosi 使用官方 AWS Rust SDK，通过 Amazon Redshift Data API 执行 Redshift SQL。源码构建需启用 exec-redshift；exec-all 和 exec-all-lean 已包含此功能。

实验性

支持 Provisioned 集群和 Serverless workgroup。结果通过 JSON 行传输；Arrow 输出使用 Dosi 的公共行转换。真实云端验收需显式开启，普通 CI 不创建 AWS 资源。

连接配置¶

datasources:
  redshift:
    type: redshift
    cluster_identifier: analytics          # Provisioned
    # workgroup_name: analytics            # Serverless：改用此字段
    database: dev
    schema: public
    aws:
      region: us-east-1
      profile: analytics                   # 可选 AWS 共享 profile
    secret_arn: ${REDSHIFT_SECRET_ARN}       # 可选；使用 IAM 身份时省略

cluster_identifier 和 workgroup_name 必须且只能设置一个。Data API 使用 HTTPS，无需为 Dosi 开放数据库入站连接。包含 host、port、uri、password、ssl、sslmode 或 sslrootcert 的 TCP 配置需转换成上面的 Data API 配置。

认证¶

AWS 凭证使用可刷新的 SDK provider：环境变量、共享 profile、assume-role profile、Web Identity 或容器/实例身份。指定 aws.profile 会明确选择该 profile 及其角色链。SSO profile 通过 AWS CLI 配置，并在运行 Dosi 前登录。

数据库认证有两种方式：

Secrets Manager：设置 secret_arn。secret 提供数据库用户名和密码，Dosi 配置中省略 username。AWS 身份需有读取 secret 及调用 Data API 的权限。
IAM 身份：省略 secret_arn。Provisioned 可设置 username 选择已有数据库用户，需要 redshift:GetClusterCredentials；不指定用户时使用 IAM 派生身份，需要 redshift:GetClusterCredentialsWithIAM。Serverless 从 IAM 派生用户，需要 redshift-serverless:GetCredentials，省略 username。

AWS 身份还需具有目标资源的 redshift-data:BatchExecuteStatement、DescribeStatement、GetStatementResult 和 CancelStatement 权限。数据库授权仍然有效。参见 Data API 认证。

参数¶

参数	默认值	含义
`database`	必填	Redshift 数据库。
`schema`	未设置	未限定表名的搜索路径；模型中已限定的表名仍优先。
`cluster_identifier` / `workgroup_name`	二选一必填	Provisioned 集群 / Serverless workgroup。
`secret_arn`	未设置	Secrets Manager 数据库凭证。
`username`	未设置	仅用于 Provisioned IAM 数据库用户。
`aws.region`	SDK region 链	AWS 区域；平铺别名为 `region`。
`aws.profile`	SDK provider 链	AWS 共享 profile；平铺别名为 `profile_name`。
`aws.ca_bundle`	SDK 信任根	AWS HTTPS 的 PEM CA bundle；平铺别名为 `ca_bundle`。
`iam`	自动推断	可选校验提示：`false` 需要 `secret_arn`；`true` 与其互斥。
`statement_name_prefix`	`dosi`	1–128 个 ASCII 字母、数字、`_` 或 `-`；Dosi 自动追加唯一 ID。
`timeout_seconds`	`30`	每次 AWS API 调用预算。
`query_timeout_seconds`	`600`	提交及数据库执行预算。
`result_timeout_seconds`	`60`	独立的结果分页预算。
`cancel_timeout_seconds`	`10`	取消或提交状态不确定时的清理预算；零表示不执行清理。
`poll_interval_seconds`	`1`	查询状态轮询间隔。
`max_rows`	`10000`	最大返回行数；超限则查询失败。
`max_result_bytes`	`16777216`	规范化结果值的最大字节数；超限则查询失败。

超时参数支持小数秒，上限为 86400 秒。嵌套与平铺的 AWS 配置冲突时会报错。AWS access key 应交由凭证 provider 管理。

执行与诊断¶

每次查询使用独立的 batch/session，在执行生成 SQL 前设置 UTC、带引号标识符的大小写及 schema。并发查询不共享 session。批量脚本按每组最多 37 条应用语句拆分，每组独立提交。

执行器读取全部结果页。NULL 与空字符串保持区别；精度超出浮点数能力的 decimal 保留为精确文本。日期及时间戳使用公共 UTC 规范化逻辑。结果超限时返回错误。

取消操作使用已提交的 statement ID，并在清理预算内轮询终态。超时错误中的 execution_info 会记录取消已确认、取消时查询已完成，或无法确认清理等情况。SQL 失败保留 Redshift 原始错误及 statement/substatement ID，语料测试报告会将这些诊断与生成 SQL 一并保存。

Redshift 会拒绝按值计算的 RANGE 窗口 frame，既有的双参数 CORR/COVAR 窗口限制也仍然有效。这些失败会保留在执行报告中。算术生成会保留整数和 decimal 输入的平均值及除法结果中的小数。

验证连接¶

$ dosi query --model model.yaml --metrics revenue --group-by orders.status \
    --execute --connections connections.yaml --connection redshift

构建未包含该功能时会提示 feature 错误。认证错误需检查选中的 AWS profile 和数据库授权。SQL 拒绝保留为 Redshift 错误：能够生成 SQL，不代表 Redshift 支持全部 PostgreSQL 函数或类型。