clickhouse-pydantic-config

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ClickHouse Pydantic Config

ClickHouse Pydantic 配置生成

Generate DBeaver database client configurations from Pydantic v2 models using mise

[env]

as Single Source of Truth (SSoT).

以mise

[env]

作为单一可信数据源（SSoT），基于Pydantic v2模型生成DBeaver数据库客户端配置。

When to Use This Skill

何时使用该技能

Use this skill when:

Setting up DBeaver connections for ClickHouse databases
Generating database client configurations from environment variables
Managing local vs cloud ClickHouse connection profiles
Integrating ClickHouse with mise-based development workflows
Automating DBeaver data-sources.json generation

在以下场景中使用本技能：

为ClickHouse数据库配置DBeaver连接
从环境变量生成数据库客户端配置
管理本地与云端ClickHouse连接配置文件
将ClickHouse与基于mise的开发工作流集成
自动生成DBeaver的data-sources.json文件

Critical Design Principle: Semi-Prescriptive Adaptation

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

This skill is NOT a rigid template. It provides a SSoT pattern that MUST be adapted to each repository's structure and local database situation.

本技能并非僵化模板。它提供一种SSoT模式，必须根据每个代码库的结构和本地数据库环境进行适配。

Why This Matters

为何这一点很重要

Each repository has unique:

Directory layouts (
```
.dbeaver/
```
location may vary)
Environment variable naming conventions
Existing connection management patterns
Local vs cloud database mix

The SSoT principle is the constant; the implementation details are the variables.

每个代码库都有其独特性：

目录结构（
```
.dbeaver/
```
的位置可能不同）
环境变量命名规范
现有的连接管理模式
本地与云端数据库的混合使用情况

SSoT原则是固定的，实现细节可以灵活调整。

Quick Start

快速开始

bash

undefined

bash

undefined

Generate local connection config

生成本地连接配置

mise run db-client-generate

Generate cloud connection config

生成云端连接配置

mise run db-client:cloud

Preview without writing

预览配置（不写入文件）

mise run db-client:dry-run

Launch DBeaver

启动DBeaver

mise run dbeaver

undefined

mise run dbeaver

undefined

Credential Prerequisites (Cloud Mode)

凭证前置条件（云端模式）

Before using cloud mode, obtain credentials via the skill chain:

Create/retrieve user: Use
```
clickhouse-cloud-management
```
skill to create read-only users or retrieve existing credentials from 1Password
Store in .env: Add to
```
.env
```
file (gitignored):

bash

CLICKHOUSE_USER_READONLY=your_user
CLICKHOUSE_PASSWORD_READONLY=your_password

Generate config: Run
```
mise run db-client:cloud
```

Skill chain:

clickhouse-cloud-management

→

.env

→

clickhouse-pydantic-config

使用云端模式前，需通过技能链获取凭证：

创建/获取用户：使用
```
clickhouse-cloud-management
```
技能创建只读用户，或从1Password中获取现有凭证
存储到.env：将凭证添加到
```
.env
```
文件（已加入git忽略）：

bash

CLICKHOUSE_USER_READONLY=your_user
CLICKHOUSE_PASSWORD_READONLY=your_password

生成配置：运行
```
mise run db-client:cloud
```

技能链：

clickhouse-cloud-management

→

.env

→

clickhouse-pydantic-config

mise

[env]

as Single Source of Truth

以mise

[env]

作为单一可信数据源

All configurable values live in

.mise.toml

toml

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

Scripts read from

os.environ.get()

with backward-compatible defaults—works with or without mise installed.

所有可配置值都存储在

.mise.toml

中：

toml

[env]
CLICKHOUSE_NAME = "clickhouse-local"
CLICKHOUSE_MODE = "local"  # "local" 或 "cloud"
CLICKHOUSE_HOST = "localhost"
CLICKHOUSE_PORT = "8123"
CLICKHOUSE_DATABASE = "default"

脚本通过

os.environ.get()

读取配置，并提供向后兼容的默认值——无论是否安装mise均可正常工作。

Credential Handling by Mode

不同模式下的凭证处理

Mode	Approach	Rationale
Local	Hardcode `default` user, empty password	Zero friction, no security concern
Cloud	Pre-populate from `.env`	Read from environment, write to gitignored JSON

Key principle: The generated

data-sources.json

is gitignored anyway. Pre-populating credentials trades zero security risk for maximum developer convenience.

