接入数据库

Cappy 连接数据库，将表结构、描述和示例数据行同步为上下文文件。Agent 读取这些文件理解数据，再通过对应连接执行 SQL，取得查询结果。

在项目根目录的 config.yaml 中配置 databases。本文先用 Doris 说明通用配置，再列出每种数据库的完整示例和对应参数，最后说明如何同步、检查文件和选择表。

支持的数据库复制锚点链接

通用参数复制锚点链接

以下示例连接 Doris 的 internal Catalog，同步 analytics 库中的表，排除 tmp_ 开头的临时表：

databases:
  - name: warehouse
    type: doris
    host: doris.example.com
    port: 9030
    user: analytics_reader
    password: {{ env('DORIS_PASSWORD_YAML') }}
    catalog: internal
    database: analytics
    schema_name: analytics
    include:
      - analytics.*
    exclude:
      - analytics.tmp_*
    allow_listed_only: true
    templates:
      - columns
      - preview

地址、库名和账号都是示例值，需替换为自己的数据库信息。analytics_reader 表示已有且具备读取权限的数据库账号，Cappy 不会自动创建它。已有 databases 时，在同一个列表中添加连接，不要重复写顶层键。

所有数据库共用以下参数，连接地址和认证字段见数据库参数。

提供密码和 Token复制锚点链接

示例用 env() 从运行环境读取凭据。Cappy 会先替换文本，再解析 YAML。为保留密码中的引号、反斜杠或换行，本文使用以 _YAML 结尾的环境变量，存放经过 JSON 字符串编码的值：

export DORIS_PASSWORD_YAML="$(python3 -c 'import getpass, json; print(json.dumps(getpass.getpass("Doris password: ")))')"

在安装了 Python 3 的环境中执行，按提示输入密码；输入不会显示。配置中使用 password: {{ env('DORIS_PASSWORD_YAML') }}，不要再加外层引号。其他数据库的密码、Token 和私钥口令使用同样的方法，将变量名替换为对应示例中的名称。

执行同步和查询的环境都需要设置这些变量。凭据文件、数据库文件和私钥路径也必须能被相应进程读取；不要把本机路径直接当作服务器路径。

限制查询范围复制锚点链接

include 和 exclude 决定哪些表进入上下文；allow_listed_only: true 进一步限制查询只能引用这些已同步的表。该检查同时适用于 Agent 生成的 SQL 和用户编辑后执行的 SQL，遇到范围外的表或无法安全解析的查询时会阻止执行。

启用后先完成同步，再发起查询。只向数据库账号授予所需的权限。Cappy 当前没有 exclude_columns 配置；若需要隐藏特定字段，应在数据库中提供仅含允许字段的视图，并将连接权限和同步范围限定到这些视图。

同步模板复制锚点链接

templates 决定每张表生成哪些文件：

只需要表结构、不想保存示例数据行时，明确写 templates: [columns]。省略 templates 或写 templates: [] 都会生成 columns 和 preview。cappy init 如果同时配置了模型，还会为连接加入 ai_summary；可在同步前调整。

如果使用旧配置，将 accessors 改为 templates，将模板名称 how_to_use 改为 query_history，并删除 description 这一项。表描述已并入 columns.md。删除模板配置不会自动移除以前生成的文件；不再需要这些内容时，也要删除对应旧文件。

查询历史复制锚点链接

在已有连接中启用 query_history，即可将常见用法作为上下文。将下面这些字段添加到这条数据库连接的配置中：

query_history_days: 30
templates:
  - columns
  - preview
  - query_history
query_history_exclude_patterns:
  - 'SYSTEM\$'
  - '^SELECT CURRENT_SESSION\(\)'
  - '^SHOW '

Cappy 为 BigQuery、Snowflake、Databricks、PostgreSQL 和 Redshift 内置了读取查询历史的 SQL。PostgreSQL 读取 pg_stat_statements，需要启用扩展并授予读取权限；它记录的是累计统计，不会按 query_history_days 筛选时间范围。其他连接器需要自定义 query_history_sql 才能读取自己的审计表。没有可用历史时，生成文件会说明未找到历史记录。

例如，Snowflake 连接可通过自定义 SQL 只保留成功的查询：

query_history_days: 14
query_history_sql: |
  SELECT query_text
  FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY
  WHERE start_time >= DATEADD(day, -{days}, CURRENT_TIMESTAMP())
    AND execution_status = 'SUCCESS'
    AND query_type = 'SELECT'
  LIMIT 10000

