clickhouse-pydantic-config

ClickHouse Pydantic 配置

使用环境变量作为唯一事实来源（SSoT），从 Pydantic v2 模型生成 DBeaver 数据库客户端配置。

架构文档原则：ClickHouse 表/列 COMMENT 是说明每列含义及其计算方式的唯一事实来源。完整的 COMMENT 策略请参见 quality-tools:clickhouse-architect。

自我演进的技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

在以下情况下使用此技能：

• 设置 ClickHouse 数据库的 DBeaver 连接
• 根据环境变量生成数据库客户端配置
• 管理本地与云端 ClickHouse 连接配置
• 自动生成 DBeaver data-sources.json

核心设计原则：半规范化适配

此技能不是僵化的模板。 它提供了一种必须根据各个代码库的结构和本地数据库情况进行调整的 SSoT 模式。

为什么这很重要

每个代码库都有其独特之处：

• 目录布局（.dbeaver/ 的位置可能有所不同）
• 环境变量命名约定
• 现有的连接管理模式
• 本地数据库与云端数据库的组合

SSoT 原则是恒定的；实现细节则因情况而异。

快速开始

# Generate local connection config
uv run scripts/generate_dbeaver_config.py --output .dbeaver/data-sources.json

# Generate cloud connection config
uv run scripts/generate_dbeaver_config.py --mode cloud --output .dbeaver/data-sources.json

# Preview without writing
uv run scripts/generate_dbeaver_config.py --dry-run

# Launch DBeaver
open -a DBeaver

凭据前提条件（云端模式）

使用云端模式前，请通过以下技能链获取凭据：

1. 创建/检索用户：使用 clickhouse-cloud-management 技能创建只读用户，或从 1Password 检索现有凭据
2. 存储在 .env 中：添加到 .env 文件（已加入 gitignore）：

CLICKHOUSE_USER_READONLY=your_user
CLICKHOUSE_PASSWORD_READONLY=your_password

1. 生成配置：运行 uv run scripts/generate_dbeaver_config.py --mode cloud

技能链：clickhouse-cloud-management → .env → clickhouse-pydantic-config

将环境变量作为唯一事实来源

所有可配置值都是环境变量；请在 shell 中导出这些变量，或将它们保存在已加入 gitignore 的 .env 文件中：

export CLICKHOUSE_NAME=clickhouse-local
export CLICKHOUSE_MODE=local  # "local" or "cloud"
export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_DATABASE=default

脚本通过 os.environ.get() 读取变量，并提供向后兼容的默认值，因此所有变量都是可选的。

按模式处理凭据

模式	处理方式	原因
本地	硬编码 default 用户，密码留空	使用零阻力，无安全顾虑
云端	从 .env 预先填充	从环境读取，写入已加入 gitignore 的 JSON

核心原则：生成的 data-sources.json 本身已加入 gitignore。预先填充凭据以零安全风险换取最高的开发者便利性。

云端凭据设置

# .env (gitignored)
CLICKHOUSE_USER_READONLY=readonly_user
CLICKHOUSE_PASSWORD_READONLY=your-secret-password

代码库适配工作流

实施前探索（阶段 0）

在编写任何代码之前，执行者必须：

# 1. Discover existing configuration patterns
fd -t f ".env*" .
fd -t d ".dbeaver" .

# 2. Test ClickHouse connectivity (local)
clickhouse-client --host localhost --port 9000 --query "SELECT 1"

# 3. Check for existing connection configs
fd -t f "data-sources.json" .
fd -t f "dataSources.xml" .

适配决策矩阵

探索发现	适配操作
代码库根目录已有 .env	在其中扩展 CLICKHOUSE_* 变量，不要新建文件
已有 .dbeaver/ 目录	合并连接，并保留现有条目
CLICKHOUSE\_\* 变量命名不标准	映射到代码库的命名约定
有多个数据库（本地 + 云端）	生成多个连接条目
无法使用 ClickHouse	发出警告并生成占位配置

验证清单（生成后）

执行者必须验证：

• 生成的 JSON 有效（jq . .dbeaver/data-sources.json）
• DBeaver 可以导入配置（启动并确认连接已显示）
• 生成器运行无错误（uv run scripts/generate_dbeaver_config.py --dry-run）
• 已将 .dbeaver/ 添加到 .gitignore

Pydantic 模型

ClickHouseConnection 模型提供：

• 类型安全的配置，并通过 Pydantic v2 进行验证
• 用于 JDBC URL 和连接 ID 的计算字段
• 模式感知的默认值（cloud 模式会在端口 8443 上自动启用 SSL）
• 通过 from_env() 类方法加载环境变量

完整的模型文档请参阅 references/pydantic-model.md。

DBeaver 格式

DBeaver 使用 .dbeaver/data-sources.json，其结构如下：

{
  "folders": {},
  "connections": {
    "clickhouse-jdbc-{random-hex}": {
      "provider": "clickhouse",
      "driver": "com_clickhouse",
      "name": "Connection Name",
      "configuration": { ... }
    }
  }
}

重要提示：DBeaver 不支持 ${VAR} 替换——必须在生成时预先填充值。

完整的格式规范请参阅 references/dbeaver-format.md。

macOS 说明

1. DBeaver 二进制文件：使用 /Applications/DBeaver.app/Contents/MacOS/dbeaver（不要使用 open -a）
2. Git 忽略规则：将 .dbeaver/ 添加到 .gitignore

相关技能

技能	集成
devops-tools:clickhouse-cloud-management	cloud 模式下的凭据检索
quality-tools:clickhouse-architect	架构设计背景

Python 驱动策略

对于连接 ClickHouse 的 Python 应用代码（而非 DBeaver），请使用 clickhouse-connect（官方 HTTP 驱动）。请参阅 clickhouse-architect，了解：

• 推荐的代码模式
• 为什么不应使用 clickhouse-driver（社区驱动）
• 性能与维护之间的权衡

其他资源

参考资料	内容
references/pydantic-model.md	完整的模型文档
references/dbeaver-format.md	DBeaver JSON 格式规范

---

故障排除

问题	原因	解决方案
DBeaver 无法连接	端口不匹配（8123 与 9000）	HTTP 使用 8123，原生协议使用 9000——请检查配置
凭据未加载	未加载 .env	运行 set -a; source .env; set +a，然后重新运行
JSON 验证失败	data-sources.json 无效	使用 jq . .dbeaver/data-sources.json 验证
Cloud SSL 错误	端口 8443 上未启用 SSL	Cloud 模式会自动启用 SSL——请确认端口为 8443
.dbeaver/ 被提交到 Git	缺少 gitignore 条目	将 .dbeaver/ 添加到 .gitignore
连接 ID 冲突	连接名称重复	每个连接都需要唯一 ID（随机十六进制值）
配置未更新	DBeaver 缓存	重启 DBeaver 以重新加载 data-sources.json

执行后复盘

此技能执行完毕后，请在结束前检查：

1. 命令是否成功？——如果没有，请修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？——如果底层工具的接口发生变化，请更新用法示例和参数表，使其保持一致。
3. 是否需要变通处理？——如果必须临时采用其他方式（不同的标志、额外步骤），请更新此 SKILL.md，避免下次调用时再次遇到相同问题。

仅在问题确实存在且可复现时进行更新，不要基于猜测更新。