К основному содержанию
скилл CX Codex

clickhouse-pydantic-config — скилл для Claude Code: конфиг DBeaver

Скилл clickhouse-pydantic-config для Claude Code собирает файл подключений DBeaver для ClickHouse из Pydantic-модели и переменных окружения. Локальная и облачная базы открываются в клиенте без ручного ввода.

MIT 130 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill clickhouse-pydantic-config -a claude-code
Открыть на GitHub

Что делает clickhouse-pydantic-config

Скилл берёт параметры подключения из переменных CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_DATABASE и складывает их в .dbeaver/data-sources.json. Модель ClickHouseConnection на Pydantic v2 считает JDBC-URL и id соединения сама, а в режиме cloud включает SSL на порту 8443.

Внутри — Python-скрипт scripts/generate_dbeaver_config.py и порядок адаптации под конкретный репозиторий. Перед генерацией скилл велит поискать существующие .env и .dbeaver/ и дописать в них CLICKHOUSE_*, а не заводить файлы заново. Проверить результат заранее можно через uv run scripts/generate_dbeaver_config.py --dry-run. Запуск идёт через uv, поэтому он должен стоять в системе.

DBeaver не подставляет ${VAR} в конфиг, так что логин и пароль оказываются в JSON уже на момент генерации. Значит .dbeaver/ нужно добавить в .gitignore, иначе креды уедут в репозиторий. Для cloud-режима заранее нужен read-only пользователь ClickHouse: его логин и пароль кладут в .env.

Какие задачи решает

  • сгенерировать подключение к локальному ClickHouse для DBeaver
  • переключить тот же конфиг на облачную базу без ручного ввода параметров
  • посмотреть JSON до записи на диск через --dry-run
  • влить новые подключения в уже существующий .dbeaver/, не потеряв старые
  • убрать .dbeaver/ из git до того, как туда попали креды

Примеры запросов агенту

  • Сгенерируй конфиг DBeaver для локального ClickHouse в .dbeaver/data-sources.json
  • Собери cloud-подключение из .env и покажи результат, файл пока не пиши
  • Проверь, есть ли в репозитории старый data-sources.json, и смержи новые подключения с ним

Как установить clickhouse-pydantic-config

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill clickhouse-pydantic-config -a claude-code

2Вручную: положить файлы

~/.claude/skills/clickhouse-pydantic-config/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/clickhouse-pydantic-config/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о clickhouse-pydantic-config

Как установить clickhouse-pydantic-config в Claude Code?

Выполните npx skills add terrylica/cc-skills --skill clickhouse-pydantic-config -a claude-code. Скилл появится по пути ~/.claude/skills/clickhouse-pydantic-config/SKILL.md.

Что делает clickhouse-pydantic-config?

Генерирует .dbeaver/data-sources.json для ClickHouse: берёт хост, порт и базу из переменных окружения, считает JDBC-URL через Pydantic v2 и пишет готовые записи подключений.

Почему креды оказываются прямо в data-sources.json?

DBeaver не раскрывает ${VAR} в конфиге, значения нужно подставить заранее. Поэтому скилл пишет логин и пароль в файл при генерации, а сам файл держит вне git.

Исходный текст

SKILL.md · MIT
---
name: clickhouse-pydantic-config
description: Generate DBeaver config from Pydantic ClickHouse models. TRIGGERS - DBeaver config, ClickHouse connection, database client config.
allowed-tools: Read, Bash, Grep
---

# ClickHouse Pydantic Config

<!-- ADR: 2025-12-09-clickhouse-pydantic-config-skill -->

Generate DBeaver database client configurations from Pydantic v2 models using environment variables as the Single Source of Truth (SSoT).

**Schema documentation principle**: ClickHouse table/column COMMENTs are the SSoT for what each column means and how it's computed. See `quality-tools:clickhouse-architect` for the full COMMENT policy.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## 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
- Automating DBeaver data-sources.json generation

## 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

```bash
# 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
```

## Credential Prerequisites (Cloud Mode)

<!-- ADR: 2025-12-10-clickhouse-skill-documentation-gaps -->

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

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

```bash
CLICKHOUSE_USER_READONLY=your_user
CLICKHOUSE_PASSWORD_READONLY=your_password
```

1. **Generate config**: Run `uv run scripts/generate_dbeaver_config.py --mode cloud`

**Skill chain**: `clickhouse-cloud-management` → `.env` → `clickhouse-pydantic-config`

## Environment Variables as Single Source of Truth

All configurable values are environment variables; export them in your shell or keep them in the gitignored `.env`:

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

Scripts read from `os.environ.get()` with backward-compatible defaults, so every variable is optional.

## 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