查询必须返回 query_text 列，连接账号需要相应系统表权限。query_history_exclude_patterns 在读取后过滤 SQL：只要匹配其中一个表达式，就排除该查询，终端会显示排除数量。停止读取历史时，从 templates 中移除 query_history。

数据统计复制锚点链接

在连接中添加 profiling 模板，并按需要设置刷新周期：

templates: [columns, preview, profiling]
profiling:
  refresh_policy: interval
  interval_days: 7

统计支持普通字段及数组、结构、JSON 等复杂类型；具体统计项取决于字段类型和连接器。大表可先只同步 columns、preview，再为需要分析分布的表启用统计。

AI 摘要复制锚点链接

AI 摘要使用运行 cappy sync 的终端环境中的模型设置。例如，使用 OpenAI 时：

export CAPPY_LLM_PROVIDER='openai'
export CAPPY_LLM_MODEL='your-model-id'
export OPENAI_API_KEY='your-api-key'

将 your-model-id 和 your-api-key 换为供应商提供的实际值。CAPPY_LLM_PROVIDER 选择供应商，CAPPY_LLM_MODEL 指定摘要模型，认证使用该供应商的环境变量。这些设置与 Web 的组织 LLM 配置分别生效。

再在数据库连接中启用摘要，下面的字段属于该连接：

templates: [columns, preview, ai_summary]
ai_summary:
  refresh_policy: interval
  interval_days: 7

摘要使用与 profiling 相同的刷新参数，默认每次同步重新生成。即使未生成 profiling.md 或 preview.md，摘要仍会读取统计结果和示例数据行（最多 10 行），并将这些材料发送给配置的模型。摘要根据统计结果判断数据质量和分布；示例数据行只用于帮助理解，不能代表整张表的数据分布。

数据库参数复制锚点链接

以下每个 YAML 都是一条完整连接的配置示例。保留项目其他配置，只将所需连接加入 databases。示例都指定了要同步的库或 Schema，避免第一次同步就遍历大量无关表；按实际对象名称修改。

Doris复制锚点链接

Doris 使用 FE 的 MySQL 协议端口。基本配置如下；需要筛选表、读取示例数据行或限制查询范围时，可采用前面的通用配置。

databases:
  - name: doris_prod
    type: doris
    host: doris.example.com
    port: 9030
    user: analytics_reader
    password: {{ env('DORIS_PASSWORD_YAML') }}
    catalog: internal
    database: analytics
    schema_name: analytics

设置 schema_name 后只同步该库；未设置 catalog 时，使用 internal Catalog 下的同名库。不设置 schema_name 时，Cappy 列出指定 Catalog 中的库；两者都不填时，Cappy 列出账号有权访问的 Catalog 和库。为外部 Catalog 配置时，将 catalog 改为其名称，database 和 schema_name 填其中的库名。

include / exclude 同时支持 analytics.orders 和 internal.analytics.orders。数据库上下文目录中的 Schema 包含 Catalog，例如 schema=internal.analytics。

StarRocks复制锚点链接

databases:
  - name: starrocks_prod
    type: starrocks
    host: starrocks.example.com
    port: 9030
    user: analytics_reader
    password: {{ env('STARROCKS_PASSWORD_YAML') }}
    catalog: default_catalog
    database: analytics
    schema_name: analytics

范围选择方式与 Doris 相同，但默认 Catalog 为 default_catalog。Cappy 的字段是单个 catalog，不是 catalogs 列表。需要分别限制多个 Catalog 的范围时，添加名称不同的连接。将 type 设为 starrocks，Cappy 才能正确读取 StarRocks 的表结构等信息。

PostgreSQL复制锚点链接

databases:
  - name: postgres_prod
    type: postgres
    host: postgres.example.com
    port: 5432
    database: analytics
    user: analytics_reader
    password: {{ env('POSTGRES_PASSWORD_YAML') }}
    schema_name: public

例如只需要 public 中的订单表，可添加 include: [public.orders]。database 是数据库名，schema_name 是库内命名空间，两者不要混填。Cappy 的 PostgreSQL 配置未提供 sslmode 字段，不要套用后面的 Redshift 参数。

MySQL复制锚点链接

databases:
  - name: mysql_prod
    type: mysql
    host: mysql.example.com
    port: 3306
    database: analytics
    schema_name: analytics
    user: analytics_reader
    password: {{ env('MYSQL_PASSWORD_YAML') }}

MySQL 的 Schema 对应数据库。像示例一样同时填写 database 和 schema_name，即可将默认查询库与同步库设为同一个库。

