検査器はパッケージ内のsqlshape.Query[R, P](template)、sqlshape.One[R, P](template)、postgres.Copy[R](...)、postgres.MatView(...)(PostgreSQL)をすべて見つけ、テンプレートを分岐の全組み合わせに展開し(templates.ja.md)、展開した各SQLをschema.sqlに対して解析して、その結果をGoの型と突き合わせる。このページは、書く場面ごとに、何がNGで何がOKかを、実際に出る診断と一緒に並べたもの。診断は英語で出るので、そのまま載せている。規則はPostgreSQLとMySQLで同じである。例はPostgreSQLのもので、規則がデータベースの名前・番号・型を使う箇所(制約名、Go型の表、診断のエラーコード)はpostgres.ja.mdとmysql.ja.mdにそれぞれのものがある。
検査器の入口は2つある。go vet -vettool=sqlshape(またはsqlshape ./...)はGoのパッケージを対象に実行され、Query / OneのテンプレートにあるSQLをGoの型と突き合わせる。sqlshape check file.sqlは、Goの中にないSQLに対して同じ解析器と同じスキーマの規約を実行する(第2部)。
三部に分かれる。第1部は何も宣言しなくても全部の文にかかる検査。結果とパラメータの形、型の意味、失敗モード、Oneの証明。第2部はschema.sqlに宣言して初めてかかる規約。読み取り条件、列の固定、集約、状態機械、ラベル付きの列。第3部は文の外側の検査。文を囲むGoコードと、スキーマ自体。
- 第1部 — すべての文にかかる検査
- 第2部 — スキーマが宣言する規約
schema.sqlのディレクティブ- 宣言の仕組み
- 必ず付ける読み取り条件(
visible where) - 列を必ず固定する(
pinned、-require-columns) - テーブルを直接読まない(
via view、-no-table-reads/-no-tables) - 表をまたぐ述語には証人が要る(
EXISTS) - 集約にはルート経由で触り、1文で1つだけ触る(
aggregate) - ステータス列は宣言した遷移でしか動かさない(
transitions) - 追記専用、対になる書き込み、1行だけの削除(
never、paired、single) - ラベル付きの列は許された文脈でしか読まない(
sensitive、may read) - 呼び出し元ごとに規約を変える(
context) - Goの外のSQLにも同じ規約を適用する(
sqlshape check)
- 第3部 — 文の外側
結果を受ける構造体Rについて、検査器はすべての結果列に受けるフィールドがあり、すべてのフィールドに対応する列があり、型とNULLの扱いが合っていることを確かめる。分岐のあるテンプレートでは、展開したすべてのSQLについて確かめる。
対応はcol:"..."タグ、db:"..."タグ、フィールド名をsnake_caseにしたもの、の順で探す。
NG
type Order struct {
ID int64
CustomerName string // field Order.CustomerName has no result column
}SELECT o.id, c.name FROM orders o JOIN customers c ON c.id = o.customer_id
-- ^ result column "name" has no field in OrderOK。列に別名を付けるか、タグで対応を指定する。
SELECT o.id, c.name AS customer_name FROM orders o JOIN customers c ON c.id = o.customer_idtype Order struct {
ID int64
CustomerName string `col:"name"`
}NG
SELECT id, id + 1 FROM orders
-- ^ result column 2 has no name: give it an alias (... AS name) so it can bind to a field of Order
SELECT o.id, c.id FROM orders o JOIN customers c ON c.id = o.customer_id
-- ^ result columns 1 and 2 are both named "id": alias one of them (... AS other_name)OK
SELECT id, id + 1 AS n FROM orders
SELECT o.id, c.id AS customer_id FROM orders o JOIN customers c ON c.id = o.customer_idNULLを受けられる型は、ポインタ、スライス、マップ、sql.Null*、pgtype.*のようなドライバのNULL可の値型、sql.Scannerを実装した型。
NG
type User struct {
ID int64
DeletedAt time.Time // field DeletedAt is time.Time but column "deleted_at" may be NULL (use a pointer, or tag it `col:",notnull"` if you know better)
}SELECT id, deleted_at FROM usersOK
type User struct {
ID int64
DeletedAt *time.Time
}補足。列がNULLになりうるかは、NOT NULL制約と主キー、WHERE句(deleted_at IS NOT NULLやdeleted_at = ...があればNULLではない)、外部結合(内側の列はNULLになりうる)、関数(引数がNULLでないstrict関数の結果はNULLでない、coalesce(x, 0)はNULLでない。ただし一部のstrictな組み込み関数・演算子は報告するものが無いとNULLを返す。meta ->> 'key'もその一つ)、ビュー自身のWHERE句から判定する。ビューは下敷きの列のNOT NULLをPostgreSQL自身と同じように動的に追いかける。後からALTER TABLE ... DROP NOT NULLがベーステーブルに入れば、ビューの連鎖を通じても、ビュー自身のWHERE句をくぐり抜けても反映される。判定より自分の方が正しいと分かっているなら、Go側はcol:",notnull"タグ(配列のフィールドに付けると要素についても主張する)、SQL側はテンプレートの-- sqlshape: not null deleted_at行で上書きできる。関数の戻り値はschema.sqlのCREATE FUNCTIONの直上に-- sqlshape: not nullと書く。 RETURNINGのold.colはINSERTの後、new.colはDELETEの後(PostgreSQL 18)、列の宣言に関わらずNULLになりうる。書き込みのその側には行が無い。
NG
type Order struct {
ID int64
Total string // field Order.Total is not selected in every branch [if@11:else]: make it a pointer so those branches leave it nil
}SELECT id {{if .WithTotal}}, total{{end}} FROM ordersOK
type Order struct {
ID int64
Total *string
}補足。選ばない分岐ではフィールドはnilのまま。どの分岐も選ばない列に対応するフィールドはhas no result columnになる。
情報を失いうる対応づけ(numericをfloat64で受ける、bigintをint32で受ける、など)は拒否ではなく注記付きで通る。本当に不適合な組(text列をint64フィールドで受ける、など)だけが拒否される。
OK(注記あり)
type Order struct {
ID int64
Total float64 // field Total: numeric into float64 loses precision
}SELECT id, total FROM ordersOK(注記無し)
type Order struct {
ID int64
Total string // 全桁を保つ。decimal.Decimal(shopspring/decimal)でもよい
}array_agg(row(...))、array_agg(t)、row(...)、複合型の列は構造体、または構造体のスライスで受ける。無名のrow(...)はフィールドの位置で、名前付きの複合型は名前と順序で対応づける。
NG。構造体のフィールドの順序が複合型の列の順序と違う。
-- schema.sql
CREATE TYPE order_item AS (sku text, qty integer);type Item struct {
Qty int32 // field Items.Qty is at position 1 but the row type's column 1 is "sku" (fields are scanned in order)
Sku string
}
type Order struct {
ID int64
Items []Item
}SELECT o.id, array_agg((i.sku, i.qty)::order_item) AS items
FROM orders o JOIN order_items i ON i.order_id = o.id
GROUP BY o.id(隣接する2つのフィールドを入れ替えると、片方だけでなく両方の位置がずれる。Skuもorder_item型の列2「qty」に来てしまうので、その位置のずれについても2つ目の指摘が出る。)
OK
type Item struct {
Sku string
Qty int32
}(PostgreSQLは、配列を保持する列自体がNOT NULLでも、配列の要素自体が非NULLであることは保証せず、検査器も一般には常設の注記を出す(PostgreSQLの型のT[]の行を参照)。ここでは検査器がそれを証明できる: order_itemの行コンストラクタは、自分自身のフィールドの非NULL性とは関係なく決してNULLにならないので、array_agg((i.sku, i.qty)::order_item)は注記を持たず、このOK例は注記なしで通る。)
OK
var Count = sqlshape.Query[int64, struct{}](`SELECT count(*) FROM orders`)NG
var Count = sqlshape.Query[int64, struct{}](`SELECT id, total FROM orders`)
// R is int64 but the query returns 2 columnsOK
type Base struct {
ID int64
CreatedAt time.Time
}
type Order struct {
Base
Total string
}SELECT id, created_at, total FROM ordersNG。2つのフィールドが同じ列を受けようとしている。
type Order struct {
Base
ID int64 // Order: fields Base.ID and ID both bind to column "id"
Total string
}補足。名前付きの構造体フィールド、またはcol:"..."タグを付けた埋め込みフィールドは、平坦化されずにネストした行として扱われる。
列をどのGo型で受けられるか、パラメータをどのGo型で渡せるかは、データベースとそのドライバが決める。PostgreSQLの表、MySQLの表。どちらも列を受けるときとパラメータを渡すときに同じに従う。PostgreSQLでは、表に無い型や自前の型で受けたい型を、Goの型に// sqlshape: type <PGの型>と書いて結びつける。変換はその型自身のsql.Scanner / driver.Valuerが行う(MySQLには結びつける先の名前付きの型が無い)。
{{.X}}はSQLの中ではパラメータになる(PostgreSQLでは$n、MySQLでは?。検査器はどちらでも$nと番号を振る)。検査器はパラメータが使われている場所からSQL側で必要な型を推論し(WHERE id = $1ならbigint、= ANY($1)なら配列)、Pの対応するフィールドの型がそれに合うことを確かめる。型の対応はデータベースのGo型の表に従う。
NG
type Params struct {
ID int64 // parameter .ID is int64 but SQL expects uuid
}SELECT id, email FROM users WHERE id = {{.ID}} -- id は uuidOK
type Params struct {
ID uuid.UUID
}補足。stringはどの型のパラメータにも渡せる(テキスト形式で送られ、PostgreSQL側で解釈される)。パラメータが渡す先の列より広い型だとオーバーフローの注記が出る。integerの列にint64ならparameter .ID: int64 into integer may overflow(realの列にfloat64でも同様)。配列パラメータでも要素ごとに同じ注記が付く。smallint[]に[]int64ならparameter .Tags: int64 into smallint may overflow。
{{if .Name}} AND name = {{.Name}} {{end}}のように、値が無いことを分岐で表すフィールドはポインタかスライスにする。非ポインタのstringはNULLを送れないので、常に値がある前提になる。
NG。enumのパラメータがポインタでない(-strict)。
type Params struct {
Status OrderStatus // parameter .Status is a non-pointer OrderStatus: its zero value "" is not a label of enum order_status and fails at runtime (SQLSTATE 22P02) when unset
}OK
type Params struct {
Status *OrderStatus
}(-strictでは、orders.statusに触れるパッケージにはその列自体のenum助言、orders.status is enum order_status: a seeded lookup table ...も別途出る。上のパラメータについての指摘とは別の、列についての指摘。)
{{.Filter.Name}}はPのフィールドFilterのフィールドNameを指す。{{range .Items}} … {{.Sku}} … {{end}}の中の{{.Sku}}はスライスItemsの要素型のフィールドを指す。
OK
type Params struct {
Filter struct{ Name *string }
Items []struct{ Sku string; Qty int32 }
}SELECT id FROM products
WHERE true {{if .Filter.Name}} AND name = {{.Filter.Name}} {{end}}
AND (false {{range $i, $it := .Items}} OR sku = {{$it.Sku}} {{end}})素朴なsku IN ({{range}}...{{end}})は空長で安全ではない。.Itemsが空だとsku IN ()となり構文エラーになる。検査器は.Itemsが取りうる長さ(0、1、2、……)を全て試し、それが構文エラーを引き起こすことをそのまま報告する。rangeをこの用途で使うときは、どの長さでも文法的に妥当な形にする必要がある。上のfalse {{range}} OR ... {{end}}の形(あるいはWHERE true {{range}} OR (...) {{end}}の形)がそれにあたる。
SQL側が複合型を期待する位置には構造体を、その配列を期待する位置には構造体のスライスを渡す。フィールドと複合型の列の対応づけはネストした行と同じ規則。
OK
-- schema.sql
CREATE TYPE order_item AS (sku text, qty integer);
CREATE FUNCTION place_order(customer_id bigint, items order_item[]) RETURNS bigint ...type Item struct {
Sku string
Qty int32
}
type Params struct {
CustomerID int64
Items []Item
}SELECT place_order({{.CustomerID}}, {{.Items}})type Params struct {
ID int64
Limit int32 // sqlshape: parameter field Limit is never used by the template
}SELECT id FROM orders WHERE id = {{.ID}}type NewOrder struct {
CustomerID int64
Status OrderStatus // parameter .Status always sends a value into orders.status, so its DEFAULT never applies: decide which side owns the default (make the column conditional with {{if}} to use the database's)
}INSERT INTO orders (customer_id, status) VALUES ({{.CustomerID}}, {{.Status}})(ここのStatusも非ポインタのOrderStatusなので、前節の「NULLを渡しうるパラメータはポインタにする」の指摘も出るし、orders.status自体のenum助言も出る。このNG例だけで1つでなく3つの指摘になる。)
OK。データベースの既定値を使うなら列ごと分岐にする。アプリケーションが常に決めるなら、列のDEFAULTを外す。
INSERT INTO orders (customer_id {{if .Status}}, status{{end}})
VALUES ({{.CustomerID}} {{if .Status}}, {{.Status}}{{end}})(このOK例でもorders.statusのenum助言だけは出る。前節のOK例と同じ。)
bigintやtextのままでは区別できない値、たとえばenumのラベル、テーブルのID、金額の単位は、Goではnamed typeで表す。検査器はnamed typeをSQL側の意味(enum、lookupテーブルのキー、CHECKの値集合、主キー、ドメイン)に結びつけ、食い違う使い方を報告する。
Goの型を「これはこのテーブルのID」「これはこのenum」と宣言する場所はどこにもない。素のnamed typeは、意味を持つ列に対して文が初めてそれを渡すか受けた瞬間に意味を獲得し、以後その型を使うすべてのパッケージでそれを保つ。
type UserID int64 // これだけ。タグもコメントも登録も無い// 1. 最初の対応づけで束縛される。UserIDはここからusers.idを表す
var User = sqlshape.One[User, struct{ ID UserID }](`SELECT id, email FROM users WHERE id = {{.ID}}`)
// 2. 以後の対応づけはその束縛と照合される
var Total = sqlshape.One[int64, struct{ ID UserID }](`SELECT total FROM orders WHERE id = {{.ID}}`)
// sqlshape: parameter .ID is UserID, which stands for key users.id elsewhere, but here meets key orders.id文字列型がenumの列やseed済みlookupテーブルのキーに渡されれば同じことが起き(以後その定数がラベルと比較される)、整数型がドメインの列に渡されればその単位を持つ。どの文が先かは関係ない。型の束縛は全部集めて突き合わせ、食い違えば報告する。そういう列に一度も対応づけられない型は検査されない。束縛は解析のfactとして書き出されるので、あるパッケージで宣言して別のパッケージで使う型も、一つの型に一つの意味として扱われる。
なぜこうしているか。sqlshapeは何も生成せず、登録APIも持たないので、Goのコードは通常のGoのまま。使用箇所で束縛すれば、型は意味を持つ場所でだけ検査され、事前に宣言する必要がない。
enumの列、seed済みlookupテーブルのキー、CHECK (col IN (...))の付いた列に使われたnamed string typeについて、型付き定数とラベルを両方向に比較する。
-- schema.sql
CREATE TABLE order_statuses (code text PRIMARY KEY, label text NOT NULL);
INSERT INTO order_statuses VALUES ('pending', '保留'), ('paid', '支払済'), ('shipped', '発送済');
CREATE TABLE orders (..., status text NOT NULL REFERENCES order_statuses(code));OrderStatusとorder_statusesは名前で結びついているわけではない。型は、文の中で列と対応づけられた箇所で値集合に束縛される。下の文では{{.Status}}がorders.statusに流れ、その列の外部キーがorder_statuses(code)を指しているので、OrderStatusはこのlookupテーブルのGo側になる。束縛はfactとして書き出され、その型を使うすべてのパッケージに適用される。列に一度も対応づけられない型は検査されない。
var ByStatus = sqlshape.Query[Order, struct{ Status OrderStatus }](`
SELECT id, total FROM orders WHERE status = {{.Status}}`)NG
type OrderStatus string
const (
Pending OrderStatus = "pending"
Paid OrderStatus = "paid"
Canceled OrderStatus = "canceled" // sqlshape: OrderStatus has constant "canceled" which is not a label of value set of order_statuses.code (lookup table)
)
// sqlshape: value set of order_statuses.code (lookup table) has label "shipped" but OrderStatus has no constant for itOK
const (
Pending OrderStatus = "pending"
Paid OrderStatus = "paid"
Shipped OrderStatus = "shipped"
)補足。OrderStatus("typo")のような変換はsqlshape: OrderStatus("typo") is not a label of ...、すべてのラベルを扱っていないswitchはsqlshape: switch on OrderStatus does not handle ... labels: shippedとして報告される。型にKnown() boolを実装しておくと、実行時にこのビルドが知らないラベルを受け取ったとき、行マッパーが*UnknownLabelErrorを返す。値集合の置き場としてはenumよりseed済みlookupテーブルを推奨する(migrations.ja.md)。
主キーの列、または外部キーで主キーから派生した列に使われたnamed typeは、そのテーブルのIDとして扱われる。束縛は値集合と同じく使用箇所から来る。下のUserIDがusers.idを表すのは、どこかの文がusers.id(かそこへの外部キー)の位置にそれを渡したから。
type UserID int64
type OrderID int64
var User = sqlshape.One[User, struct{ ID UserID }](`SELECT id, email FROM users WHERE id = {{.ID}}`)NG
type Params struct {
ID UserID // sqlshape: parameter .ID is UserID, which stands for key users.id elsewhere, but here meets key orders.id
}SELECT total FROM orders WHERE id = {{.ID}}OK
type Params struct {
ID OrderID
}ドメインの列に使われたnamed typeはそのドメインに結びつけられる。SQLの中でも、ドメインは基底型とは別の単位として扱う。PostgreSQL自身は基底型に戻して演算を許すが、検査器は報告する。
-- schema.sql
CREATE DOMAIN yen AS bigint;
CREATE DOMAIN gram AS integer;
CREATE TABLE products (id bigint PRIMARY KEY, price yen NOT NULL, weight gram NOT NULL);NG
SELECT id FROM products WHERE price + weight > 1000
-- ^ domain mismatch: yen + gram: operands must share the domain (cast to the base type to drop it)type Params struct {
Max int64 // sqlshape: parameter .Max carries domain yen as a plain int64; declare a named type to have it checked (-strict)
}OK
type Yen int64
type Params struct {
Max Yen
}SELECT id FROM products WHERE price > {{.Max}}補足。リテラルとパラメータは相手の単位を引き継ぐ。price + 100、price * 2、abs(price)、coalesce(price, 0)はyenのまま。単位を外したいときは基底型へ明示的にキャストする(price::bigint + weight::bigint)。
type Event struct {
At time.Time // field At: timestamp without time zone into time.Time: which zone the value is in becomes the application's implicit choice (prefer timestamptz)
Day time.Time // field Day: date into time.Time: a zone conversion can move the day (keep it at UTC midnight or use a civil date type)
}timestamptzならこの注記は出ない。dateをtime.Timeで受けるなら、UTCの0時として扱うことをコードの側で決めておく。
INSERT / UPDATE / DELETE / MERGEは制約違反で失敗しうる。検査器は各展開について違反しうる制約を列挙し、テンプレートがそれを-- sqlshape: expect行で宣言していることを確かめる。実行時には、宣言した名前でConstraintErrorが返る(runtime.ja.md)。
NG
INSERT INTO customers (email, name) VALUES ({{.Email}}, {{.Name}}) RETURNING id
-- ^ may violate customers_email_key (UNIQUE (email) on customers, SQLSTATE 23505); add `-- sqlshape: expect customers_email_key` to the template or make it impossibleOK
-- sqlshape: expect customers_email_key
INSERT INTO customers (email, name) VALUES ({{.Email}}, {{.Name}}) RETURNING id_, err := postgres.First(ctx, db, CreateCustomer, p)
if postgres.Violates(err, "customers_email_key") { ... }補足。列挙されるのは、一意制約と主キー、外部キーの両方向(挿入する行が存在しない親を参照する、削除する行がまだ子から参照されている)、EXCLUDE制約、CHECK、ドメインのCHECK、書き込む値がNULLになりうる場合のNOT NULL。パラメータ由来のNULLは、そのフィールドがnilを表せない型(stringなど)なら候補から外れる。 NOT ENFORCEDと宣言したCHECKと外部キー(PostgreSQL 18)は決して失敗しないので、列挙されない。
参照される側のキーを変えるDELETEやUPDATEは、外部キー自体が変更を拒む場合(NO ACTION / RESTRICT)だけでなく、そのON DELETE / ON UPDATEアクションが参照する側の行に対して行うことを通じても失敗しうる。SET NULLは参照列のNOT NULL制約に触れうる、SET DEFAULTは同じ外部キーに再び触れうる(デフォルト値が親に存在するとは限らない)うえデフォルトが無ければ同じNOT NULLにも触れうる、CASCADEは参照する側の行を削除(または更新)し、それはさらに一段下で同じように検査される——したがってON DELETE CASCADEが連鎖する外部キーは、何段も先のテーブルで失敗することがある。
WITH [LOCAL | CASCADED] CHECK OPTION付きのビューへの書き込みは、SQLSTATE 44000でも失敗しうる(PostgreSQL自身のこのエラーは制約名を持たないため、注釈の無いトリガーのSQLSTATEと同様に、expect行はSQLSTATEそのものをキーにする)。CASCADED(オプションを修飾子無しで書いたときの既定)は、このビューだけでなく、さらに下位にある更新可能なビューのWHERE句も検査対象にする。
NG
-- sqlshape: expect orders_total_check
-- ^ expects orders_total_check but no expansion can violate it
UPDATE orders SET note = {{.Note}} WHERE id = {{.ID}}expect行は「この文が失敗しうる理由の正確な一覧」として保たれる。不要になった宣言は消す。
失敗モードのキーは、データベースが制約に付ける名前か、NOT NULLならtable.columnである。診断・expect行・実行時エラーで同じ文字列になる。名前を付けなかった制約に付く名前と、制約名を持たない失敗(トリガのエラー、ビューのWITH CHECK OPTION)のキーはデータベースごとに違う。PostgreSQL、MySQL。
検査器はPL/pgSQLのトリガー本体を読むので、中のRAISE EXCEPTION ... USING ERRCODE = 'P0401'だけでP0401は失敗モードに加わる(ERRCODEの無いRAISEはP0001)。トリガーの関数の上に書く-- sqlshape: error <code> = <Name>行は、そのコードに名前を付ける:
-- schema.sql
-- sqlshape: error P0401 = OrderTooLarge
CREATE FUNCTION check_order_size() RETURNS trigger LANGUAGE plpgsql AS $$
BEGIN
IF NEW.total > 1000000 THEN RAISE EXCEPTION 'order too large' USING ERRCODE = 'P0401'; END IF;
RETURN NEW;
END $$;
CREATE TRIGGER order_size BEFORE INSERT OR UPDATE ON orders FOR EACH ROW EXECUTE FUNCTION check_order_size();NameはGoの識別子でなければならない。プログラム側はsqlshape.Errorでそれを写し取り、生のコードの代わりにそれで失敗を読み戻す:
var OrderTooLarge = sqlshape.Error("P0401")
if postgres.Violates(err, OrderTooLarge) { ... }expect行はその失敗をコードでもNameでも綴れる——読みやすい方を書けばよく、両方どちらも取り残されない:
-- sqlshape: expect OrderTooLarge, orders_customer_id_fkey
INSERT INTO orders (customer_id, total) VALUES ({{.CustomerID}}, {{.Total}})トリガーが付いているテーブルへの、トリガーが発火するイベント(この例ではINSERTとUPDATE)の失敗モードに、そのSQLSTATEが加わる。
go vetはsqlshape.Error宣言を両方向で検査する。コードがスキーマの宣言どおりの、まさにそのNameのものであること、そしてパッケージの文が起こしうる名前付き失敗モードすべてに、プログラムのどこかに(自分自身か、参照が届く他パッケージの宣言か)そういう宣言があること——宣言済みの型の束縛が届く範囲と同じ範囲で判定する。
NG
var Wrong = sqlshape.Error("P0401")
// sqlshape: schema names function check_order_size's error P0401 "OrderTooLarge", not "Wrong"var A = sqlshape.Error("P0401")
var B = sqlshape.Error("P0401")
// sqlshape: A and B both declare sqlshape.Error("P0401")var Ghost = sqlshape.Error("P9999")
// sqlshape: the schema declares no error "P9999"// このパッケージから検査器が届く範囲にP0401を宣言するvarが無い。文のexpect行はそれを名指している
// sqlshape: P0401 (raised by trigger order_size on orders as OrderTooLarge, SQLSTATE P0401)
// has no `var OrderTooLarge = sqlshape.Error("P0401")` declared in this program名前を付けるかどうかは任意である。-- sqlshape: error注釈の無いスキーマは、expect行もViolatesもすべてコードだけで書けて読める。
MySQLもトリガー本体を同じように読み、注釈の代わりになるのは自前のSIGNALである:
-- schema.sql
-- sqlshape: error 30001 = OrderTooLarge
CREATE TRIGGER order_size BEFORE INSERT ON orders FOR EACH ROW
BEGIN
IF NEW.total > 1000000 THEN
SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'order too large', MYSQL_ERRNO = 30001;
END IF;
END;-- sqlshape: expect OrderTooLarge, fk_orders_customer
INSERT INTO orders (customer_id, total) VALUES ({{.CustomerID}}, {{.Total}})expect行とmysql.Violatesが判定に使うキーは、SIGNALにMySQL自身が付けるもの——MYSQL_ERRNOを設定していればその10進表記(30001)、無ければSQLSTATE(45000)——であることに変わりはない。項目をそのコードで綴っても注釈のNameで綴っても同じで、Violatesもランタイムもスキーマを読まないので、sqlshape.Error("30001")から作ったsqlshape.Failureもコードそのものを運んでおり、そのコードで判定される。MYSQL_ERRNOを設定しないときのキー、SELECT ... INTOとトリガーが自分の表に書く場合の番号はmysql.ja.mdとmysql-errors.ja.mdにある。
PL/pgSQLの一部の文はRAISEが無くても失敗しうる。検査器はそのSQLSTATEも、明示的なRAISEと同様に本体の失敗モードへ加える。
SELECT ... INTO STRICTとEXECUTE ... INTO STRICTは、問い合わせが1行も返さなければP0002(no_data_found)、2行以上返せばP0003(too_many_rows)。問い合わせが1行以下だと証明できる場合(Oneが使うのと同じ証明)はP0003を落とす。- マッチする
WHENが無くELSEも無いCASE文は20000(case_not_found)。 ASSERTは条件が偽ならP0004(assert_failure)。
RAISE ... USING ERRCODE = <式>は、<式>が文字列リテラルの場合、リテラルの初期値のまま再代入されない変数の場合、あるいはEXCEPTIONハンドラの中で捕捉したSQLSTATEをそのまま再送出するSQLSTATEそのものの場合に、静的に解決する。それ以外の式はSQLSTATEを特定できないままとし、P0001と決め打ちせずその旨を検査器が報告する。
BEGIN ... EXCEPTION WHEN ... ENDブロックは、WHENの条件がカバーするものをすべて捕捉する — 条件名、エラークラス名(そのクラスの全コードにマッチする。たとえばintegrity_constraint_violationはどの23xxxにもマッチする)、リテラルのSQLSTATE '...'、OTHERSのいずれでも。捕捉された失敗モードは呼び出し元まで届かない。ハンドラ自身が新たに送出するものは届く。
ユーザー定義関数の呼び出しは、その本体(LANGUAGE sqlでもplpgsqlでも)の失敗モードを引き継ぐ。本体の書き込みが違反しうる制約、その書き込みが発火させるトリガー、本体が呼ぶ関数、本体が送出するSQLSTATEである。
SELECT place_order({{.CustomerID}}, {{.Note}})
-- ^ may violate orders_customer_id_fkey (FOREIGN KEY (customer_id) on orders REFERENCES customers, SQLSTATE 23503, through place_order()); add `-- sqlshape: expect orders_customer_id_fkey` to the template or make it impossible補足。本体でパラメータに由来するとわかったNOT NULLは、呼び出し側の引数まで辿られる。STRICTな関数はNULLでは呼ばれないので、その引数からの違反は候補から外れる。
MySQLもストアドFUNCTIONの呼び出しとCALLされるPROCEDUREを同じに扱う。本体のSIGNAL、本体自身の書き込みが違反しうる制約、その書き込みが発火させるトリガーが、呼び出した文まで届く。
-- schema.sql
-- sqlshape: error 30001 = OrderTooLarge
-- sqlshape: not null
CREATE FUNCTION place_order(cust_id BIGINT UNSIGNED, amount DECIMAL(10,2)) RETURNS BIGINT
BEGIN
IF amount > 1000000 THEN
SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'order too large', MYSQL_ERRNO = 30001;
END IF;
INSERT INTO orders (customer_id, total) VALUES (cust_id, amount);
RETURN LAST_INSERT_ID();
END;SELECT place_order({{.CustomerID}}, {{.Total}})
-- ^ may violate 30001 (raised by function place_order() as OrderTooLarge, MySQL error 30001);
-- add `-- sqlshape: expect OrderTooLarge` to the template or make it impossibleMySQL固有のもの——引数の数が違う場合(1318)、呼び出し側自身が読むか書く表に関数自身が書く場合(1442、実行のたびに)、CALLのOUT引数と結果列の規則——はmysql-errors.ja.mdにある。
sqlshape.One[R, P]は1行以下しか返さないと宣言するもので、検査器はそれを展開ごとにスキーマから証明する。証明できなければエラー。実行時にはGetは無ければErrNoRows、Findは有無を返し、データベースが証明に反して2行返したらどちらもErrManyRowsを返す。
NG
var ByName = sqlshape.One[User, struct{ Name string }](`
SELECT id, email FROM users WHERE name = {{.Name}}`)
// One: cannot prove at most one row: users: no unique key is fixed by equality (keys: (id), (email))OK
var ByEmail = sqlshape.One[User, struct{ Email string }](`
SELECT id, email FROM users WHERE email = {{.Email}}`)補足。1行以下と言えるのは、FROMに現れるすべてのテーブルについて、その一意キー(主キー、UNIQUE、一意インデックス、またはWHERE句が同じ条件を含む部分一意インデックス)がリテラル・パラメータ・外側の参照・相関の無いスカラーサブクエリのいずれかと等値で固定されているとき。何が固定になるかは次のとおり。
col = NULLは何も固定しない(決して真にならない)col IS NOT DISTINCT FROM vは、列がNOT NULLでvが既知かつNULLでなければ固定する- 要素1個の
col = ANY(ARRAY[v])はcol = vと同じ - 列へのキャスト(
GROUP BY status::text)は透かして見る - 等値はJOIN(外部結合のON句はNULLになりうる側だけを固定する)、ビュー、サブクエリ、CTEを通して追跡する
キーに関わらずそれ自体で1行以下と見なすもの: GROUP BYの無い集約、定数のLIMIT 0 / LIMIT 1、FROMの無いSELECT、1行のVALUES、1行のINSERT ... RETURNING。
決して1行以下にならないもの: FULL JOINと、DEFERRABLEと宣言したキー。一意性がコミットまで検査されないため、そのトランザクションが生きている間は同じ値を持つ2行が存在しうる。
時制キー(PRIMARY KEY (id, valid_at WITHOUT OVERLAPS)、PostgreSQL 18)は、スカラー列が等値で固定され、範囲列が既知の値と等しいか、要素型の既知の点を含む(valid_at @> {{.Day}}::date)ときに固定される。同じidの行どうしは範囲が重ならないので、1つの点を含む行は多くても1つである。既知側が範囲だと足りない(空の範囲はどの範囲にも含まれる)。重なり(&&)でも足りない。
NG
var Find = sqlshape.One[User, struct{ ID *int64 }](`
SELECT id, email FROM users WHERE true {{if .ID}} AND id = {{.ID}} {{end}}`)
// One: cannot prove at most one row: users: no unique key is fixed by equality (keys: (id), (email)) [if@45:else].IDがnilの分岐では条件が無くなり、全行が返る。それを見つけるのがこの検査の意図なので、この文はQueryにするか、.IDを非ポインタにして分岐を外す。
postgres.Copy[R]("order_items", "order_id", "line_no", ...)はINSERTと同じように検査される。テーブルと列が存在すること、各列の型がその列に値を入れるフィールドと合うこと、指定しなかった列にはすべて既定値があるか生成列であること。
NG
type Item struct {
OrderID int64
Sku string
}
var Load = postgres.Copy[Item]("order_items", "order_id", "sku")
// Copy into order_items: column "line_no" is NOT NULL without a default and is not copiedOK
type Item struct {
OrderID int64
LineNo int16
Sku string
}
var Load = postgres.Copy[Item]("order_items", "order_id", "line_no", "sku")チームの規約のうち、SQLの形として現れるものは検査器に強制させられる。論理削除の条件を必ず付ける、テナント列で必ず絞る、テーブルを直接読まずビューを通す、ステータス列は決めた遷移でしか動かさない、といったもの。規約はschema.sqlの、対象のテーブルの直上に書く。宣言しない限り何も適用されない。
schema.sqlに書けるディレクティブの一覧と、書く場所。規約の中身は以下の各節で説明する。テンプレートの中に書くディレクティブはtemplates.ja.mdにある。
| ディレクティブ | 置く場所 | 意味 |
|---|---|---|
-- sqlshape: postgres 17 / postgres 18 |
先頭の行 | スキーマが前提とするPostgreSQLのバージョン。文はその文法とカタログで判定される(下記) |
-- sqlshape: mysql 8.4 |
先頭の行 | スキーマが前提とするMySQLのバージョン(下記) |
-- sqlshape: server sql_mode = '...' / server lower_case_table_names = 1 |
mysqlの行の後 |
MySQLのみ。サーバが既定と違う設定で動くときの、その設定(下記) |
-- sqlshape: visible where deleted_at IS NULL |
CREATE TABLEの直上 |
このテーブルを読む文はすべてこの条件を持たなければならない(require deleted_at IS NULL on readの略記) |
-- sqlshape: require pinned(tenant_id) / require pinned(version) on update, delete |
CREATE TABLE / CREATE VIEWの直上 |
そのリレーションに触る文すべてへの義務。述語、pinned(列)、immutable(列)、via view、never、paired(表)、singleのいずれかに、任意でon select, insert, update, deleteを付ける(下記) |
-- sqlshape: aggregate orders (order_items, order_notes) [lock version] |
ルートのCREATE TABLEの直上 |
これらの表で1つの集約を成す。子表はルートの鍵で固定し、1文は1集約にしか触らない。lockを付ければ書き込みはルートのバージョンを名指しする |
-- sqlshape: transitions status: draft -> submitted, submitted -> paid | cancelled |
CREATE TABLEの直上 |
この列は状態機械。SETするUPDATEはWHEREで現在の状態を前状態に固定する |
-- sqlshape: sensitive pii: email, phone |
CREATE TABLEの直上 |
この列はラベルを持つ。may read piiの文脈だけが参照できる(ビュー経由も同じ。マスクの式でラベルは外れる) |
-- sqlshape: context ops: waive pinned(tenant_id); require id = $1 on delete |
CREATE TABLE / CREATE VIEWの直上 |
名前つき文脈での義務の差分。パッケージコメントの// sqlshape: context ops、vetの-context、check -contextのいずれかで選ぶ |
-- sqlshape: unfiltered orders / waive orders pinned(tenant_id) |
CREATE VIEWの直上 |
ビュー定義自身が文としてopt-outする |
-- sqlshape: not null |
CREATE FUNCTIONの直上 |
この関数の戻り値はNULLにならない |
-- sqlshape: error P0401 = OrderTooLarge |
そのエラーを送出するCREATE FUNCTION(MySQLではCREATE TRIGGER / PROCEDUREも)の直上 |
エラーコードに名前を付け、expect行とViolatesでその名前を使えるようにする(下記)。PostgreSQLではPL/pgSQL本体のRAISEは注釈なしでもコードで検出される |
-- sqlshape: seed |
INSERT ... VALUESの直上 |
PostgreSQLのみ。このseedは追加のみで、宣言に無い行もテーブルに残す(migrations.ja.md) |
-- @migrate ... |
どこでも | マイグレーションの意図の宣言(migrations.ja.md) |
テーブル(またはビュー)は、そのテーブルに触る文が守るべき規則を宣言する。この規則を義務と呼び、文が自分の証明できることで義務を満たすことを履行と呼ぶ。一般形はCREATE TABLEかCREATE VIEWの直上のディレクティブ。
-- sqlshape: require <what> [on <kinds>]<what> |
文に求めること | onの既定 |
|---|---|---|
SQLのboolean式(deleted_at IS NULL、status <> 'closed' AND amount > 0、EXISTS (SELECT 1 FROM orders o WHERE o.id = order_id AND o.tenant_id = $1)) |
その表の行についてこれが成り立つこと。各conjunctがWHERE / ONから含意される(等値、IS NULL、IS NOT NULL)か、字面どおり現れる。EXISTSは証人が要る(後述) |
read |
pinned(tenant_id) |
読み・UPDATE・DELETEではその列を一つの値に固定する(= {{.X}}、リテラル、外側の参照)。INSERTでは値を入れる。その列に代入するUPDATEも、WHEREで固定していなければならない(固定しなければ行が別の値へ移る) |
all |
immutable(tenant_id) |
UPDATEでその列に代入しない | update |
via view |
その表を直接参照しない(onに書き込みを含めなければ、書き込みの対象にはできる) |
read |
never |
そういう文が存在しないこと。追記専用の表(require never on update, delete) |
write |
paired(outbox) |
同じ文で名指しの表にも書くこと(書き込みCTE) | insert |
single |
高々1行しか触らないと証明できること(Oneの証明) |
delete |
<kinds>はselect / insert / update / deleteのカンマ区切りか、まとめ書きのread(SELECTと、WHEREで行を読むUPDATE / DELETE / MERGEの対象)、write、all。文は表に対して実際にすることで判定される。MERGEの各枝はその枝の文種の書き込み(INSERT枝しかないMERGEはon updateの義務を負わない)、INSERT ... ON CONFLICT DO UPDATEはinsertとupdateの両方、TRUNCATEは全行のdelete、自動更新可能ビューを通した書き込みは基底表への書き込み。裏返すと、ビューに宣言した義務が縛るのはビューの読み手だけである — ビュー経由の書き込みは基底表の義務で判定され、ビュー自身の義務には決してかからないので、書き込みにも効かせたい規則は基底表に宣言する。宣言の中の$nは「行を見る前に決まっている何かの値」— パラメータ、リテラル、外側の参照 — を指し、その番号のパラメータという意味ではない。Goテンプレートの{{.X}}はそういう値の一つ。
require行ではないが義務に展開される宣言が3つある。visible where <expr>(require <expr> on readのもとの綴り)、aggregate、transitions。sensitiveは列にラベルを付ける。vetのフラグ-require-columns=tenant_id・-no-table-reads・-no-tablesは、その列を持つ全表へのrequire pinned(tenant_id)、全表へのrequire via view、require via view on allの略記で、文脈のwaiveは宣言と同じように解除できる。
ディレクティブは直下のCREATE TABLE・CREATE VIEW・CREATE FUNCTION・seedのINSERTに属する。それ以外の文(ALTER TABLE、COMMENT ON)の直上に書いたものは宣言にならず、スキーマの問題として報告される。
義務の履行経路は6つで、見ておくべきものは-strictが報告する。
- 文自身のWHERE / ON / SET
- ビュー経由。ビューの定義はスキーマ読み込み時にそれ自身が判定され、ビューの読み手はその中の表について再度判定されない(関数の本体も同じ扱いで、トリガー関数も含む。vetはスキーマの問題として、
sqlshape checkは発見として報告する) - 行レベルセキュリティのポリシー。USINGがそれを成り立たせていれば、行セキュリティの対象ロールについて履行される(表が
FORCE ROW LEVEL SECURITYでなければ-strictが所有者への注記を出す) - 複合外部キーをまたいで。
FOREIGN KEY (order_id, tenant_id) REFERENCES orders (id, tenant_id)があれば、order_id = orders.idで結合しorders.tenant_idが固定されていればorder_items.tenant_idも固定されている。ただしorder_items.tenant_idがNOT NULL(か、文がそう証明している)ときに限る。外部キーのどれか1列がNULLの行はどちらのデータベースでも制約の検査対象外で、親と結合できても値を揃えていない - 2の書き込み側の対称形。自動更新可能なビューに
WITH CHECK OPTIONが付いていれば、そのビュー経由の書き込みはビュー自身のWHERE(CASCADEDなら結合の有無を問わず下位の全ビューのWHEREも、LOCALなら自前のCHECK OPTIONを宣言した下位ビューのWHEREだけ)が固定する値でpinnedを履行する。サーバ自身がそれを満たさない行を拒む(PostgreSQLのSQLSTATE 44000、MySQLの1369ER_VIEW_CHECK_FAILED)からで、CHECK OPTIONを何も宣言していないビューはこの経路を持たない - 文側のopt-out。
-- sqlshape: unfiltered orders(述語型の義務)か-- sqlshape: waive orders pinned(tenant_id)(宣言どおりの綴りで1つ。waive ordersだけならその表の義務を全部)。opt-outは-strictで報告される
表の出現ごとに判定する。自己結合やサブクエリでもう一度その表を読めば、そこでも義務を負う。RETURNINGは判定しない。ビューに付けた義務はビューの読み手への義務で、ビューの定義文は中の表の義務を自分で履行する側。
-- schema.sql
-- sqlshape: visible where deleted_at IS NULL
CREATE TABLE memos (...);NG
SELECT id, body FROM memos WHERE user_id = {{.UserID}}
-- rows of memos are visible where deleted_at IS NULL: add that predicate for memos, or opt out with `-- sqlshape: unfiltered memos`OK
SELECT id, body FROM memos WHERE user_id = {{.UserID}} AND deleted_at IS NULL-- 意図的に全行を読む文
-- sqlshape: unfiltered memos
SELECT id, body FROM memos WHERE id = {{.ID}}補足。ビューも同じ規則で検査される。条件を持つビューを通して読めば、そのビューの利用側は条件を満たしたことになる。RETURNINGの列は直前に書いた行なので検査しない。
-- sqlshape: require pinned(tenant_id)
CREATE TABLE orders (...);NG
SELECT id, total FROM orders WHERE id = {{.ID}}
-- orders.tenant_id is not pinned: every statement on orders must fix tenant_id by equality (or assign it)OK
SELECT id, total FROM orders WHERE id = {{.ID}} AND tenant_id = {{.TenantID}}補足。INSERTはtenant_idに値を入れなければならない。行レベルセキュリティのポリシーがtenant_idを固定していれば、それでも要件を満たす。ただしテーブルがFORCE ROW LEVEL SECURITYでなければ所有者には適用されないので、-strictでorders.tenant_id is pinned by policy ... for roles subject to row security, not for the table's owner: FORCE ROW LEVEL SECURITY if the application connects as the ownerと注記される。
楽観ロックは同じ宣言をバージョン列に、書き込みだけに付けたもの。
-- sqlshape: require pinned(version) on update, delete
CREATE TABLE orders (..., version int NOT NULL DEFAULT 1);
CREATE TRIGGER orders_bump_version BEFORE UPDATE ON orders FOR EACH ROW EXECUTE FUNCTION bump_version();UPDATE orders SET status = {{.Status}} WHERE id = {{.ID}} AND version = {{.Version}}
-- OK。`AND version = ...`が無いと:
-- orders.version is not pinned: every statement on orders must fix version by equality (or assign it)補足。バージョンを上げるのはトリガ、見たバージョンを名指しするのは文、何も当たらなかったOneのUPDATEはErrNoRowsを返す(先を越された)。
-- sqlshape: require via view
CREATE TABLE orders (...);NG(-no-table-reads)
SELECT o.id, c.name FROM orders o JOIN customers c ON c.id = o.customer_id
-- table orders is read directly; with -no-table-reads application code reads views (tables are written, not read)OK
SELECT id, customer_name FROM order_summary補足。-no-table-readsはINSERT / UPDATE / DELETE / MERGEの対象としてテーブルを使うことは許す。-no-tablesは書き込みも含めてテーブルへの参照を一切禁じる(table orders is referenced directly; with -no-tables application code reads views and calls functions only)。
表をまたぐ述語はEXISTSで書く。文の側は、それを成り立たせる証人を持っていなければならない。同じレベルで本体が成り立つように結合した表(内部結合。外部結合のONは対象の行を絞らない)か、文自身の否定なしEXISTS / IN (SELECT ...)で本体が成り立つもの。
-- sqlshape: require EXISTS (SELECT 1 FROM orders o WHERE o.id = order_id AND o.tenant_id = $1)
CREATE TABLE shipments (...);OK(3つとも)
SELECT s.carrier FROM shipments s JOIN orders o ON o.id = s.order_id WHERE o.tenant_id = {{.T}}
SELECT carrier FROM shipments s WHERE EXISTS (SELECT 1 FROM orders x WHERE x.id = s.order_id AND x.tenant_id = {{.T}})
SELECT carrier FROM shipments WHERE order_id IN (SELECT id FROM orders WHERE tenant_id = {{.T}})NG(外部結合、否定したサブクエリ)
SELECT s.carrier FROM shipments s LEFT JOIN orders o ON o.id = s.order_id AND o.tenant_id = {{.T}}
SELECT carrier FROM shipments s WHERE NOT EXISTS (SELECT 1 FROM orders x WHERE x.id = s.order_id AND x.tenant_id = {{.T}})いくつかのテーブルは、まとまりでしか意味を持たない。注文には明細とメモが付き、注文を通さずに明細を足す人はいないし、「合計は明細の和に一致する」といった不変条件は明細1行ではなく注文全体について成り立つ。ドメイン駆動設計(DDD)はこのまとまりを集約と呼ぶ。1つのテーブルがルート、残りはその子、外の世界はルートのIDだけを持ち、1回の変更は1つの集約にしか触らない。アプリケーションはこれを規約で守る(集約ごとのリポジトリ、サービス層)が、規約は誰かがSQLを直接書いた時点で破れる。sqlshapeは、このうち文の形に現れる部分を検査器に守らせる。集約は義務の束で、ルートの直上に1行で宣言する。
-- sqlshape: aggregate orders (order_items, order_notes)
CREATE TABLE orders (...);各子表へのrequire pinned(<ordersへの外部キー列>) on all(子はルート経由で触る。鍵を固定するか、ルートの鍵で結合する)と、集約の全表へのalone(1文は1集約にしか触らない)に展開される。集約をまたぐ読みはビューの仕事で、どの集約にも属さない表(lookup)は自由に結合できる。子表はルートか、集約の他のメンバーへの外部キーを持っていなければならない。孫は直接の親の鍵を固定し、ルートまでの結合は1リンクずつ判定される。
NG
SELECT o.status, v.id FROM orders o JOIN invoices v ON v.order_id = o.id WHERE o.id = {{.ID}}
-- orders belongs to aggregate orders and this statement also touches invoices of aggregate invoices: one statement, one aggregate (read across aggregates through a view)lock <列>を付けると、ルートのバージョンが集約全体のロックになる。
-- sqlshape: aggregate orders (order_items, order_item_tags) lock versionルートはpinned(version) on update, delete(見たバージョンを名指しする)を負い、各子表はUPDATE / DELETEで、外部キーをたどった先(孫なら親を経由して)のルート行がそのバージョンであることのEXISTSを負う。
UPDATE order_items i SET qty = {{.Q}} FROM orders o WHERE o.id = i.order_id AND o.version = {{.V}} AND i.id = {{.ID}}補足。バージョンを上げるのはDBの仕事のまま(ルートのトリガ。子から上げるなら子のトリガがルートを更新する)。何も当たらなかったOneの書き込みはErrNoRowsを返す。
-- sqlshape: transitions status: draft -> submitted, submitted -> paid | cancelled, paid -> refunded
CREATE TABLE orders (...);ステータス列は小さな状態機械で、注文はdraftからsubmittedへ、そこからpaidかcancelledへ進み、draftからいきなりpaidにはならず、戻りもしない。この宣言はその機械を書き下したもの。検査は、その列をある状態にSETするUPDATEが、WHEREで現在の状態をその状態の前状態のいずれかに固定していること(status = 'submitted'、あるいは列挙した状態がすべて前状態ならstatus IN ('shipped', 'delivered'))。これはcompare-and-setで、2つのリクエストが同じ注文を同時にpaidにしようとしても、後の方はWHERE status = 'submitted'がもう当たらず何も更新しない。黙って二重に支払うことがない。OneのUPDATEならそれはErrNoRowsとして返る。
OK
UPDATE orders SET status = 'paid' WHERE id = {{.ID}} AND status = 'submitted'NG
UPDATE orders SET status = 'paid' WHERE id = {{.ID}}
-- orders.status: SET status = 'paid' must fix the current state in WHERE (status = 'submitted')
UPDATE orders SET status = 'paid' WHERE id = {{.ID}} AND status = 'draft'
-- orders.status: draft -> paid is not a declared transition (paid comes from submitted)補足。遷移先は宣言した状態のリテラルに限る。SET status = {{.S}}は前状態の集合を検査できないので拒否される。INSERTは遷移ではないので検査しない。この宣言はseed済みの(from_status, to_status)lookup表と同じ形で、DB側ではトリガで守れる。
-- sqlshape: require never on update, delete
CREATE TABLE ledger (...);
-- sqlshape: require paired(outbox) on insert
-- sqlshape: require single on delete
CREATE TABLE orders (...);neverは、そういう文が存在しないことを求める。ledgerへのUPDATE / DELETEは、単独でもWITHの中でも、ON CONFLICT DO UPDATEでもTRUNCATEでも更新可能ビュー経由でもNG(ledger is declared \require never on update, delete`: no statement may do this to it`)。
paired(outbox)はoutboxパターンのためのもの。書き込みと一緒に外の世界(メッセージキュー、webhook、別サービス)にも知らせたいとき、通知を直接送ると二つがずれる。行は書けたのにメッセージが消える、メッセージは出たのに書き込みがロールバックする。outboxパターンは、メッセージを変更と同じトランザクションでテーブルに書き、別プロセスがそこから配送する。pairedはその対を規則にする。ordersへのINSERTは同じ文でoutboxにも書かなければならないので、1行書き忘れただけで二つが離れることはなく、トランザクション層も要らない。
WITH o AS (INSERT INTO orders (...) VALUES (...) RETURNING id)
INSERT INTO outbox (id, payload) SELECT id, 'created' FROM o
-- OK。ordersだけのINSERTだと:
-- a write to orders must also write outbox in the same statement (a data-modifying WITH): require paired(outbox) on insert規則は「同じ文で両方の表に書く」であって、outboxに書く値とordersの行の対応は見ない(無関係な値を書いたoutbox行も通る)。対になっていることが約束で、中身は文の責任である。
singleは、DELETEが高々1行しか触らないことをOneと同じ証明で求める。
DELETE FROM orders WHERE id = {{.ID}} -- OK
DELETE FROM orders WHERE status = 'cancelled'
-- orders requires a single-row DELETE: fix a unique key by equality (the One proof)-- sqlshape: sensitive pii: email, phone
CREATE TABLE orders (...);
-- sqlshape: context billing: may read pii
CREATE VIEW order_contacts AS SELECT id, email, left(phone, 3) || '***' AS phone_masked FROM orders;ラベルの付いた列は、そのラベルをmay readする文脈(文脈)でしか参照できない。SELECT句でもWHEREでも同じ。値を書き込むのは読むことではないが、RETURNINGで返すのは読むこと(誰が渡した値でも、データベースの外に出る)。ラベルは列をそのまま通すビューと、その表の行を返す関数(RETURNS SETOF orders)を通って伝わり、式(マスクした列)で止まる。
SELECT email FROM orders WHERE id = {{.ID}} -- billing以外ではNG
-- orders.email is pii: this context may not read it (a context with `may read pii`, or a view that masks it)
SELECT email FROM order_contacts WHERE id = {{.ID}} -- これもNG。ビューがemailをそのまま通している
SELECT phone_masked FROM order_contacts -- OK。式にはラベルが付かない運用スクリプトはテナントを固定せずに実行される、分析者はビューしか読まない、請求だけは個人情報を読む。文脈(context)はその差分を表ごとに宣言し、パッケージかcheckの実行が一つを選ぶ。
-- sqlshape: require pinned(tenant_id)
-- sqlshape: context ops: waive pinned(tenant_id); require id = $1 on delete
-- sqlshape: context analyst: require via view
-- sqlshape: context billing: may read pii
CREATE TABLE orders (...);// Package ops は運用スクリプトを実行する。
//
// sqlshape: context ops
package opswaive <body> [on <kinds>]はその文脈の中で基底の義務を解除する(宣言どおりの綴りで指定する。onを付ければその文種だけ。waive pinned(tenant_id) on selectなら書き込みは縛られたまま)。require ...はその文脈だけの義務を追加する。may read <label>はラベルの読み取りを許す。パッケージはパッケージコメントの1行で文脈を指定する。無ければvetの-contextフラグ、sqlshape check -context opsはファイルに対して選ぶ。スキーマに無い文脈名や、ディレクティブとして読めないsqlshape: context行は報告される。文脈を選ばなければ基底の義務だけが適用される。
同じ判定は、Goコードの外のSQLにも使える。運用のUPDATE、backfill、エージェントがこれから流すクエリ。
$ sqlshape check -schema schema.sql ops.sql # または ... < ops.sql
ops.sql:2: ok orders: require pinned(tenant_id)
ops.sql:6: waived orders: require pinned(tenant_id): orders: `require pinned(tenant_id)` is waived by this statement
ops.sql:8: FAIL orders: visible where deleted_at IS NULL: rows of orders are visible where ...
sqlshape: 2 finding(s)
判定は全部、履行経路つきで出る(ok、ok(policy)、ok(fk)、waived)。そのスクリプトに何が許されたかの監査ログを兼ねる。-quietは失敗だけを出す。義務を履行できない文か解析に失敗する文があれば終了コード1(構文エラーの文はその行だけが失敗し、他の文は判定される)。スキーマ自身の関数本体とビュー本体は、vetと同じように最初に判定される。文の直上の-- sqlshape:行はその文のもので、-context・-require-columns・-no-tables・-no-table-readsはvetと同じく受け付ける。
schema.sqlは、どのバージョンのPostgreSQL向けに書かれているかを1回宣言する。この宣言が判定の土台になる。スキーマと全部の文を読む文法、型・関数・演算子を解決するカタログ、マイグレーション系コマンドが起動するPostgreSQLのバージョンが、ここで決まる。宣言の無いスキーマは読まない。規則の中でPostgreSQLに属するもの(Go型の表、制約名、Oneの証明の材料、ランタイム、マイグレーションコマンド)はpostgres.ja.mdにまとめてある。
-- sqlshape: postgres 18
CREATE TABLE ...NG
schema.sql(ディレクトリなら*.sqlのどれか)に宣言が無い- sqlshapeが持っていないバージョン(メッセージが対応バージョンを列挙する。17と18)
- 値の違う宣言が2つある
OK
- ファイルのどこに書いてもよい。同じ値なら繰り返しもよい
新しいバージョンだけが受け付ける構文(RETURNING old.*、WITHOUT OVERLAPS、NOT ENFORCED、VIRTUALな生成列は18のもの)は、古いバージョンを宣言していれば構文エラーになる。そのバージョンのサーバに流したときと同じ結果である。PostgreSQLのバージョンを上げる作業は、この数字を変えて検査器の報告を読むことになる。
同じ宣言でMySQLを名乗れる。そのときはMySQL自身の文法がスキーマと全部の文を読み、MySQLの規則が式に型を付け、文はgithub.com/kr9ly/sqlshape/mysql/v2がdatabase/sqlの上で実行する。
-- sqlshape: mysql 8.4
CREATE TABLE ...NG
- sqlshapeが持っていないバージョン(持っているのは8.4)
- 値の違う宣言が2つある、または
postgresも同時に名乗る
第1部と第2部の規則はMySQLのスキーマにも同じにかかる。判定するのがPostgreSQLではなくMySQLのアナライザーになるだけである。規則が名前・番号・型を使う箇所(制約名とエラー番号、Go型の表、Oneの証明の材料、ONLY_FULL_GROUP_BYの検査)でMySQLのものが何かは、MySQLに無くて検査しないものと合わせてmysql.ja.mdにある。
文の判定を変えるサーバ変数は、バージョンと並べて1行に1つ宣言する。検査器と本番の接続を同じ設定に揃えるための行である。宣言が無ければ検査器は、接続先のサーバではなく、Linuxで初期化したままのMySQL 8.4の既定値を仮定する。既定のsql_mode(ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION)とlower_case_table_names = 0である。
-- sqlshape: mysql 8.4
-- sqlshape: server sql_mode = 'ANSI,STRICT_ALL_TABLES'
-- sqlshape: server lower_case_table_names = 1
CREATE TABLE ...NG
- その方言が読まない変数。MySQLでは
sql_mode・lower_case_table_names・max_sp_recursion_depth以外、PostgreSQLでは今のところ全部(判定はサーバの既定値に従い、search_pathはスキーマ自身のSETで扱う) - 8.4に無い
sql_modeの名前、0・1・2以外のlower_case_table_names - 空白を含む値を文字列リテラルにしていない、同じ変数を2回宣言している
OK
sql_modeはカンマ区切りの名前(大文字小文字は問わない)、空文字列、組み合わせモードのANSIとTRADITIONAL。組み合わせはサーバと同じに展開するlower_case_table_namesは0、1、2
検査器はこれらに次のように従う。
- パーサは字句解析のビットをそのまま読む。
ANSI_QUOTESなら二重引用符は識別子、PIPES_AS_CONCATなら||はCONCAT(無ければOR)。IGNORE_SPACE、NO_BACKSLASH_ESCAPES、HIGH_NOT_PRECEDENCEもサーバどおりに効く。REAL_AS_FLOATならREAL列はDOUBLEではなくFLOAT(float32)になる ONLY_FULL_GROUP_BYは上のグループ検査(1055、1140、DISTINCTの3065)の有無を決める。HAVINGの名前解決(1054)とORDER BYの集約の規則(3029、3028)はサーバと同じくどのモードでもかかる- 厳密モード(
STRICT_TRANS_TABLESかSTRICT_ALL_TABLES)は2つを決める。文字列関数(CONCAT、SUBSTRING、LOWERなど)がNULL可になるのは厳密モードのときだけで、無ければNOT NULL列のCONCAT(name, 'x')は*stringではなくstringで受ける。NOT NULL列へのNULLが失敗モード(1048)になるのも厳密モードのときで、無ければ1行のINSERTとREPLACE(そのON DUPLICATE KEY UPDATEを含む)だけがNULLを拒み、複数行、INSERT ... SELECT、UPDATEは型の暗黙の既定値を警告付きで格納するので、検査器はそれらに1048を挙げない NO_UNSIGNED_SUBTRACTIONなら符号なし同士の減算は符号付き(uint64ではなくint64)になる- 残りの名前(
NO_ZERO_DATE、ERROR_FOR_DIVISION_BY_ZERO、NO_ENGINE_SUBSTITUTION、PAD_CHAR_TO_FULL_LENGTHなど)は実行時にしか効かない。検査器はそのまま受け付ける lower_case_table_names = 1は表名とビュー名を小文字にして持つ。サーバの報告と同じである(SELECT * FROM Usersは表usersを読み、factsも境界の検査もその名前で見る)。2は宣言どおりの綴りで持ち、大文字小文字を無視して照合する。0はUsersとusersを区別する(1146)。ディレクティブ(unfiltered、waive、義務)が名乗る表名も同じ規則で解決する。1と2ならどの綴りでも届き、0ならCREATEの綴りで書く
宣言は「文が走るサーバはこう設定されている」という約束であり、mysql.Verify(ctx, db, schemaSQL)がそれを確かめる。接続のセッションの@@sql_mode(DSNやプールの初期化が上書きしうる)とサーバのlower_case_table_namesを読み、宣言との差を返す。8.4が定義しないモード名は照合から外す(mysql.ja.md)。
実行時に組み立てた文字列でpgxやdatabase/sqlのQuery / Execを呼ぶことは、テンプレートの保証が届かない穴になる。
NG(既定の-raw-sql=constant)
rows, err := pool.Query(ctx, "SELECT id FROM orders WHERE "+where)
// sqlshape: SQL passed to Query must be a constant: a string built at run time can carry injected SQL; write the dynamic parts as a sqlshape.Query template (or pass -raw-sql=allow)OK
rows, err := pool.Query(ctx, "SELECT id FROM orders WHERE status = $1", status)補足。-raw-sql=forbidは定数であってもsqlshapeを通らない文をすべて拒否する(pgx.Query executes SQL outside sqlshape; with -raw-sql=forbid every statement goes through sqlshape.Query / One / postgres.Copy (or list the package in -raw-sql-allow))。移行中のパッケージは-raw-sql-allow=pkg/...で除外する。
-schemas=a_api,b_privateは、そのパッケージが参照してよいPostgreSQLのスキーマを限定する。1つのデータベースを複数サービスで使うときの境界。
SELECT id FROM c_private.orders
-- c_private.orders is outside the schemas this code may reference (a_api,b_private)schema.sqlは読み込み時に、それ自体も一度解析される。LANGUAGE sqlとLANGUAGE plpgsqlの関数の本体、ビュー、ポリシーはPostgreSQLがCREATE時に行うのと同じ型検査を受け、seedのINSERTは冪等性と型を検査される。問題はパッケージ内の最初のQueryの位置にsqlshape: schema ...として報告される。
PL/pgSQLの本体は、変数をスコープに入れた上で文ごとに検査される。DECLAREした変数はその型で(%TYPEと%ROWTYPEはスキーマから解決する)、record変数はそれを埋めたクエリの形で(FOR r IN SELECT ...、SELECT ... INTO r)、トリガー関数のNEWとOLDはCREATE TRIGGERで結びつけられた各テーブルの行の型で、それに関数のパラメータ、FOUND、TG_OPなどのトリガー変数、例外ハンドラ内のSQLSTATEとSQLERRM。代入とRETURNは宣言された型と、RETURN QUERYはRETURNS TABLEと照合される。変数と列の両方に当たる名前はPostgreSQLと同じく曖昧としてエラーになる。EXECUTEは定数文字列ならその文として検査されるが、実行時に組み立てた文字列は検査できないので、-strictで知らせる:
CREATE FUNCTION purge(tbl text) RETURNS void LANGUAGE plpgsql AS $$
BEGIN
EXECUTE 'DELETE FROM ' || quote_ident(tbl);
-- sqlshape: schema: function purge: line 3: EXECUTE runs SQL built at run time, which is not checked (a constant string would be)
END $$;-- schema.sql
CREATE VIEW order_summary AS
SELECT o.id, c.nmae AS customer_name FROM orders o JOIN customers c ON c.id = o.customer_id;
-- sqlshape: schema schema.sql: view order_summary: 42703: column c.nmae does not exist (at <schema.sqlでのバイトオフセット>)MySQLのトリガやストアドPROCEDURE / FUNCTIONの本体も、スキーマごとに1回、同じように検査される。NEW / OLD、DECLAREした変数や引数、制御構造、SELECT ... INTO、カーソル、CALL、SIGNAL / RESIGNALがスコープに入る。本体の作成時にサーバ自身が拒むものもスキーマの問題として報告される。本体についてMySQL固有のもの——制約名とエラー番号、SIGNALのキーの規則——はmysql-errors.ja.mdとmysql.ja.mdにある。
補足。行レベルセキュリティのポリシーもここで検査される。CREATE POLICYの条件式はboolean型で、集約やウィンドウ関数を含まず、ドメインの単位を守っていなければならない。行セキュリティを有効にしていないテーブルにポリシーがあれば報告する。ポリシーの条件を文の側で繰り返すことは要求しない。絞り込むのはデータベースの仕事である。
-strictではスキーマと文についての助言が加わる。一覧はflags.ja.md。