模式	处理方式	原因说明
本地	硬编码 `default` 用户，空密码	零摩擦，无安全风险
云端	从 `.env` 中预加载凭证	从环境变量读取，写入已加入git忽略的JSON文件

核心原则：生成的

data-sources.json

本来就是git忽略的。预填充凭证不会带来安全风险，同时能最大化开发者的使用便利性。

Cloud Credentials Setup

云端凭证设置

bash

undefined

bash

undefined

.env (gitignored)

.env（已加入git忽略）

CLICKHOUSE_USER_READONLY=readonly_user CLICKHOUSE_PASSWORD_READONLY=your-secret-password

undefined

CLICKHOUSE_USER_READONLY=readonly_user CLICKHOUSE_PASSWORD_READONLY=your-secret-password

undefined

Repository Adaptation Workflow

代码库适配工作流

Pre-Implementation Discovery (Phase 0)

实施前调研（第0阶段）

Before writing any code, the executor MUST:

bash

undefined

在编写任何代码前，执行者必须完成以下操作：

bash

undefined

1. Discover existing configuration patterns

1. 发现现有配置模式

fd -t f ".mise.toml" . fd -t f ".env*" . fd -t d ".dbeaver" .

2. Test ClickHouse connectivity (local)

2. 测试本地ClickHouse连通性

clickhouse-client --host localhost --port 9000 --query "SELECT 1"

3. Check for existing connection configs

3. 检查现有连接配置

fd -t f "data-sources.json" . fd -t f "dataSources.xml" .

undefined

fd -t f "data-sources.json" . fd -t f "dataSources.xml" .

undefined

Adaptation Decision Matrix

适配决策矩阵

Discovery Finding	Adaptation Action
Existing `.mise.toml` at repo root	Extend existing `[env]` section, don't create new file
Existing `.dbeaver/` directory	Merge connections, preserve existing entries
Non-standard CLICKHOUSE_* vars	Map to repository's naming convention
Multiple databases (local + cloud)	Generate multiple connection entries
No ClickHouse available	Warn and generate placeholder config

调研结果	适配操作
代码库根目录已存在 `.mise.toml`	扩展现有 `[env]` 部分，不创建新文件
已存在 `.dbeaver/` 目录	合并连接配置，保留现有条目
非标准CLICKHOUSE_*变量	映射到代码库的命名约定
多数据库（本地+云端）	生成多个连接条目
无可用ClickHouse	发出警告并生成占位符配置

Validation Checklist (Post-Generation)

验证检查清单（生成后）

The executor MUST verify:

Generated JSON is valid (
```
jq . .dbeaver/data-sources.json
```
)
DBeaver can import the config (launch and verify connection appears)
mise tasks execute without error (
```
mise run db-client-generate
```
)
```
.dbeaver/
```
added to
```
.gitignore
```

执行者必须验证以下内容：

生成的JSON有效（使用
```
jq . .dbeaver/data-sources.json
```
验证）
DBeaver可导入配置（启动DBeaver并确认连接已显示）
mise任务可正常执行（
```
mise run db-client-generate
```
）
```
.dbeaver/
```
已添加到
```
.gitignore
```

Pydantic Model

Pydantic模型

The

ClickHouseConnection

model provides:

Type-safe configuration with Pydantic v2 validation
Computed fields for JDBC URL and connection ID
Mode-aware defaults (cloud auto-enables SSL on port 8443)
Environment loading via
```
from_env()
```
class method

See references/pydantic-model.md for complete model documentation.

ClickHouseConnection

模型提供以下功能：

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

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

DBeaver Format

DBeaver格式

DBeaver uses

.dbeaver/data-sources.json

with this structure:

json

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

Important: DBeaver does NOT support

${VAR}

substitution—values must be pre-populated at generation time.

See references/dbeaver-format.md for complete format specification.

DBeaver使用

.dbeaver/data-sources.json

文件，其结构如下：

json

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

重要提示：DBeaver不支持

${VAR}

变量替换——所有值必须在生成时预先填充。

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

macOS Notes

macOS注意事项

DBeaver binary: Use

/Applications/DBeaver.app/Contents/MacOS/dbeaver

(NOT

open -a

)

Gitignore: Add
```
.dbeaver/
```
to
```
.gitignore
```

DBeaver二进制文件：使用

/Applications/DBeaver.app/Contents/MacOS/dbeaver

（不要使用

open -a

）

Git忽略配置：将
```
.dbeaver/
```
添加到
```
.gitignore
```

Related Skills