ClickHouse复制锚点链接

默认使用 HTTP 接口。以下示例通过 HTTPS 连接：

databases:
  - name: clickhouse_prod
    type: clickhouse
    host: clickhouse.example.com
    protocol: http
    port: 8443
    database: analytics
    user: analytics_reader
    password: {{ env('CLICKHOUSE_PASSWORD_YAML') }}
    secure: true
    include: [analytics.*]
    connect_timeout: 10
    send_receive_timeout: 120

如果服务只开放 native 协议，将连接中的相关字段改为：

protocol: native
port: 9440
secure: true
verify: true

verify: false 会跳过 native TLS 证书检查，仅在明确接受这一行为的环境使用。database 不限制同步时查找库表的范围；通过 include: [analytics.*] 选择库。对于系统表不可读的受限连接，使用精确表名，例如：

tolerate_unreadable_system_tables: true
include:
  - analytics.events
  - analytics.users

无法读取系统表时，Cappy 不能查出通配符匹配的表，因此需要逐个填写表名。ClickHouse 的排序键、分区键、主键和 Projection 等可读取的定义写入 columns.md，无需另加索引模板。

DuckDB复制锚点链接

databases:
  - name: warehouse_local
    type: duckdb
    path: ./analytics.duckdb
    include: [main.*]

相对路径以运行项目的目录为基准。文件连接只读，连接后关闭外部文件和网络访问，并锁定配置；该连接不能读取其他本地文件、远程 URL 或 ATTACH 其他数据库。运行实例也需要能读取同一数据库文件。

不要将连接命名为 duckdb_local：这是 Cappy 内置文件查询引擎使用的名称。

MotherDuck复制锚点链接

databases:
  - name: motherduck_prod
    type: motherduck
    database: analytics
    token: {{ env('MOTHERDUCK_TOKEN_YAML') }}
    include: [main.*]

直接使用 MOTHERDUCK_TOKEN 环境变量时，变量保存原始 Token，不做 _YAML 编码，并从配置中省略 token。Cappy 自动构造 MotherDuck 连接路径；已有 type: duckdb 加 md: 路径的配置仍可使用。MotherDuck 需要访问远程服务，不使用本地 DuckDB 的外部访问限制。

BigQuery复制锚点链接

databases:
  - name: bigquery_prod
    type: bigquery
    project_id: company-data-prod
    dataset_id: analytics
    credentials_path: /etc/cappy/credentials/bigquery.json
    location: US
    max_query_size: 5
    partition_filters:
      events: "event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)"

可以使用服务账号文件、credentials_json 对象或环境中的 ADC 完成认证。使用本地交互认证时，移除凭据文件字段并设置 sso: true；无人值守环境应提供无需浏览器交互的有效凭据。

max_query_size 为正数时，执行 SQL 前会先估算扫描的数据量（dry run），超出上限就拒绝该查询，并返回估算量和上限。它不替代同步模板的成本控制，也不限制其他数据库。

partition_filters 的键是表名，例如 events，不是 analytics.events。设置后，读取示例数据行时会使用这些条件替代自动生成的分区筛选条件，但不会改写用户的所有查询。同步的 columns.md 分别记录分区列与聚簇列，并尽可能保留 BigQuery 原生类型，例如 DATETIME、TIMESTAMP 和 INT64。

Snowflake复制锚点链接

databases:
  - name: snowflake_prod
    type: snowflake
    account_id: xy12345.us-east-1
    username: analytics_reader
    password: {{ env('SNOWFLAKE_PASSWORD_YAML') }}
    database: ANALYTICS
    warehouse: COMPUTE_WH
    schema_name: PUBLIC

按账号启用的方式选择认证。以下片段替换连接中的 password 字段，其余连接参数保留。

密钥对认证：

private_key_path: /etc/cappy/credentials/snowflake.p8
passphrase: {{ env('SNOWFLAKE_KEY_PASSPHRASE_YAML') }}

未加密私钥省略 passphrase；需要直接填写 PEM 私钥内容时，使用 private_key: {{ env('SNOWFLAKE_PRIVATE_KEY_YAML') }}，其中变量采用前述 JSON 字符串编码以保留换行。

浏览器 SSO：

authenticator: externalbrowser

Programmatic Access Token（PAT）：

authenticator: programmatic_access_token
token: {{ env('SNOWFLAKE_PAT_YAML') }}

同步时也会读取可访问的 Snowflake semantic views，将指标、维度和关系写入 schema=<schema>/semantic_view=<name>/definition.md。没有可用 semantic views 时跳过，不需要另设配置。

