Skip to content

Latest commit

 

History

History
96 lines (70 loc) · 9.2 KB

flags.ja.md

File metadata and controls

96 lines (70 loc) · 9.2 KB

フラグとエディタ設定

English

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のフラグ

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

-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: バージョニング)。

SQLから構造体を書き起こす

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で適用する。