clickhouse-pydantic-config

ClickHouse Pydantic Config

Pydantic v2 モデルから DBeaver データベースクライアント設定を生成します。環境変数を唯一の信頼できる情報源（SSoT）として使用します。

スキーマドキュメントの原則：ClickHouse のテーブル／カラムの COMMENT は、各カラムの意味と計算方法に関する SSoT です。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 に保存する：Git で追跡対象外の .env ファイルに追加します。

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

環境変数を唯一の信頼できる情報源として使用する

設定可能な値はすべて環境変数です。シェルでエクスポートするか、Git で追跡対象外の .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 から事前入力する	環境から読み取り、Git で追跡対象外の JSON に書き込みます

重要な原則：生成された data-sources.json はいずれにせよ Git で追跡対象外です。認証情報を事前入力することで、セキュリティ上のリスクをゼロに保ちながら、開発者の利便性を最大限に高められます。

クラウド認証情報の設定

# .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 の計算フィールド
• モードに応じたデフォルト値（クラウドモードではポート 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 バイナリ：open -a ではなく、/Applications/DBeaver.app/Contents/MacOS/dbeaver を使用してください
2. Gitignore：.dbeaver/ を .gitignore に追加してください

関連スキル

スキル	連携内容
devops-tools:clickhouse-cloud-management	クラウドモードで使用する認証情報の取得
quality-tools:clickhouse-architect	スキーマ設計のコンテキスト

Python ドライバーポリシー

ClickHouse に接続する Python アプリケーションコード（DBeaver を除く）では、公式 HTTP ドライバーの clickhouse-connect を使用してください。詳細については、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 で検証してください
クラウド SSL エラー	ポート 8443 で SSL が未設定	クラウドモードでは SSL が自動的に有効になります。ポートが 8443 であることを確認してください
.dbeaver/ が Git に含まれる	gitignore のエントリがない	.dbeaver/ を .gitignore に追加してください
接続 ID が競合する	接続名が重複している	接続ごとに一意の ID（ランダムな 16 進数）が必要です
設定が更新されない	DBeaver のキャッシュ	DBeaver を再起動して data-sources.json を再読み込みしてください

実行後の振り返り

このスキルの実行が完了したら、終了前に以下を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラー表を修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、それに合わせて使用例とパラメーター表を更新してください。
3. 回避策が必要でしたか？ — 別のフラグや追加の手順など、即興で対応する必要があった場合は、次回同じ回避策が不要になるよう、この SKILL.md を更新してください。

実際に再現可能な問題がある場合にのみ更新してください。推測に基づく更新は行わないでください。