```bash
# .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:

```bash
# 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" .
```

### Adaptation Decision Matrix

| Discovery Finding                  | Adaptation Action                                      |
| ---------------------------------- | ------------------------------------------------------ |
| Existing `.env` at repo root       | Extend it with `CLICKHOUSE_*` vars, don't create a 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)
- [ ] The generator runs without error (`uv run scripts/generate_dbeaver_config.py --dry-run`)
- [ ] `.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](./references/pydantic-model.md) for complete model documentation.

## DBeaver Format

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](./references/dbeaver-format.md) for complete format specification.

## macOS Notes

1. **DBeaver binary**: Use `/Applications/DBeaver.app/Contents/MacOS/dbeaver` (NOT `open -a`)
2. **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               |

## Python Driver Policy

For Python application code connecting to ClickHouse (not DBeaver), use `clickhouse-connect` (official HTTP driver). See [`clickhouse-architect`](../../../quality-tools/skills/clickhouse-architect/SKILL.md#python-driver-policy) for:

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

## Additional Resources

| Reference                                                      | Content                      |
| -------------------------------------------------------------- | ---------------------------- |
| [references/pydantic-model.md](./references/pydantic-model.md) | Complete model documentation |
| [references/dbeaver-format.md](./references/dbeaver-format.md) | DBeaver JSON format spec     |

---

## 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             | `set -a; source .env; set +a`, then re-run        |
| 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 |
| .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       |


## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Все скиллы по теме «Данные и базы» →
clickhouse-managed-postgres-rca ClickHouse Inc Скилл clickhouse-managed-postgres-rca ищет причины просадки производительности ClickHouse-managed Postgres по метрикам Prometheus и Slow Query Patterns, предлагая исправления без их применения. CX Codex +1 6 900установок clickhouse-best-practices ClickHouse Inc Скилл clickhouse-best-practices для Claude Code проверяет схемы таблиц, SQL-запросы, полнотекстовый поиск и вставку данных в ClickHouse по набору из 36 правил. CX Codex +1 23 400установок clickhouse-query civitai Скилл clickhouse-query гоняет ad-hoc запросы к ClickHouse прямо из чата с агентом: метрики, события, план выполнения. По умолчанию только чтение. CX Codex +1 ★ 7 327звёзд репо pydantic-models-py Microsoft Скилл pydantic-models-py для Claude Code задаёт структуру моделей Pydantic v2 по шаблону из пяти вариантов: Base, Create, Update, Response и InDB. Генерирует схемы запросов и ответов API с наследованием, чтобы не дублировать поля. CX Codex +1 5установок pydantic-ai-harness pydantic Скилл pydantic-ai-harness для Claude Code и Codex, расширяющий Pydantic AI агентов возможностями кодирования, работы с файлами и командами, изоляции в песочницах и управления контекстом. CX Codex +1 3 300установок migrating-agno-to-pydantic-ai pydantic Скилл migrating-agno-to-pydantic-ai для Claude Code переносит Python-приложения с Agno на Pydantic AI, трассируя реальный путь запроса и сохраняя HTTP-границы и инфраструктуру. CX Codex +1 463установок

Из того же набора79

Весь набор →
python-workspace Скилл python-workspace экспортирует котировки из MetaTrader 5 и переносит индикаторы MQL5 на Python с проверкой корреляции от 0.999. CX Codex +1 131установок terminal-print Скилл terminal-print собирает вывод терминала в PDF и отправляет его на сетевой принтер. Помогает распечатать сессию или обойти проблему пустых страниц на некоторых HP LaserJet Pro. CX Codex +1 131установок doppler-workflows Скилл doppler-workflows помогает запускать публикацию Python-пакетов и AWS-команды с секретами из Doppler. Пригодится и для разбора ошибок авторизации. CX Codex +1 130установок ml-data-pipeline-architecture Скилл ml-data-pipeline-architecture для Claude Code помогает проектировать ML-пайплайны на Polars, Arrow и ClickHouse. Сравнивает Polars и Pandas, обрабатывает большие наборы данных и передаёт их в PyTorch. CX Codex +1 130установок issue-create Скилл issue-create превращает черновое описание в оформленный GitHub issue: определяет тип, подбирает метки из таксономии репозитория и предупреждает о дублях. CX Codex +1 129установок asciinema-streaming-backup Скилл asciinema-streaming-backup организует потоковую выгрузку терминальных записей asciinema в orphan-ветку репозитория GitHub со сжатием zstd и brotli. CX Codex +1 128установок multi-agent-e2e-validation Скилл multi-agent-e2e-validation для Claude Code и других AI-редакторов запускает несколько агентов параллельно, чтобы комплексно протестировать рефакторинг базы данных. CX Codex +1 128установок link-validator Скилл link-validator проверяет markdown-ссылки в навыках на предмет абсолютных путей, которые сломаются при установке в другое место. Нужен перед распространением навыка или после добавления новых ссылок. CX Codex +1 127установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой