SQLはGoのtext/templateのサブセットで書く。入力はパラメータ型Pの値で、{{.X}}と書いた箇所がプレースホルダ(PostgreSQLでは$n、MySQLでは?)になり、{{if}}や{{range}}で文の形を切り替えられる。検査器は分岐の全組み合わせを展開して検査し、ランタイムは検査済みのSQLだけを実行する。展開はlint時に行うので、テンプレートは文字列定数でなければならない。
- 値:
{{.Field}}、{{.Outer.Inner}}、{{.}}、rangeの中の{{$x}}。それぞれがSQLの中ではパラメータになり、値が文字列として埋め込まれることはない。関数呼び出し、メソッド呼び出し、パイプラインは値の位置では使えない - 分岐:
{{if}}/{{else if}}/{{else}}/{{end}}、{{with}}、{{range}}。{{switch}}は無いので{{if eq .Sort "a"}} … {{else if eq .Sort "b"}} … {{end}}と書く - 条件式: 組み込みの
not、and、or、eq、ne、lt、le、gt、ge、len、indexと、文字列・数値の定数、フィールド参照。nilポインタ、空のスライスやマップ、0、空文字列はtext/templateと同じく偽 - 使えないもの:
{{define}}/{{template}}(代わりにGoの定数を連結する。後述)、独自関数、rangeの要素以外の変数
SELECT o.id, o.total, o.created_at
FROM orders o
WHERE true
{{if .CustomerID}} AND o.customer_id = {{.CustomerID}} {{end}}
{{if .Statuses}} AND o.status = ANY({{.Statuses}}) {{end}}
ORDER BY {{if eq .Sort "total"}} o.total DESC {{else}} o.created_at DESC {{end}}, o.id
{{with .Limit}} LIMIT {{.}} {{end}}この文は{{if}}が3つと{{with}}が1つなので16通りに展開され、16通りすべてが検査される。
{{.Filter.Name}}はPのフィールドFilterのフィールドNameを指す。{{range .Items}} … {{.Sku}} … {{end}}の中の{{.Sku}}はスライスItemsの要素のフィールドを指す。スカラーのスライスに対するrangeの中の{{.}}は要素そのもの。埋め込み構造体のフィールドは昇格して見える。
各{{.X}}の型は、SQLの中で使われている場所から決まる(WHERE id = {{.ID}}ならbigint)。合っていなければ報告される。詳細はchecks.ja.md。{{if .Flag}}で調べるだけで値としては使わないフィールドはPに存在すればよく、型は問わない。
{{range}}は空、1要素、2要素の3通りで展開される。INの中身のように要素の間に区切りが要る場所は、{{if $i}}, {{end}}のように書く。
SELECT id FROM products
WHERE sku IN ({{range $i, $it := .Items}}{{if $i}}, {{end}}{{$it.Sku}}{{end}})ディレクティブは検査器が読むSQLコメント。テンプレートの中で使うもの:
| ディレクティブ | 意味 |
|---|---|
-- sqlshape: expect users_email_key, orders.total, P0401 |
この書き込みが違反しうる制約、NOT NULL列、SQLSTATEの一覧。検査器はこの一覧が正確であることを保つ(checks.ja.md) |
-- sqlshape: not null total, note |
これらの結果列はNULLにならない、と検査器の判定を上書きする(col:",notnull"タグのSQL側バージョン) |
-- sqlshape: unfiltered memos |
この文は意図的にmemosをvisible whereの条件なしで読む(述語型の義務だけを解除する) |
-- sqlshape: waive orders pinned(tenant_id), audit |
この文はordersの義務を1つ(宣言どおりの綴りで指定する)、auditの義務を全部解除する。解除したことは-strictで報告される(checks.ja.md) |
schema.sqlに書くディレクティブ(バージョン、visible where、require、seed、-- @migrateなど)はchecks.ja.mdに一覧がある。
Goのコードの中では、型宣言のdocコメントに// sqlshape: type money_amountと書くと、その型をPostgreSQLの型に結びつけられる(postgres.ja.md。PostgreSQLのみ。MySQLには結びつける先の名前付きの型が無い)。パッケージコメントの// sqlshape: context opsは、そのパッケージが判定される義務の文脈を選ぶ。
テンプレートは定数でなければならないが、Goの定数は連結できる。共通の条件やSELECT句はGoの定数にして連結する。
OK
const tenantFilter = " AND tenant_id = {{.TenantID}}"
var ListOrders = sqlshape.Query[Order, ListParams](base + tenantFilter)
var ListItems = sqlshape.Query[Item, ItemParams](itemsBase + tenantFilter)連結した全体を1つのテンプレートとして展開する。フラグメントが参照するフィールドはPに無ければならず、フラグメントに関する診断はフラグメントが定義されている行に出る。
NG。実行時に組み立てたテンプレートは検査できない。
var ListOrders = sqlshape.Query[Order, ListParams](fmt.Sprintf(base, table))
// sqlshape: query template must be a string constantテンプレートとしては書けるが、SQLとしては見た目どおりに動かないものは報告される。
NG
SELECT id FROM products WHERE name LIKE '%{{.Q}}%'
-- ^ {{.Q}} is inside a string literal: it becomes text, not a parameter (write '%' || {{.Q}} || '%' to concatenate)OK
SELECT id FROM products WHERE name LIKE '%' || {{.Q}} || '%'NG。値が指す列ではなく、定数で並べ替えることになる。
SELECT id, total FROM orders ORDER BY {{.Sort}}
-- ^ ORDER BY {{.Sort}} sorts by a constant, not by the column the value names: branch on it instead ({{if eq .Sort "total"}} total {{else}} id {{end}})OK
SELECT id, total FROM orders ORDER BY {{if eq .Sort "total"}} total {{else}} id {{end}}SELECT id FROM orders -- {{.Note}}
-- ^ {{.Note}} is inside a comment and has no effect分岐の組み合わせが256通りを超える(独立した{{if}}が9個以上で、512通り以上になる)と、全組み合わせは検査されず、代表的な組み合わせだけが検査される。-strictを付けると次の診断で知らされる:
sqlshape: 512 branch combinations exceed 256: checked sparsely (all branches off, all on, each on alone); the runtime cannot compare renderings with the checked set
独立したAND条件の並びなら、この代表だけでも各条件の有無は網羅される。分岐同士が絡み合っている(ある分岐が別の分岐の中にある、ORDER BYとWHEREが連動する)なら見落としが起きうるので、テンプレートをGo側で選ぶ2つの文に分ける。分ければ全組み合わせの検査に戻る。
一部の展開でだけ起きる問題には、どの分岐で起きたかが末尾に付く。
field Order.Total is not selected in every branch [if@11:else]: make it a pointer so those branches leave it nil
if@11:elseは、テンプレートの11バイト目にある{{if}}が偽だった展開、という意味。range@120:x2なら120バイト目の{{range}}が2要素だった展開。すべての展開で共通の問題は、この接尾辞なしで一度だけ報告される。