sql-lint

SQL Lint

プロジェクトに SQL カタログ（-- name: X :type コメントや、名前付きクエリの慣習）があり、負荷の大きい SQL リンターを導入せずに基本的な品質を保ちたい場合に使用します。

2 つのレイヤー

このスキルには、コストとカバー範囲のバランスが異なる 2 つ のリンターが含まれています。

レイヤー 1：catalog-lint（組み込み、依存関係なし）

scripts/catalog-lint.mjs は、依存関係のない Node 20 以降向けのスクリプトです。次の問題を検出します。

• duplicate-name：同じ -- name: X ヘッダーを持つクエリが 2 つある場合。一部のコード生成ツールでは、警告なく上書きされることがありますが、別のツールではエラーになります。
• missing-semicolon：末尾の ; がないクエリ。sqlc はビルド時にこれを拒否しますが、catalog-lint なら fmt の実行時に検出できます。
• empty-body：SQL 本文がないヘッダー。
• malformed-name：name: X :type の形式に一致しない -- name: 行。
• select-star：SELECT *（常に不要な列まで取得します）。
• double-wildcard-like：LIKE '%...%'（テーブル全体をスキャンするリスクがあります）。

実行方法（最初に実行する既定のチェックです。sqlfluff を使う前に、まずはこちらを実行してください）。

# `scripts/` is relative to THIS skill's directory. From elsewhere, use the
# absolute path, e.g. node "$CLAUDE_SKILLS_DIR/sql-lint/scripts/catalog-lint.mjs".
node scripts/catalog-lint.mjs your-project/db/queries.sql
echo "exit=$?"   # 0 = clean, 1 = findings — the exit code IS the pass/fail signal

問題がなければ 0、検出事項があれば 1 で終了します。出力形式は file:line: [rule] message で、エディターの診断表示で解析できます。注：select-star と double-wildcard-like では、問題の SQL 行ではなく、クエリの -- name: ヘッダー行が報告されます。

レイヤー 2：sqlfluff（任意、明示的なオプトイン）

キーワードの大文字・小文字、インデント、エイリアス名など、スタイル全般をカバーするには sqlfluff を使用します。このスキルには、SQLite/D1 と sqlc のカタログ向けに調整された .sqlfluff が含まれています。

uvx sqlfluff lint --config .sqlfluff your-project/db/queries.sql

astral.sh/uv の uvx は、一時的な仮想環境で sqlfluff を実行するため、永続的にインストールされるものはありません。uv がない場合は、pip install sqlfluff または pipx install sqlfluff を使用してください。

付属の設定では、sqlfluff のいくつかのルールを無効にしています。

• AM04（SELECT *）は、より適切なコンテキストで catalog-lint が処理します。
• CP02（列名の大文字・小文字）は、obj.field_name のような JSON パス参照で誤検出が多すぎます。
• L009（末尾の改行）は git で強制します。

実行するタイミング

• クエリカタログを変更するすべてのコミット時（pre-commit / pre-push フック）。
• マイグレーションのマイルストーンごとに 1 回、sqlfluff を実行してスタイル全般をチェックします。

ホストコード内のインライン SQL

このスキルは MoonBit / Rust / Go などのインライン SQL をチェックしません。その場合は ast-grep が適切なツールですが、言語ごとの tree-sitter サポートが必要です。tree-sitter の文法がないホスト言語（例：MoonBit）では、テキスト検索のベースラインファイル（.linters/inline-sql-baseline.json）が有効です。ファイルごとに .prepare( の出現回数を数え、増加を拒否します。

関連する sql-security スキルでは、SQL インジェクションに対する同じ方法を説明しています。

CI との統合

sql-lint:
    node scripts/catalog-lint.mjs db/queries.sql

CI で sqlfluff をすべて実行する場合は、別途 sql-lint-style ステップを実行し、軽量な catalog-lint がすばやく失敗を検出できるようにします。

エンジンの拡張性

catalog-lint.mjs は特定のエンジンに依存しません。ルールは SQL コメント、セミコロン、基本的なパターンをチェックします。MySQL / Postgres に対応するには、.sqlfluff の dialect = sqlite の行を変更してください。

要件

• scripts/catalog-lint.mjs の実行には Node 20 以降が必要です。
• （任意）sqlfluff の実行には uv / pipx / pip が必要です。

ファイル

• scripts/catalog-lint.mjs — 依存関係なしのカタログリンター。
• .sqlfluff — オプトイン方式の sqlfluff 設定（SQLite 方言。他のエンジンでは dialect = ... を変更してください）。