Databricks复制锚点链接

databases:
  - name: databricks_prod
    type: databricks
    server_hostname: adb-1234567890123456.7.azuredatabricks.net
    http_path: /sql/1.0/warehouses/abc123
    access_token: {{ env('DATABRICKS_TOKEN_YAML') }}
    catalog: main
    schema_name: analytics

如果 analytics 只有读取权限，而查询需要暂存数据，可以在同一连接增加：

temp_schema: scratch

此时 scratch 成为连接的默认 Schema，schema_name: analytics 仍决定同步范围。scratch 需要事先存在，并向连接账号授予所需写入权限。

SQL Server复制锚点链接

databases:
  - name: mssql_prod
    type: mssql
    host: sqlserver.example.com
    port: 1433
    database: analytics
    user: analytics_reader
    password: {{ env('MSSQL_PASSWORD_YAML') }}
    schema_name: dbo
    driver: ODBC Driver 18 for SQL Server

driver 仅选择驱动，不会安装它。同步和查询的运行环境都需提供对应 ODBC 驱动；驱动名称必须与安装名称一致。该连接的 type 为 mssql，不是 sqlserver。

Fabric复制锚点链接

从 Warehouse 或 Lakehouse 的连接信息中复制 SQL 端点地址。以下示例使用 Azure CLI 登录身份：

databases:
  - name: fabric_prod
    type: fabric
    host: workspace.datawarehouse.fabric.microsoft.com
    port: 1433
    database: analytics
    schema_name: dbo
    auth_mode: azure_cli
    driver: ODBC Driver 18 for SQL Server

需要让服务自动运行、无需手动登录时，将示例中的 auth_mode 替换为以下字段：

auth_mode: azure_service_principal
client_id: 00000000-0000-0000-0000-000000000001
client_secret: {{ env('FABRIC_CLIENT_SECRET_YAML') }}
tenant_id: 00000000-0000-0000-0000-000000000002

Client ID 和 Tenant ID 为占位值，替换为自己应用的信息。Cappy 使用的字段是 host 和 auth_mode，不是 server 或 auth_method。

Redshift复制锚点链接

databases:
  - name: redshift_prod
    type: redshift
    host: cluster.example.us-east-1.redshift.amazonaws.com
    port: 5439
    database: analytics
    auth_mode: password
    user: analytics_reader
    password: {{ env('REDSHIFT_PASSWORD_YAML') }}
    schema_name: public
    sslmode: require

azure_entra_id 用于已配置 Microsoft Entra ID 身份传递的实例。同步仍需要 user、password 读取元数据；运行时查询必须使用当前登录用户的访问 Token，不会改用同步账号。仅改这一字段不能完成组织登录和数据库联合认证的配置。

如果需经 SSH 跳板机连接，在同一连接下增加：

ssh_tunnel:
  ssh_host: bastion.example.com
  ssh_port: 22
  ssh_username: ec2-user
  ssh_private_key_path: ~/.ssh/id_rsa
  ssh_private_key_passphrase: {{ env('SSH_KEY_PASSPHRASE_YAML') }}

ssh_host、ssh_username、ssh_private_key_path 必填，ssh_port 默认 22。未加密私钥省略 ssh_private_key_passphrase。数据库的 host 仍填从跳板机可访问的 Redshift 地址；SSH 账号与数据库账号是两套凭据。

Athena复制锚点链接

databases:
  - name: athena_prod
    type: athena
    s3_staging_dir: s3://company-query-results/athena/
    region_name: us-east-1
    schema_name: analytics
    work_group: primary
    profile_name: analytics

profile_name 优先于直接填写的访问密钥。改用访问密钥时，移除 profile_name，加入：

aws_access_key_id: {{ env('ATHENA_ACCESS_KEY_ID_YAML') }}
aws_secret_access_key: {{ env('ATHENA_SECRET_ACCESS_KEY_YAML') }}
aws_session_token: {{ env('ATHENA_SESSION_TOKEN_YAML') }}

长期密钥省略 aws_session_token。Profile 和访问密钥都未填写时，AWS 驱动使用运行环境中的认证信息。账号需能执行 Athena 查询、访问所需元数据与数据，并向结果 S3 路径写入查询结果。

Trino复制锚点链接

下面使用 HTTPS 和密码认证。端口应与 Coordinator 实际开放的端口一致：

databases:
  - name: trino_prod
    type: trino
    host: trino.example.com
    port: 8443
    catalog: iceberg
    schema_name: analytics
    user: analytics_reader
    password: {{ env('TRINO_PASSWORD_YAML') }}
    http_scheme: https
    verify: true

