cmd/sqlshapeはgo vet -vettool互換の検査器である。次のどの形でも実行でき、以下のフラグはどの形でも同じように渡せる。
sqlshape ./...sqlshape vet ./...go vet -vettool=$(which sqlshape) ./...
マイグレーションのサブコマンド(diff、apply、verify-schema)のフラグは別で、migrations.ja.mdにある。sqlshape checkのフラグは下記。
| フラグ | 既定 | 意味 |
|---|---|---|
-schema PATH |
パッケージから上に辿って最初に見つかるschema.sqlかschema/ |
検査に使うスキーマ。ディレクトリなら*.sqlを名前順に適用する |
-strict |
off | 助言も報告する(下記) |
-no-table-reads |
off | テーブルの読み取りを禁じる。SELECTも書き込み中の読み取り部分もビューを通す。INSERT / UPDATE / DELETE / MERGEの対象にはテーブルを使える |
-no-tables |
off | テーブルへの参照を一切禁じる。アプリケーションはビューを読み、関数を呼ぶ |
-schemas=a_api,b_private |
全部 | このコードが参照してよいPostgreSQLのスキーマ。1つのデータベースを複数サービスで使うときの境界 |
-context=ops |
なし | パッケージを判定する義務の文脈。パッケージコメントに// sqlshape: context <name>があればそちらが優先 |
-require-columns=tenant_id |
なし | すべての文が、その列を持つ各テーブルでその列を等値で固定しなければならない。INSERTは値を入れなければならない。その列を固定する行レベルセキュリティのポリシーがあれば満たしたことになる |
-query=example.com/app/db.Query,example.com/app/db.Get:one |
なし | 自前のマーカー関数をsqlshape.Queryと同じように読む(:oneはOneと同じ扱い)。テンプレートを引数に取る generic なF[R, P any](string) Tであればよい。関数はフルのimport pathに.と関数名を続けて指定する。短いパッケージ名では何にも一致しない。検査器が読むのは宣言であって、実行するランタイムではない |
-raw-sql=constant |
constant |
sqlshapeを通さないドライバ呼び出し(pgx / database/sqlのQuery、Execなど)の扱い。constantはSQL引数が定数であることを要求し、forbidは拒否し、allowは無視する |
-raw-sql-allow=pkg/... |
なし | -raw-sql=forbidを適用しないパッケージ(/...で終わる接頭辞も可) |
-coverage |
off | パッケージごとに、検査したQuery / Oneの数と、検査できなかった数(テンプレートが定数でないもの)を報告する |
-sync-comments |
off | スキーマのCOMMENT ONから、結果の構造体のフィールドと型にdocコメントを提案する(-fixで適用) |
-fix |
off | 提案された修正(構造体の書き換え、docコメント)をソースに適用する |
-no-table-reads・-no-tables・-require-columnsは、schema.sqlで表ごとに宣言する義務(require via view、require via view on all、require pinned(列))の略記。宣言形ならonによる文種の指定、immutable(列)、任意の述語も書ける。文脈のwaiveはフラグ由来の義務も宣言と同じように解除する(checks.ja.md)。
sqlshape check [flags] [FILE.sql...]はSQLファイル(または標準入力)をschema.sqlの規約と照合する(checks.ja.md)。
| フラグ | 既定 | 意味 |
|---|---|---|
-schema PATH |
作業ディレクトリから上に辿って最初に見つかるschema.sqlかschema/ |
照らすスキーマ |
-context NAME |
なし | 判定に使う義務の文脈(schema.sqlのcontext NAME: ...宣言) |
-quiet |
off | 全判定ではなく失敗だけを出す |
-require-columns、-no-tables、-no-table-reads |
vetと同じ | 表ごとの義務の略記。vetと同じ意味 |
義務を履行できない文か解析に失敗する文があれば終了コード1、使い方の誤りは2。
-strictを付けると助言が加わる。ルール違反ではなく、意図してそう書いた可能性もあるが、一度見直す価値のあるもの、である。文についての助言:
- どの展開でも使われていない
Pのフィールド - enum・ドメイン・キー列を無名のGo型(
string、int64)で受けている。結びつきの検査ができない timestampやdateをtime.Timeで受けている。タイムゾーンや時刻の情報が無いのに補われる- enumのパラメータがポインタでない。ゼロ値の
""はラベルではないので、未設定のまま渡すと実行時に失敗する DEFAULTやidentityを持つ列に、NULLを表せない型のパラメータで常に値を書き込んでいる。データベース側の既定値が使われることがないORDER BYの無いLIMIT。どの行が返るか決まらない- enumの比較や
ORDER BY。アルファベット順ではなく宣言順で並ぶ - 先頭列にインデックスの無い条件で絞っているテーブル(全表走査になる)、プランナーがビューの中に押し込めない条件(ビューに
LIMIT/OFFSET、集合演算、ウィンドウ関数がある) - 分岐の組み合わせが256を超えて疎に検査されたテンプレート
- 一意インデックスの無いビューに対する
MatView.RefreshConcurrently -require-columnsを、FORCE ROW LEVEL SECURITYでないテーブルのポリシーで満たしている。所有者には適用されない
スキーマについての助言:
- enumの列。seed済みlookupテーブルのほうが変更しやすく、検査は同じようにできる
- 一意インデックスの無いマテリアライズドビュー。concurrentlyにrefreshできない
- 行レベルセキュリティが有効なのにポリシーが無いテーブル。所有者以外には行が見えない
current_setting(name, true)を読むポリシー。設定していないセッションではNULLになり、エラーにならずに何も見えなくなる- 所有者にはポリシーが適用されないテーブルに到達する
SECURITY DEFINER関数 - PL/pgSQLの
EXECUTEで実行時に組み立てた文字列を実行している。検査できない
検査器はgo vetのツールなので、go vetが走る場所ならどこでも走る。一度ビルドして-vettoolに指定する:
$ go install github.com/kr9ly/sqlshape/cmd/sqlshape/v2@v2.0.0 # 使うリリースに固定する
$ go vet -vettool="$(which sqlshape)" -strict ./...
Go統合のあるエディタは保存時にgo vetを走らせて診断をインラインに表示できるので、その設定に同じ-vettoolと-strictを渡す。gopls自体はサードパーティのアナライザーを読み込まないため、goplsではなくgo vetを経由する。CIでも同じコマンドを、バージョンを固定して走らせればよい。マイナーリリースで診断が増えることがあるためである(README: バージョニング)。
type OrderRow struct{}とtype OrderParams struct{}を空で宣言し、クエリを書いて保存する。すべての結果列について対応するフィールドが無い、すべての{{.X}}について対応するパスが無い、という診断が出て、それぞれにクエリから構造体を書き換えるquick fixが付く。書き起こされる内容:
- すべての分岐の列。一部の分岐だけが選ぶ列はポインタになる
- NULLになりうる列はポインタになる
- enumやlookupの値は、モジュール内で既に結びつけられているGo型になる
- レコードと複合型はネストした構造体、その配列はスライスになる
COMMENT ONがあればdocコメントになるPについては、パスごとにSQL側が期待する型のフィールド(.Filter.Nameならネストした構造体、rangeならスライス)と、{{if .Flag}}で調べるだけのフィールドにはbool
同じquick fixは、以後に不一致が出たとき(SELECTに列を足した、スキーマで型を変えた)にも付く。まだ合っているフィールドの名前・docコメント・タグ・型は保たれるので、選択肢の中から選んだ型(numericに対するdecimal.Decimalなど)は残る。numericはモジュールがshopspring/decimalを既にimportしていればdecimal.Decimal、していなければpgtype.Numericになる。uuidも同様に、使用中のuuidパッケージの型になる。
コマンドラインからはsqlshape -fix ./...で適用する。エディタからは診断に付いたquick fixで適用する。