schema-e2e-validation について
gapless-network-data プロジェクトでスキーマ変更を検証し、生成ワークフローを実行するスキルです。Earthly のターゲット、ClickHouse の検証要件、生成物、環境設定のトラブル対処を説明します。
主な機能
- 01Earthly によるスキーマ生成
- 02ClickHouse スキーマ検証
- 03Python 型、DDL、ドキュメントの生成
- 04E2E ワークフローのコマンド
- 05Docker と Doppler のトラブル対処
活用シーン
- 01YAML スキーマから成果物を生成
- 02ClickHouse Cloud に対するスキーマ検証
- 03コミット前のスキーマ E2E チェック
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/schema-e2e-validationを入力して読み込まれたか確認します。
同梱ファイルreferences/evolution-log.md
詳細
スキーマのE2E検証
自己進化型スキル：このスキルは使用を通じて改善されます。手順に誤りがある、パラメーターが変更されている、または回避策が必要だった場合は、後回しにせず、このファイルをすぐに修正してください。実際に再現可能な問題がある場合のみ更新してください。
このスキルを使用するタイミング
次のような場合にこのスキルを使用してください。
- コミット前にスキーマの変更を検証する
- YAML スキーマが稼働中の ClickHouse Cloud と一致することを確認する
- Python の型、DDL、またはドキュメントを再生成する
- スキーマのワークフロー全体を検証する
前提条件
Docker ランタイム（必須）
Earthly には Docker が必要です。実行前に Colima を起動してください。
colima start
実行中かどうかを確認する：
docker ps # Should not error
Doppler アクセス（検証ターゲット用）
+test-schema-validate と +test-schema-e2e に必要です。
doppler configure set token <token_from_1password>
doppler setup --project gapless-network-data --config prd
Earthly のインストール
brew install earthly
クイックコマンド
生成のみ（シークレット不要）
cd ~/eon/gapless-network-data
colima start # If not already running
earthly +test-schema-generate
検証を含むE2E全体（Doppler が必要）
cd ~/eon/gapless-network-data
colima start # If not already running
./scripts/earthly-with-doppler.sh +test-schema-e2e
シークレット不要の全ターゲット
cd ~/eon/gapless-network-data
earthly +all
成果物
+test-schema-generate または +test-schema-e2e の実行後、./earthly-artifacts/ を確認してください。
| パス | 内容 |
|---|---|
types/blocks.py | Pydantic と TypedDict のモデル |
types/__init__.py | パッケージの初期化 |
ddl/ethereum_mainnet.sql | ClickHouse DDL |
docs/ethereum_mainnet.md | Markdown ドキュメント |
E2E の場合、成果物は e2e/types/、e2e/ddl/、e2e/docs/ にあります。
Earthfile ターゲットのリファレンス
| ターゲット | シークレット | 目的 |
|---|---|---|
+deps | いいえ | uv と依存関係をインストールする |
+build | いいえ | ソースファイルをコピーする |
+test-unit | いいえ | pytest を実行する |
+test-schema-generate | いいえ | 型／DDL／ドキュメントを生成する |
+test-schema-validate | はい | ClickHouse と照合して検証する |
+test-schema-e2e | はい | ワークフロー全体と成果物を実行する |
+all | いいえ | シークレット不要の全ターゲットを実行する |
トラブルシューティング
「could not determine buildkit address - is Docker or Podman running?」
原因：Docker／Colima が起動していない
解決方法：
colima start
# Wait for "done" message, then retry
earthly +test-schema-generate
「unable to parse --secret-file argument」
原因：フラグ名が誤っている、またはシークレットファイルの形式が不正
解決方法：正しいフラグは --secret-file-path です（--secret-file ではありません）。ラッパースクリプトが処理しますが、手動で実行する場合は次のようにします。
# WRONG
earthly --secret-file=/path/to/secrets +target
# CORRECT
earthly --secret-file-path=/path/to/secrets +target
また、シークレットファイルの値を引用符で囲まないでください。
# WRONG format
CLICKHOUSE_HOST="host.cloud"
# CORRECT format
CLICKHOUSE_HOST=host.cloud
「OSError: Readme file does not exist: README.md」
原因：hatchling のビルドバックエンドでは、コンテナー内に README.md が必要です
解決方法：deps ターゲットで Earthfile が README.md をコピーするようにしてください。
deps:
COPY pyproject.toml uv.lock README.md ./ # README.md required!
検証中の「missing secret」
原因：Doppler が設定されていないか、シークレットが渡されていない
解決方法：
# Verify Doppler has the secrets
doppler secrets --project gapless-network-data --config prd | grep CLICKHOUSE
# Use the wrapper script (handles secret injection)
./scripts/earthly-with-doppler.sh +test-schema-validate
キャッシュの問題
キャッシュを使わずに強制的に再ビルドします。
earthly --no-cache +test-schema-e2e
実装の詳細
Doppler によるシークレットの注入
ラッパースクリプト scripts/earthly-with-doppler.sh は次の処理を行います。
- Doppler からシークレットをダウンロードする
CLICKHOUSE_*変数を抽出する- 引用符を削除する（Doppler の出力は
KEY="value"ですが、Earthly ではKEY=valueが必要です） --secret-file-pathフラグで渡す- 終了時に一時ファイルを削除する
必要なシークレット
| シークレット | 目的 |
|---|---|
CLICKHOUSE_HOST_READONLY | ClickHouse Cloud のホスト |
CLICKHOUSE_USER_READONLY | 読み取り専用ユーザー |
CLICKHOUSE_PASSWORD_READONLY | 読み取り専用パスワード |
関連ファイル
| ファイル | 目的 |
|---|---|
~/eon/gapless-network-data/Earthfile | メインのビルドファイル |
~/eon/gapless-network-data/scripts/earthly-with-doppler.sh | シークレット注入ラッパー |
~/eon/gapless-network-data/schema/clickhouse/ethereum_mainnet.yaml | SSoT スキーマ |
~/eon/gapless-network-data/docs/adr/2025-12-03-earthly-schema-e2e.md | ADR |
検証履歴
- 2025-12-03：ClickHouse Cloud に対する完全な E2E 実行で作成・検証済み
- 学んだこと：
--secret-fileではなく--secret-file-path（Earthly v0.8.16）- Doppler の
--format envは引用符を出力するため、sed 's/"//g'で取り除く必要があります - hatchling のビルドバックエンドには README.md をコピーする必要があります
- Earthly の実行前に Colima を起動する必要があります
設計権限
このスキルはスキーマを検証しますが、設計はしません。スキーマ設計のガイダンス（ORDER BY、圧縮、パーティショニング）については、まず quality-tools:clickhouse-architect を実行してください。
関連スキル
| スキル | 目的 |
|---|---|
quality-tools:clickhouse-architect | 検証前のスキーマ設計 |
devops-tools:clickhouse-cloud-management | E2E テスト用のクラウド認証情報 |
devops-tools:clickhouse-pydantic-config | クライアントの設定 |
実行後の振り返り
このスキルの実行後、完了する前に次の点を確認してください。
- コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順またはエラーテーブルを修正してください。
- パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェースに変更があった場合は、使用例とパラメーターテーブルを更新して合わせてください。
- 回避策が必要でしたか？ — 別のフラグや追加手順などの工夫が必要だった場合は、次回同じ回避策が不要になるように、この SKILL.md を更新してください。
問題が実際に再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。