使用内部 CA 时，将 verify 改为证书包路径：

verify: /etc/ssl/certs/internal-ca.pem

使用 JWT 时，移除 password，改为以下两种方式之一：

jwt_token: {{ env('TRINO_JWT_YAML') }}

jwt_token_file: /var/run/trino/token

Token 文件保存原始 Token，可由外部程序定期更新。优先级为非空文件中的 Token → jwt_token → password；文件不存在或为空时继续尝试下一项。使用 JWT 会强制 HTTPS，但仍需填写正确的 TLS 端口。

同步时会尝试读取表与列注释，一并加入结构上下文，不需要额外模板。

SQL 方言复制锚点链接

Cappy 根据连接的 type 提供相应的 SQL 指引。例如 SQL Server 和 Fabric 使用 TOP N，BigQuery 使用反引号和 SAFE_DIVIDE，Doris、StarRocks 和 MySQL 使用相应标识符引号规则，Redshift 使用其支持的窗口函数和聚合写法。

因此应填写数据库真实类型，不要仅因兼容某种协议就改成其他 type。连接多个不同数据库时，Agent 按目标连接选择 SQL 写法。

同步数据库复制锚点链接

下面以开头的 Doris 连接 warehouse 为例。my-project 代表已初始化的项目文件夹，其中包含 config.yaml。

cd my-project
cappy debug

cappy sync -p databases:warehouse

my-project/
├── config.yaml
└── databases/
    └── type=doris/
        └── database=internal.analytics/
            └── schema=internal.analytics/
                └── table=orders/
                    ├── annotations.md
                    ├── columns.md
                    └── preview.md

上下文文件复制锚点链接

自动生成的文件在 frontmatter 中带有 type: generated，再次同步时可能覆盖。annotations.md 带有 type: manual，用于补充说明表中每条记录代表什么、字段的业务含义及使用限制；同一张表后续同步时保留已有内容。跨表规则写在 RULES.md。

例如，一张包含 order_id 和 status 字段的订单表，其 columns.md 会包含类似内容。下面数值仅用于说明文件格式：

# orders

**Dataset:** `internal.analytics`

## Description

One row per order.

## Table Metadata

| Property | Value |
|----------|-------|
| **Row Count** | 200 |

## Columns (2)

- order_id (BIGINT)
- status (VARCHAR, "Order status")

preview.md 展示示例数据行，每条记录对应一行 JSON：

# orders - Preview

**Dataset:** `internal.analytics`

## Rows (2)

- {"order_id": 1001, "status": "completed"}
- {"order_id": 1002, "status": "cancelled"}

启用 profiling 后，profiling.md 还会记录计算时间和字段统计。例如：

# orders - Profiling

**Dataset:** `internal.analytics`

**Computed at:** `2026-10-29T00:00:00+00:00`

**Columns:** 2

## Column Profiles (JSONL)

- {"column": "order_id", "type": "BIGINT", "total_count": 200, "null_count": 0, "distinct_count": 200}

这些文件帮助 Agent 查找和理解表，查询结果仍从数据库取得。将配置与上下文按发布流程更新到运行项目后，即可在对话中选择相应数据提问；运行实例需要能访问数据库并取得同样的凭据。

选择表复制锚点链接

include / exclude 使用 glob 通配符匹配 schema.table；Doris 和 StarRocks 也支持 catalog.schema.table。例如，添加到开头的 Doris 连接中：

include:
  - analytics.*
  - marts.fct_*
exclude:
  - analytics.tmp_*
  - marts.fct_*_backup

该配置选择 analytics 下的表和 marts 下以 fct_ 开头的表，再排除临时表与备份表。要同时同步这两个库，还需移除开头的 schema_name: analytics；否则同步范围仍然只有 analytics。名称和大小写应与数据库实际对象一致。

只刷新某张表时，在原配置范围内使用 -s：

cappy sync -p databases:warehouse -s internal.analytics.orders

-s 不扩大 include 或 schema_name 的范围。局部同步时，也不会清理不再使用的表目录。完整同步会清理不再选中的表目录，其中可能包含 annotations.md；删除连接配置也可能清理对应目录，-s 不能阻止整个连接目录的清理。缩小范围或删除连接前，先保存其中需要保留的人工说明。

第一次接入可先选择核心库表和默认模板，核对表结构和示例数据行后再扩展范围；查询历史、统计和摘要按需要加入，避免无用上下文和不必要的查询或模型调用。