clickhouse-pydantic-config
Generate DBeaver configurations from Pydantic ClickHouse connection models. Use when user mentions "DBeaver config", "ClickHouse connection setup", "database client configuration", "generate connection JSON", "mise SSoT connection", or needs consistent connection configuration across development tools.
When & Why to Use This Skill
This Claude skill automates the generation of DBeaver database client configurations using Pydantic v2 models and mise environment management. It establishes a Single Source of Truth (SSoT) for ClickHouse connections, allowing developers to seamlessly synchronize environment variables with their GUI tools while ensuring consistent setup across local and cloud environments.
Use Cases
- Automated Workspace Setup: Quickly generate DBeaver connection files for new team members based on the repository's existing .mise.toml and Pydantic models.
- Cloud Credential Integration: Streamline the process of importing ClickHouse Cloud credentials from .env files into DBeaver without manual copy-pasting.
- Environment Synchronization: Ensure that database connection parameters (host, port, database name) remain consistent between the application code and the database management tool.
- Multi-Environment Management: Rapidly switch between local and cloud ClickHouse configurations by generating dynamic data-sources.json files tailored to the current development context.
| name | clickhouse-pydantic-config |
|---|---|
| description | > |
| allowed-tools | Read, Bash, Grep |
ClickHouse Pydantic Config
Generate DBeaver database client configurations from Pydantic v2 models using mise [env] as Single Source of Truth (SSoT).
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.
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.
Quick Start
# 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
mise run dbeaver
Credential Prerequisites (Cloud Mode)
Before using cloud mode, obtain credentials via the skill chain:
- Create/retrieve user: Use
clickhouse-cloud-managementskill to create read-only users or retrieve existing credentials from 1Password - Store in .env: Add to
.envfile (gitignored):
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
mise [env] as Single Source of Truth
All configurable values live in .mise.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.
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.
Cloud Credentials Setup
# .env (gitignored)
CLICKHOUSE_USER_READONLY=readonly_user
CLICKHOUSE_PASSWORD_READONLY=your-secret-password
Repository Adaptation Workflow
Pre-Implementation Discovery (Phase 0)
Before writing any code, the executor MUST:
# 1. Discover existing configuration patterns
fd -t f ".mise.toml" .
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" .
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 |
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
Pydantic Model
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.
DBeaver Format
DBeaver uses .dbeaver/data-sources.json with this structure:
{
"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.
macOS Notes
- DBeaver binary: Use
/Applications/DBeaver.app/Contents/MacOS/dbeaver(NOTopen -a) - Gitignore: Add
.dbeaver/to.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 |
Python Driver Policy
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
Additional Resources
| Reference | Content |
|---|---|
| references/pydantic-model.md | Complete model documentation |
| references/dbeaver-format.md | DBeaver JSON format spec |