Skill	Integration
`devops-tools:clickhouse-cloud-management`	Credential retrieval for cloud mode
`quality-tools:clickhouse-architect`	Schema design context
`itp:mise-configuration`	SSoT environment variable patterns

技能	集成用途
`devops-tools:clickhouse-cloud-management`	为云端模式获取凭证
`quality-tools:clickhouse-architect`	提供Schema设计上下文
`itp:mise-configuration`	SSoT环境变量模式参考

Python Driver Policy

Python驱动策略

For Python application code connecting to ClickHouse (not DBeaver), use

clickhouse-connect

(official HTTP driver). See

clickhouse-architect

for:

Recommended code patterns
Why NOT to use
```
clickhouse-driver
```
(community)
Performance vs maintenance trade-offs

对于Python应用代码连接ClickHouse（非DBeaver场景），请使用

clickhouse-connect

（官方HTTP驱动）。详情请参考

clickhouse-architect

：

推荐代码模式
为何不使用
```
clickhouse-driver
```
（社区版）
性能与维护的权衡

Additional Resources

额外资源

Reference	Content
references/pydantic-model.md	Complete model documentation
references/dbeaver-format.md	DBeaver JSON format spec

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

Troubleshooting

故障排查

Issue	Cause	Solution
DBeaver can't connect	Port mismatch (8123 vs 9000)	HTTP uses 8123, native uses 9000 - check config
Credentials not loading	.env not sourced	Run `mise trust` or source .env manually
JSON validation fails	Invalid data-sources.json	Validate with `jq . .dbeaver/data-sources.json`
Cloud SSL error	Missing SSL on port 8443	Cloud mode auto-enables SSL - verify port is 8443
mise task not found	Missing task definition	Add task to mise.toml `[tasks]` section
.dbeaver/ in git	Missing gitignore entry	Add `.dbeaver/` to `.gitignore`
Connection ID conflict	Duplicate connection names	Each connection needs unique ID (random hex)
Config not updating	DBeaver caching	Restart DBeaver to reload data-sources.json

问题	原因	解决方案
DBeaver无法连接	端口不匹配（8123 vs 9000）	HTTP协议使用8123，原生协议使用9000 - 检查配置
凭证未加载	.env未被加载	运行 `mise trust` 或手动加载.env文件
JSON验证失败	data-sources.json无效	使用 `jq . .dbeaver/data-sources.json` 验证
云端SSL错误	8443端口未启用SSL	云端模式会自动启用SSL - 确认端口为8443
mise任务未找到	缺少任务定义	将任务添加到mise.toml的 `[tasks]` 部分
.dbeaver/被提交到git	.gitignore中缺少对应条目	将 `.dbeaver/` 添加到 `.gitignore`
连接ID冲突	连接名称重复	每个连接需要唯一ID（随机十六进制字符串）
配置未更新	DBeaver缓存	重启DBeaver以重新加载data-sources.json

clickhouse-pydantic-config

Original

Translation

ClickHouse Pydantic Config

ClickHouse Pydantic 配置生成

When to Use This Skill

何时使用该技能

Critical Design Principle: Semi-Prescriptive Adaptation

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

Why This Matters

为何这一点很重要

Quick Start

快速开始

Generate local connection config

生成本地连接配置

Generate cloud connection config

生成云端连接配置

Preview without writing

预览配置（不写入文件）

Launch DBeaver

启动DBeaver

Credential Prerequisites (Cloud Mode)

凭证前置条件（云端模式）

mise [env] as Single Source of Truth

以mise [env]作为单一可信数据源

Credential Handling by Mode

不同模式下的凭证处理

Cloud Credentials Setup

云端凭证设置

.env (gitignored)

.env（已加入git忽略）

Repository Adaptation Workflow

代码库适配工作流

Pre-Implementation Discovery (Phase 0)

实施前调研（第0阶段）

1. Discover existing configuration patterns

1. 发现现有配置模式

2. Test ClickHouse connectivity (local)

2. 测试本地ClickHouse连通性

3. Check for existing connection configs

3. 检查现有连接配置

Adaptation Decision Matrix

适配决策矩阵

Validation Checklist (Post-Generation)

验证检查清单（生成后）

Pydantic Model

Pydantic模型

DBeaver Format

DBeaver格式

macOS Notes

macOS注意事项

Related Skills

相关技能

Python Driver Policy

Python驱动策略

Additional Resources

额外资源

Troubleshooting

故障排查

mise
`[env]`
as Single Source of Truth

以mise
`[env]`
作为单一可信数据源