sqlshapeを開発する人(と、開発を手伝うエージェント)向けに、設計の判断を「何を決めたか・なぜか・何を棄てたか」の形で残す。振る舞いの説明は利用者向けのREADMEとdocs/にあり、ここには繰り返さない。判断が変わったら該当項目を書き換える。経緯はgitの履歴とコミットメッセージにある。
RDBMSを使うアプリケーションに要るのは4つ。SQLの構文と型の検査、型安全な値のバインド、結果の構造体へのマッピング、スキーマから導けるマイグレーション。既存のツールは、このうち2〜3個を満たして残りを落とすか、4つ揃えるためにSQLをDSLに翻訳させる形を取る(jOOQ / Kysely / Drizzle)。前の3つは「SQLが正」、最後は「アプリの型定義が正」と真実の源が割れていることが、その背景にあると見ている。sqlshapeは真実の源をschema.sqlとSQLそのものに置き、アプリの型は照合される側にする。
決めたこと。PostgreSQLのカタログ(pg_type / pg_proc / pg_operator / pg_cast / pg_aggregate)を本物のPGからCOPYでdumpしてTSVとして埋め込み、型変換はマニュアル10章の規則をそのまま実装する。埋め込みPostgreSQL(embedded-postgres)は差分テストの正解役としてだけ使い、検査時には起動しない。
理由。nullabilityはPGのDescribeが返さないので自前で式の木を歩く必要があり、そうするなら型も同じ木の走査に載せた方が解析器が1つで済む。WHEREやJOINの条件に現れる列参照はDescribeでは見えず、消費者索引(どの文がどの列を読むか)には全数の参照が要る。
棄てた案。① embedded PGにschema.sqlを流してPREPARE / Describeで聞く(当初案。起動コスト、nullabilityと参照の全数が取れない)。② libpg_queryの手法をanalyze.cまで広げて偽カタログで動かす(研究課題に近い)。③ PGをwasmで動かす(実用段階か未確認)。④ カタログをPGソースの.datから生成する(COPY dumpならデフォルト値解決済み・OID確定・拡張も同じ経路)。
忠実度の測り方。PGの回帰テストsrc/test/regressの全文を本物のPGと並走させ、パラメータ型・結果列・エラーの一致をgo testでゲートする(check/postgres/analyze/regress_test.go)。残る不一致は環境依存のcollation、RLSの再帰、権限、サーバー内部エラー、意図的な相違3件で、いずれも静的解析の外。
意図的な相違。ドメインの演算結果はドメインを保つ(PGは基底型に落とす)。配列リテラルの要素に対するCHECKの定数評価。PG 17のリライタが絡む1件。
決めたこと。SQLはGoのtext/templateのサブセットで書く。{{.X}}は必ず$nになり、分岐はif / else if / with / rangeのみ。rangeは0・1・2回で代表する。組み合わせが256を超えたら疎(全オフ・全オン・各単独オン)に落とす。実行時は描画結果を同じ分岐シグネチャの静的展開とバイト比較し、違えば実行しない。
理由。文字列結合が危険なのは出力集合が無限で不透明だから。分岐だけなら有限で、全展開すれば動的SQLもそのまま検査できる。2-way SQL(Doma / uroboroSQL)は同じ形だが既定の1形しか検査しない。
棄てた案。{{switch}}(else if eqで書ける。構文を増やさない)。分岐ごとに結果型が変わるクエリをタグ付きunionで受ける生成(省略可能な投影をnullableフィールドで受ける方が単純)。分岐の独立性の自動判定(疎検査の規則を固定した方が説明できる)。{{define}} / {{template}}(Goの定数連結で足りる。値がSQLテキストにならない唯一の共有機構を保つ)。
決めたこと。構造体もSQLも人が書き、検査器は合っているかだけを見る。go/analysisアナライザーとしてgo vet -vettoolに乗せる。構造体の書き起こしはSuggestedFixで出す。
理由。生成物が無いのでgoplsのリネーム・参照検索がそのまま効く。既存コードの定数SQL文字列はディレクティブ0個のテンプレートとして後付けで検査対象になる。検査できない文(非定数)を数えれば検査カバレッジが数値になる。
棄てた案。sqlcのようなクエリからの関数生成。goplsへの直接統合(サードパーティのアナライザーを読めない)。
決めたこと。スキーマの正はschema.sql(またはschema/ディレクトリ)。検査器はこれを空のカタログに載せて読み、テストはpgtestでこれを適用した本物のPGを立て、DBの実状態はsqlshape diff / applyが寄せる。マイグレーションファイルは持たない。
理由。「マイグレーションに書いたスキーマしか使えない」を制約として検査するのではなく、それ以外の状態が作れないようにする。副産物としてDROPの影響分析、ドリフト検出、死んだスキーマの検出が同じ基盤で出る。
決めたこと。Goのnamed typeがenum・lookupのキー・CHECKの値集合・キー列・ドメインに出会った箇所で、その型をその意味に束縛する。束縛はfactでパッケージを越え、以後の使用箇所すべてで照合する。明示的な登録APIは置かない。
理由。vetの思想(生成物なし・後付け可)に揃える。使っていない型は検査から外れるが、使っていなければ問題も起きない。
拡張。ID型はFKグラフから同一性を導く(orders.user_idの同一性はusers.id)。ドメインはSQLの中でも不透明な単位として扱い、PGが許すyen + gramを報告する。PGより厳しい型検査を意図している。
決めたこと。値集合の置き場としてlookupテーブル + FKを推奨し、-strictはenum列にそう言う。lookupテーブルの行はschema.sqlの普通のINSERT ... VALUESで書き、Relation.Seedとして読む。INSERTには冪等性の規則(定数キー・定数値・ON CONFLICTなし・キー重複なし)を課す。
理由。enumはDROP VALUEが無く、ラベルの削除や並び替えが「型の作り直し + 全列USING + 依存ビュー再作成」になる。lookupテーブルならMERGE 1文で済み、削除はFKが止め、属性も持て、ビュー経由で分析側にも名前が届く。検査精度はseedを値集合として読むことでenumと同等になった。
棄てた案。-- @dataのようなコメント構文で行を宣言する(INSERTなら型・NOT NULL・FK・CHECKの検査がそのまま効き、psqlにも流せる)。
決めたこと。書き込みの各展開が違反しうる制約をカタログから列挙し、テンプレートの-- sqlshape: expect行と両方向で比較する。無名の制約はPGの自動命名(<table>_<cols>_key / _fkey / _check / _pkey、ドメインは<domain>_check、NOT NULLはtable.column)で呼ぶ。ランタイムはクラス23のエラーを同じキーのConstraintErrorに写す。トリガーの独自SQLSTATEは-- sqlshape: error CODE = Nameで名前を与える。
理由。診断・宣言・実行時エラーが同じ文字列で結ばれ、どの違反を処理すべきかがコードに書かれた状態が保たれる。命名をPGに揃えるのは、実行時エラーが運ぶ制約名と一致させるため。
決めたこと。正はスキーマの-- sqlshape: error <code> = <Name>注釈であり、Goはそれをsqlshape.Error(code)で写すだけ(var OrderTooLarge = sqlshape.Error("30001"))。vetが両方向を見る——宣言のコードがスキーマの宣言どおりの、まさにそのNameのものであること、パッケージの文が起こしうる名前付き失敗モードのすべてに宣言が(自分のパッケージか、参照が届く他パッケージに)あること。ランタイムのViolatesは~stringを取るだけで、渡された値がFailureか生の文字列かを区別せず、スキーマも読まない——sqlshape.Error(code)が返すFailureはコードそのものを運ぶ値でしかなく、Nameを解決したり登録したりする経路は無い。expect行はコードでもNameでも書け、両方書いても片方が余らない(Violation.Nameが付いているときだけ、そのNameも満たされたキーに数える)。
理由。「正は1つ、複製は写しでしかない」という他の裁定(型のPG名↔Goの対応、enumラベルのFactなど)と同じ形に揃えた。ランタイムにNameからコードへ解決させる方式(登録テーブルをどこかに持つ)は、ランタイムがスキーマに依存する新しい経路を作ってしまい、「ランタイムはschema.sqlを読まない」という既存の不変を壊す。Go側にNameとコードを両方持つ独自の宣言方式(sqlshape.NamedError{Name, Code}のような値をvetでなく実行時にも参照する形)も検討したが、Failureはただの~stringのままにしてViolates[K ~string]の型引数で受けるほうが、コードの読み書き・比較・switchが素朴な文字列のまま扱えて、ランタイム側に一切の分岐が要らない。この裁定はMySQLのSIGNALキーにも及ぶ——先の裁定(下記MySQLトリガの項)でNameをキーの別名にしないと決めたのは「複数のSIGNALが同じMYSQL_ERRNOを別の意味で使いうる」ことを懸念してのものだったが、Nameをキーの別名にする経路自体を作らず、Goのsqlshape.Error(code)がコードだけを運ぶ値である以上、その懸念は生じない(Violates(err, OrderTooLarge)は結局Violates(err, "30001")と同じ呼び出しでしかない)。
決めたこと。Oneと宣言した文は、すべてのFROM項目の一意キーが等値で固定されているか(JOIN・ビュー・サブクエリ・CTEを通して追跡)、または集約・LIMIT 1・単一行INSERTかを、展開ごとに証明する。証明できなければエラー。実行時に2行目が来たらErrManyRows。
理由。「1件返るはず」という解釈をDBの制約で裏付ける。証明できないOneはスキーマ側に一意制約が足りていないことの発見になる。
決めたこと。sqldefは使わず自前で持つ。比較は両側とも「PGを通した正準形」(DBはpg_dump、schema.sqlは埋め込みPGに載せてpg_dump)。diffはDDLを出すだけ、applyはDDLファイルを入力に取り、終点比較(現DB + DDLをembedded PGで再現しschema.sqlと一致するか)で確認してから1トランザクションで実行する。diffだけでは決められないこと(rename、enumラベルの削除先、backfill)は-- @migrate行で宣言し、宣言と差分の不整合はどちら向きもエラー。
理由。schema層がDDL全般のオブジェクトモデルを持ち、embedded PGで生成DDLを機械検証できるので、外部ツールの出力を検査する層より自前で出す方が短い。両側正準形にするのは、直接ロードとdumpで式の綴りが違うため('x'と'x'::text)。diffとapplyを分けるのは、間に人の手編集(順序・分割・USING・backfill差し込み)が入る前提だから。終点比較なら手編集の中身を問わない。
受け入れた冗長と限界。列順の差は許容して注記する(PGは列を途中に挿せないので、弾くとapplyが二度と通らなくなる)。renameした列を含む制約・FKはDROP + ADDで出る(正しいが再検証が走る。痛くなったらprops比較にrename写像を当てる)。domainの基底型・rangeのサブタイプ・INHERITS・OF typeの変更は注記のみ。行を持つ表のパーティションキーの変更と、列に使われている複合型の属性の型変更は、無損失のDDLが無いので問題として止める(注記だとapplyは通り、verify-schemaが永久に差分を報告する)。pg_dumpは利用者環境のもの(embedded PGにクライアントツールは同梱されない。pg_catalog直読みは必要になったら)。
棄てた案。sqldefのラップ。pg_catalog直読みによる逆ロード(pg_dumpの方が正準形が得やすい)。
スコープは運用まで(裁定2026-09-16)。パーティションの一覧はスキーマの一部なので、列と同じ資格で比較・計画・検証する。Skeemaのpartitioning=keepのように「時系列RANGEのローテーションは運用だから差分を見ない」と切ると、verify-schemaの立場からは検出できないドリフトを設計で作ることになる。こちらの答えは、行を落とすDROP PARTITIONは列のDROPと同じく宣言を要求し、行を動かす変更(MySQLのREORGANIZE、PGのDETACH + ATTACH)はDDLとして導き、無損失のDDLが無い差分は問題で止める。無視はしない。この先にあるのは、後から表をパーティション化する手順(PGはDEFAULTパーティションにATTACHしてから範囲ごとに行を移す)と、ローテーションの規則そのものを宣言してパーティション集合を導くこと。
検査器と同じく本物のサーバをオラクルにするが、問う内容が違う。検査器は「この文をサーバはどう判定するか」を聞き、計画器は「この DDL をサーバは受け入れ、着いた先が目的のスキーマか」を聞く。check/{postgres,mysql}/migrateのTestMigrateProbeが、計画器の語彙からスキーマAを乱数で生成し、変異を1〜5個重ねてBを作り(変異は自分の-- @migrate宣言も書く)、Plan(A→B)のDDLを3行ずつ入ったAを持つ実サーバに流す。合格は三つ: 拒まれない、読み返した正準形がBと一致する(PGは列順を除く)、そこから再Planが空。落ちた組は変異を削って最小化し、直した穴はprobe_findings_test.goに最小の組で固定する。
網羅の単位。検査器のコーパスはサーバ自身の回帰テストで、網羅は所与だった。乱数生成には網羅の単位が無いので、計画器の入力に置く。計画器の入力はdiffの出力だから、diffが出し得る変更の全種((Op, Kind, Field)の三つ組。+ table、~ column type、~ constraint deferrable…)をアルファベットと呼び、diff.Alphabet()がCompareと同じProps関数から機械的に列挙する(キーを写して二重に持たない。無条件に増えたキーは自動で拾い、新しい条件の下のキーは代表スキーマの拡張が要る)。ゲートはseed 1の200組で、踏んだ集合と理由付きの既知未到達の和がアルファベット全体に一致すること。既知未到達に置けるのは「計画器がDDLを書かず問題として止める差分」と「構造的に現れない三つ組」だけで、生成器の怠けは置けない。diffにプロパティが増えると生成器が追従するまでゲートが落ちる。組み合わせと順序は乱数に任せる、という分担。乱数だけだと「seed 1の200組がたまたま全変異を引く」ことに網羅が依存し、変異を1つ足すとPRNGの列がずれて既存の網羅が落ちる(3巡目で実際に起きた)ので、各変異を単独で適用した組を毎回1つずつ作るdirected passを足し、乱数の組との和で集計する。PostgreSQLはprobeを17と18の両方で回す(TestMigrateProbe18。18専用の語彙——VIRTUAL生成列、NOT ENFORCED、WITHOUT OVERLAPS、PERIOD——は18のゲートで踏む)。
数字(2026-09-16、5巡目)。PostgreSQLはアルファベット103のうち17のゲートで94、18のゲートで98を踏む。未到達は、無損失のDDLが無く問題で止める差分4(INHERITS、OF type、domainの基底型、rangeのサブタイプ。以前は注記だったが、注記だとapplyが通りverify-schemaが永久に差分を出すので問題に変えた)、構造的に現れないもの1(pg_dumpは名前付きUNIQUEを常に制約で出すので~ index uniqueは無い)、17のゲートではさらにPG 17が構文を拒む18の語彙4。MySQLは48を全部踏む(パーティションはRANGE / LIST / COLUMNS / HASH / KEY / LINEAR / サブパーティションまで構造にし、Textのフォールバックは無くした)。行を持つ表のパーティションキーの変更は、旧表をRENAMEして目標の形を新しく作り、宣言されたパーティションを付け、INSERT ... SELECTでPGのrouterに全行を配らせ、旧表を落とす手順で書く(空→X、X→空、X→Yとも。コメント・トリガ・ポリシー・RULE・被参照FK・sequenceを付け直す。bigserialのsequenceはOWNED BY NONEで退避して新表に再所有、identityは旧sequenceを退避改名しOVERRIDING SYSTEM VALUEで入れてsetvalで続きから)。固定した計画器の穴はprobe_findings_test.goのPG 35本、MySQL 21本。ほぼ全部がDDLの順序(FKが乗るキー、生成列の依存、PK不在の窓、スキーマの作成と削除、ポリシーとRULEが読む列の型変更)で、依存グラフへの作り替えはせず種類別の固定順の穴埋めで収束している。
届かないもの。生成器のモデル外にある実世界のスキーマの形(レガシーな綴り、拡張型、巨大な表)と、データ依存の失敗(backfillの値、ロック時間)。前者は利用者のschema.sqlが持ち込むもので、applyの終点比較が最後の網。パーティションは語彙に無く、次の巡で足す。
棄てた案。実世界コーパス(regressのCREATE TABLE群をAにする)はdumpの往復に乗らないオブジェクトが多く、変異の網羅にもならない。計画器の行カバレッジをゲートにするのは、未到達行が語彙の穴か死んだ分岐か区別できず宣言の単位として粗い(補助の数字としてなら可)。
決めたこと。CREATE POLICYの条件式を型検査し、ポリシーとENABLE / FORCEの設定をdiff / applyで運ぶ。-require-columnsはポリシーが列を固定していれば満たしたとみなす。ポリシーのUSING式からvisible where相当の条件を導出して文に要求することはしない。
理由。RLSはデータベースが絞る仕組みで、文に同じ条件を繰り返させるのは誤り。
未対応。ポリシーのUSINGをnullabilityやOneの証明に使うこと。PL/pgSQL関数のSECURITY DEFINER到達(本体の解析待ち)。
決めたこと。LANGUAGE plpgsqlの関数本体をlibpg_queryのPL/pgSQLパーサで構造に分け、埋め込まれた各SQL断片を既存のアナライザーで検査する(check/postgres/analyze/plpgsql.go)。PL変数は関数パラメータと同じ経路(funcParam)でスコープに入れ、plVar印で$nから外し、変数と列の衝突はPostgreSQLの既定(variable_conflict = error)どおりエラーにする。record変数の形はそれを埋めたクエリから取り、トリガー関数はCREATE TRIGGERの結びつきごとにNEW / OLDをそのテーブルの行型として解析する(結びつきの無いトリガー関数は解析しない)。RAISEのSQLSTATEは本体から拾い、-- sqlshape: error注釈は名前を付ける役に退く。EXECUTEは定数文字列だけ検査し、それ以外は-strictの助言。
理由。DB側にロジックを置く方針なのに、トリガー関数と書き込み関数の大半を占めるPL/pgSQLが読めないと、関数経由の失敗モード・消費者索引・SECURITY DEFINERの到達がすべて本体の手前で止まり、READMEの主張が成り立たない。パーサが本体を構造化してくれるので、足したのはPL側の層だけで済んだ。
対象外。動的SQL(EXECUTEの非定数)、カーソル経由で取り出した行の型(FETCH INTOの先は形が不明なrecordとして扱い、フィールド参照は型不明で通す)。
決めたこと。visible where・-require-columns・-no-table-reads / -no-tablesは、表(ビュー)が参照側の文に課す義務の実例として一つの仕組みに載せる。宣言はschema.sqlの-- sqlshape: require <body> [on <kinds>](bodyはSQLのboolean式、pinned(列)、immutable(列)、via view)。アナライザーは判定せず、文が証明できること(葉・正規化述語・等値の閉包・代入集合)をx/factsのデータとして出し、internal/obligationが「事実 ⇒ 義務」を判定して履行経路(文自身 / ビュー / ポリシー / 複合FK / waive)ごと返す。aggregateは義務の束を生む宣言、contextは文脈ごとの差分、sqlshape checkはGoの外の文への同じ判定の入口。従来の構文とフラグは略記として残す。経緯・設計・ロードマップはobligations.md。
理由。規則を一つずつ実装すると「ポリシーが満たす」「ビューが運ぶ」のような特例が規則の数だけ増える。判定を一本にすると新しい規則は宣言で済み、方言を足すときも「Factsを出すアナライザー」と「述語を落とすLowerer」だけで判定を共有できる。核(アナライザー・スキーマ・vet)はobligationを知らない。
棄てた案。文をまたぐ規則(トランザクション内の対)を扱う層(分析の単位は文、という核の裁定と衝突する)。方言をまたぐ義務DSL(SQL式と少数の構造述語で足りる)。opt-outの命名規則によるパッケージ→文脈の写像(暗黙は読めない。パッケージコメントの// sqlshape: contextとフラグで明示する)。
事実の正しさは実サーバで測る(2026-09-16)。x/stmtprobeがスキーマと行と文を生成し、両方言のアナライザーが出したFactsの主張——述語が返る全行で成り立つ、列が既知の値に固定されている、高々1行、書き込みが格納する値——をサーバの返した行で反証する(検査器の型をembedded PGで、マイグレーションの計画を正準形一致で測るのと同じ位置づけ。マイグレーションのprobeと同じく生成器・判定器・報告を方言中立に一つ書き、ドライバだけ方言ごと)。初回で両方言に1件ずつ見つかった(MySQLの1093 / 1443、PGのJOIN ON内サブクエリの外部参照)。同じ生成器で失敗モードも測る: 全種類の制約を持つスキーマへの書き込みを走らせ、サーバが出した制約エラーは予測した違反のどれかにランタイムのViolatesで一致しなければならない(PGが「毎回失敗する」noteで言う確定失敗も予測に数える)。MySQLの本体はサーバのCREATE時判定と(check/mysql/internal/analyzeのbody probe)、文の型とエラーはmysql-testコーパス1,281ファイルの並走と(同corpus probe、PGのregress probeの対)で測る。コーパスは初回44,342文一致・4,605不一致をベースラインとして固定し、以後の巡で削る(PGは5,282から47まで削った)。
決めたこと。schema.sqlは-- sqlshape: postgres 18と1行で、どの版のPostgreSQL向けかを宣言する。宣言は必須で、無いファイルは読まない。この1行が、スキーマと全部の文を読む文法、型・関数・演算子を解決するカタログ、pgtestとマイグレーション系コマンドが起動するPostgreSQLの版を決める。パーサはlibpg_queryを版ごとにWebAssemblyへビルドして埋め込み、wazeroで実行する(check/postgres/pgparse)。カタログは版ごとにその版の埋め込みPostgreSQLからdumpしたTSV(check/postgres/catalog/data/<major>/)、オラクルとregressコーパスも版ごと。ノードのGo型は最新版のpg_query.protoから生成した1組だけを持ち、どの版の木もパーサのJSON出力をprotojsonで読む。古い版で名前が違うフィールドは読む前にJSON上で最新版の形に書き換える(pgparse/upgrade.go。17→18はreturningList→returningClause.exprs、is_enforced=true、generated_kind="s"と、生の木には現れない3フィールドの削除)。版で判定が変わる規則はアナライザー内の版分岐(RETURNING old/new、セッションTZの略称、数値フィールドの厳格化、aclitemの引用符、JSON_VALUEの照合衝突、jsonpath引数の型、CTE越しの外側集約)。diff / apply / verify-schemaは接続先のserver_versionが宣言と違うメジャー版なら警告して続行する。
理由。宣言版より新しい構文をその版の本物の文法が拒否するので、gram.yの差分表を持たずに済む。cgoが消えてgo installにCツールチェーンが要らず、1つのランナーで全プラットフォームをクロスコンパイルできる。wasmモジュールは隔離されるので版ごとのパーサを同じバイナリに複数積める。JSON経路を選んだのは、protobufのフィールド番号をlibpg_queryが版ごとに振り直すためで(17→18で267フィールド、enum値434が変わった)、JSON経路のほうがprotobuf経路より速くもあった(1文215µs対273µs)。書き換え漏れはprotojsonが未知フィールドとして拒否するので黙って消えない。
棄てた案。① pg_query_goをforkしてcgoのまま版を積む(版ごとに別バイナリになる。pg_query_goのリリースを待つ形も変わらない)。② 版を宣言しないスキーマに最新のサポート版を既定として当てる(当初案。「既定が動いて何が判定されたか分からない」より、1行足してもらう方がよい。既定pgparse.Defaultはコードから組むスキーマ用のAPI上のフォールバックとして残る)。③ 版ごとのGo型を持つ(アナライザーを型で分岐させることになる)。④ 版ごとにprotobufのフィールド番号を変換する(JSONで済む)。
忠実度。regressコーパスをその版の本物と並走させた結果、17は22,103文で既知の不一致35、18は23,384文で47(testdata/regress_baseline_<major>.txt)。18の47は17の既知集合と、RETURNING old/newのnullability 10件(INSERTのold・DELETEのnewはアナライザーがnullable、オラクルは列のNOT NULLしか見えない)、DO INSTEADルール付きDELETE RETURNINGの1件(アナライザーはPGと同じ0A000、オラクルのDescribeが空を返す)。pgparseのTestCorpusは17の43,226文が書き換え経由で読め、18のJSON経路がprotobuf経路と全一致することを検問する。
追従。新しいメジャー版は「版を1つ足す」作業で、手順はcheck/postgres/pgparse/README.mdにまとめてある。libpg_queryのリリースを待つ形は変わらない(18は8か月遅れた)。サポート窓はPGの5年に合わせるが、まず17と18の2版でこの構造を作った。メジャー間で判定が変わるのは、構文の追加、カタログの追加・オーバーロードによる曖昧化・稀な削除、予約語の追加、ごく稀な型規則の変更で、regressコーパスの差分がそれを列挙する。
裁定 2026-09-10。sqlshape の約束は「schema.sqlに対してテンプレートの有限展開を静的に検査する」で、それはマーカーsqlshape.Query[R, P](tmpl) / Oneひとつで閉じる。SafeQL が使うクライアントライブラリを問わないのと同じ位置に立つ: 検査対象はマーカーで、ランタイムは「あると便利な 1 実装」。
- ルートモジュール
github.com/kr9ly/sqlshape/v2は依存ゼロの核だけを持つ:Query/One/Stmt/Render(テンプレートの意味論 —{{.X}}のプレースホルダ化と分岐の有限集合)と、依存の無い検査器の共有部(x/expand/dialect/facts/obligation)。利用者の go.mod に pgx も wazero も載らない - ランタイムは DB ごとの別モジュールで、互いに似ていなくてよい。
sqlshape/postgresは pgx の自然な形(iter.Seq2、Batch、Copy、pgtype のスキャナ、MatView、ConstraintError)、sqlshape/mysqlは database/sql の形(?描画、*sql.Rows)。共通シグネチャは作らない。受け型の表はドライバごと - マーカーは設定できる。既定は
sqlshape.Query/One、-query=pkg.Funcで利用者自身の generic 関数F[R, P any](string) Tを登録できる。ランタイムを自作してよい。定数の生 SQL(db.Query(ctx, "SELECT …"))は R / P 無しの薄い検査(構文・名前・パラメータ個数) - 失うものは明示する:
-raw-sql=forbidの「検査済み SQL しか実行されない」、expect行とConstraintErrorの対応、Oneの実行時ErrManyRowsはランタイム側の契約で、sqlshape のランタイムを使ったときだけ成立する。docs は「静的に約束すること」と「ランタイムを使えば加わること」を分けて書く - 検査器も DB ごとのモジュール:
sqlshape/check/postgres(Apache。analyze / schema / catalog / pgparse / oracle / verify / dump / diff / migrate。パッケージは公開だがツール向けで互換性の約束はしない)とsqlshape/check/mysql(GPLv2、旧mysql/)。sqlshape/pgtestは check/postgres の上。sqlshape/cmd/sqlshape(GPLv2)が vet と cli を内包して全部を積む。7 モジュールを 1 つの版番号でロックステップ、2.0.0 から - DB × 言語の行列: Go の各 DB が
sqlshape/<db>、TypeScript は別リポジトリの@sqlshape/<db>、check/<db>は言語非依存で共有、言語フロントエンド(vet)はcmd/側 - 退けた案: ルートに PG ランタイムを残して MySQL だけ別モジュール(依存の混入が残る)、ランタイム間で
Run(ctx, db, stmt, p)の関数形を揃える(揃える理由が無い)
裁定 2026-09-11。pgtest.Verifyが確かめるのは「検査器の判定がサーバと一致するか」で、これはsqlshapeの正しさの検証であってアプリケーションのテストではない。ユーザーのスキーマ固有の文で不一致が出てもそれはsqlshapeのバグで、報告してもらうもの。ユーザーのテストに自己検証を持ち込ませるのは「静的解析は信用できないかもしれない」と言うのと同じで、製品として弱い。サーバを起こす便宜(Start)も、本物のDBでテストしたいユーザーは自分の環境(testcontainers等)を既に持っていて、sqlshapeが口を出す理由が無い。そこでpgtestとmysqltestはユーザー向けAPIから外し、check/*と同じ「ツール向け、互換性の約束なし」の位置に置く。モジュールは残す(oracle、examples、敵対的テスト、regressの照合が使う)。ユーザー向けdocs(README、runtime、postgres.md / mysql.md)からテスト用サーバの節を消し、互換性の約束の文からも外した。sqlshape自身の正しさはregress 22,103文、oracleの5,033文、敵対的テストの照合で保証し、ユーザーにはその数字を見せる。退けた案: Verifyを任意の接続に対して使える形にしてユーザーに勧める(検証の主語が逆)、mysqltestにVerifyを足す(oracleがGPL側にあるのでApacheのmysqltestからは呼べず、構図も成立しない)
FETCH(カーソルの列は静的に決まらない)。EXPLAINの実行(embedded PGの統計は本番と違う。性能の助言は構造的に判定できるもの、インデックスの先頭列とビューへの述語押し込みに限る)。初期リリースではPostgreSQL以外のRDBMS(下記「検討中」のMySQL参照)。
層の規則(x/boundary_test.go が import グラフで検査する、負債リストは空): x/* は stdlib と x/* しか import しない(契約と共有部)。言語フロントエンド cmd/sqlshape/internal/vet は x/* と自分の internal だけ — 方言は x/dialect.Register で名乗り、cmd/sqlshape/main.go の blank import が積む。方言アダプタ check/<db>/dialect は自分の check/<db>/* と x/* だけで、dialect.Analyzer(文の解析)に加えて Schemaed(関係・定義・助言・型・出所)と Contracted(義務の contract と lowering)を実装する。
| package | 役割 |
|---|---|
sqlshape |
宣言の核(依存ゼロ): Query[R, P] / One[R, P] / Stmt / Render、行の束縛規則(Fields)、Labelled |
postgres |
pgx 上のランタイム(別モジュール): Run / Collect / First / Exec / Get / Find、Batch / Copy[R] / MatView、行マッパー、型登録、ConstraintError、描画のバイト比較) |
mysql |
database/sql 上の MySQL ランタイム(別モジュール、go-sql-driver/mysql の受け型): Run / Collect / First / Exec / Get / Find / ExecOne、$n → ? の並べ替え(x/placeholder)、ConstraintError(1062 / 1452 / 1048 / 3819 をスキーマの名前に) |
mysqltest |
PATH の mysqld を schema.sql を載せて起こす(アプリケーションのテスト用、pgtest の MySQL 版)。check/mysql の oracle もこの上 |
x/placeholder |
$n → ? の書き換えと位置の逆写像。MySQL のランタイムとアナライザーが共有 |
pgtest |
schema.sqlを適用した本物のPGをアプリケーションのテストに提供する。VerifyがアナライザーとPGを突き合わせる |
x/expand |
テンプレートの全展開。{{.X}} → $nとP上のパス |
check/postgres/pgparse |
パーサ。libpg_queryを版ごとにWebAssemblyへビルドして埋め込み、wazeroで実行する。Version.Parse / Deparse / SplitWithScanner / ParsePlPgSqlToJSONと、最新版のprotoから生成したノード型 |
check/postgres/schema |
libpg_queryでschema.sqlをカタログの上に載せる。テーブル・ビュー・enum・ドメイン・複合型・関数・制約・ポリシー・seed |
check/postgres/catalog |
埋め込みのpg_catalog(版ごとの型・関数・演算子・キャスト・集約、data/<major>/)と拡張のdump |
check/postgres/analyze |
アナライザー本体。10章の型変換、スコープ、DML、$n推論、nullability、カーディナリティ、違反の列挙、PG互換のエラー。文の事実(facts.Facts)の生産と、義務の述語を事実の言語に落とすLower |
x/facts |
アナライザーと義務検査の間のデータ契約。文種・スコープの木・葉・正規化述語・等値の辺・固定列・代入集合。パーサのノードを含まず、方言を知らない |
x/cardinality |
One の証明を facts の上で(方言非依存、PostgreSQL も MySQL もこれだけ): 全 leaf のユニークキー(部分インデックスは述語を文が繰り返すとき、WITHOUT OVERLAPS は範囲が既知の点を含むとき)が等式で固定される、join の辺で知識を運ぶ、派生表・ビュー・CTE は外側で固定された出力列を種にして本体の scope で、GROUP BY は全項が固定されるとき、LIMIT 1 / 1 行 VALUES / 集約は Single、集合演算 / 複数行 VALUES / FULL JOIN は Many、producer の AtMostOne はそのまま |
x/obligation |
境界の規則(方言非依存)。obligation.Schema / Relation interface 越しにスキーマを見る(PG は schema.Schema.Contract() が適合)。schema.sqlのrequire / visible whereとvetのフラグを義務に読み、事実に対して履行を判定する(obligations.md)。analyzeにもvetにも依存しない |
cmd/sqlshape/internal/vet |
go/analysisアナライザー。x/dialect の契約だけを読む(PG 固有型なし)。結果列 ↔ R、$n ↔ P、束縛、expect行、SuggestedFix。境界の規則はobligationに委ね、フラグを義務に展開して渡す |
check/postgres/oracle |
差分テストのオラクルとしての本物のPG(embedded-postgres)。検査時には使わない |
check/postgres/dump / diff / migrate / consumers / cli |
マイグレーション側。pg_dumpによる正準形、オブジェクト単位のdiff、DDL生成と終点検証、消費者索引、サブコマンド |
- MySQLを、PostgreSQLとは別の実装としてサポートする。初期リリースの範囲外。方言をまたぐ共通DSLは作らない(作った瞬間にSQLをDSLに翻訳させる形に戻る)。代わりにプラットフォームごとに、そのDBの構文と型規則を実装したアナライザーと、そのDBのdumpを使うマイグレーション支援を持つ。共有するのはテンプレートの展開、
go/analysisのフロントエンド、Go側の型照合の枠組み- ライセンスと構成(裁定 2026-09-09、改訂): MySQLサーバはGPLv2で、Apache 2.0のsqlshapeと同じ成果物には混ぜられない(libpg_queryの形が成立したのはPostgreSQL Licenseが寛容だったから)。守るのは「利用者のランタイムにGPLが混入しない」の1点で、優先するのは利用者の使いやすさ。MySQLとPostgreSQLで別のバイナリを使い分けさせることはしない。そこでモノレポの中でモジュールを2種に分ける。① Apache 2.0のまま残るもの: 利用者のコードにリンクされる
sqlshape(ランタイム)とpgtest、pgtestが使うPostgreSQL側の解析(check/postgres/analyze/schema/catalog/pgparse/oracle/verify)、テンプレート展開、義務、vetのフロントエンド。import pathはgithub.com/kr9ly/sqlshape/v2のまま動かさない。② GPLv2に置くもの: MySQLの文法・字句解析器・関数表を切り出したwasmとそのアナライザー(github.com/kr9ly/sqlshape/check/mysql/v2、ネストしたモジュール)、そして両方を積む1つのバイナリcmd/sqlshape(ネストしたモジュール、GPLv2。Apache→GPLの一方向importは互換)。バイナリはschema.sqlの宣言(-- sqlshape: postgres 18/-- sqlshape: mysql 8.4)で方言を選び、vetとしてもマイグレーションとしても同じ1つで済む。利用者のアプリにリンクされるのは①だけなので、GPLは開発ツールに閉じる(gccと同じ)。internal/の参照はパスの接頭辞で判定されるのでネストしたモジュールからも通る見込みだが、これとネストしたモジュールのタグ付け(cmd/sqlshape/vX.Y.Z)とgo installの解決はスパイクで確認する。退けた案: MySQL対応を別リポジトリ・別バイナリsqlshape-mysqlにする(当初の裁定。利用者にDBごとのバイナリを使い分けさせることになる)、パーサを別プロセスにしてパイプで木を渡す(FSFは密なデータ交換を結合とみなし得るとしていて灰色、構造も歪む)、Apache 2.0の互換パーサ(TiDB parser / Vitess)を使う(原則を捨てる)、抽出を事実に限定して文法を手書きする(一番品質が欲しい文法が手書きになる)- バージョン(裁定 2026-09-10): 3 モジュールは 1 つの版番号でロックステップ、全部 1.x(
cmd/sqlshapeの/v2は外した。MySQL 追加は additive なので minor が semver 上も正しく、ランタイムの import path も動かさない)。同一コミットにvX.Y.Z/mysql/vX.Y.Z/cmd/sqlshape/vX.Y.Zを打ち、scripts/release.shが go.mod の相互 require を揃えてコミット・タグ付けする。release.yml はルートのv*で発火。退けた案: モジュールごとに独立した番号(root 1.x / mysql 0.x / cmd 2.x、多段の手順が要る)、root も/v2に上げて 2.x で揃える(ランタイム利用者の import path が変わる)
- バージョン(裁定 2026-09-10): 3 モジュールは 1 つの版番号でロックステップ、全部 1.x(
- パーサと字句解析器(裁定 2026-09-09): MySQLサーバのソースから機械的に切り出し、libpg_queryと同じ形でwasmにする。原則は「本物から機械的に抽出したものを土台にし、手で書く部分を最小にする」。文法は
sql/sql_yacc.yy(bison、18k行、%expect 59)からC++のアクション(NEW_PTNが923箇所)を剥がして規則・優先順位・トークンだけを残し、規則名と子要素だけの素の構文木(CST)を組む汎用アクションを機械生成してbisonに通す。字句解析器はsql/sql_lex.ccのlex_one_token(726行)と2トークン先読みのMYSQLlex(WITH ROLLUP等の合成)、Lex_input_stream(440行)、find_keyword(sql/lex.hの784語の表からgen_lex_hashが生成する完全ハッシュ)、consume_comment・int_tokenをそのまま使う。測ったところ、字句解析器がサーバ状態を読むのは5点だけ —sql_mode(ANSI_QUOTESの1箇所)、default_collation_for_utf8mb4、接続文字集合、コメント収集のm_parser_state、非推奨文字集合のpush_warning(2箇所)— なのでTHDはこの5点を持つ数十行のshimで置き換える。文字の分類(state_map/ident_map)はstrings/sql_chars.ccが文字集合のctype表から作るもので、strings/ライブラリごと取り込む(PGのsrc/portをlibpg_queryが抱えるのと同じ)。バージョンコメント/*!80000 ... */はMYSQL_VERSION_IDとの比較なので、版ごとにビルドすれば自然に正しい。sqlshape用のASTへの変換だけが手書きで、CSTの規則名を読む。生成手段はこの裁定でbison + emccに決まる(goyaccでpure Goに持つ案は字句解析器の書き直しを伴うので原則に反する)。残る確認はスパイク: shimの表面積が本当に5点で閉じるか、抽出した文法とlexerがemccで通るか、mysql-test/t(1810ファイル)の受理率- スパイクの結果(2026-09-09、
mysql/spike/): 三点とも成立。shimの表面積は5点で閉じた(警告・digest・utf8本文・オプティマイザヒントは空実装)。アクションを剥がした文法はbison 3.8で%expect 59のまま通り、トークン番号は本物と一致する。mysql-test/tの1,455ファイルを文に割った137,062文のうち、エラーを期待しない125,187文の99.89%を受理し、残りはテストハーネス側の事情(delimiter、クライアント文字集合の切り替え、パーサ深さの試験)で文法の穴は見つかっていない。MySQLがアクション内で出す構文エラー(予約関数名のテーブル名、<=>ALL)はCSTパーサでは通るので、意味層で拾う - CST→AST(裁定 2026-09-09): 剥がしたアクションの中身が CST→AST の対応表なので、parsegenがそれを読み戻して
shapes.go(規則×選択肢 → server が何を組んだか)を生成し、mysqlastが汎用に再生する。ノードは server の PT クラス(PT_query_specification/PTI_where/Item_func_eq)で、引数名はヘッダのコンストラクタから、by-value の struct のフィールド名はparser_yystype.hから取る。読めないアクション(到達範囲で約 45)は hook を手書きし、hook は規則名と右辺の記号列で結び、版が上がってずれれば init で落ちる。読めもせず hook も無い構文はUnsupportedとして明示する。mysql-test の DML/DDL の 97.7% が組める - アナライザーが読む木(裁定 2026-09-09): mysqlast を直接読む(PG 側が pg_query のノードを直接読むのと同じ位置づけ)。parsegen が持つコンストラクタ引数名から PT クラスごとの型付きビュー(
AsPTQuerySpecification(v)と引数名のアクセサ)を生成して、アナライザーはそれを通す。MySQL 専用の正規化した文モデルは作らない。版ごとの揺れは hook と引数名の照合で露見させ、吸収層が要るかは SELECT の解析を書いてから判断する
- スパイクの結果(2026-09-09、
- ライセンスと構成(裁定 2026-09-09、改訂): MySQLサーバはGPLv2で、Apache 2.0のsqlshapeと同じ成果物には混ぜられない(libpg_queryの形が成立したのはPostgreSQL Licenseが寛容だったから)。守るのは「利用者のランタイムにGPLが混入しない」の1点で、優先するのは利用者の使いやすさ。MySQLとPostgreSQLで別のバイナリを使い分けさせることはしない。そこでモノレポの中でモジュールを2種に分ける。① Apache 2.0のまま残るもの: 利用者のコードにリンクされる
- 方言の口(裁定 2026-09-09): vet が
analyze.Result/schema.Schema/pgparseに直接依存しているので、ルートにx/dialectを切る。Load(schemaSQL) (Analyzer, error)、Analyzer.Analyze(sql) (*Result, error)、Go 型 ↔ SQL 型の対応表を方言が提供し、schema.sqlの先頭宣言(-- sqlshape: postgres 18/-- sqlshape: mysql 8.4)で選ぶ。Resultは方言非依存の形(型は名前と NULL 可否、出所はテーブル・列名、facts.Facts)に寄せる。PG 実装はcheck/postgres/analyzeの薄い adapter、MySQL 実装はmysql/側。vet が pgparse に触る 2 箇所(ORDER BY の hazard、束縛の定数)は方言側へ。SQLite 等の第三の方言もこの口に足すだけで済む形にする(パーサは同じ手法 — 本物の文法からの機械抽出 — で、Lemon の文法なら parsegen に相当する生成器をもう 1 つ書く)- 方言間の線引き(裁定 2026-09-10): 機能は方言の事実として現れるだけで、共通化しない。契約(
Oneの証明・義務・失敗モード)は事実(facts.Facts: どの列を読む・固定する・書く、どのキーで一意になる、どの制約に当たり得るか)の上に書く。契約が必要とする事実をその方言が生産できないなら、その契約はその方言ではエラーにする(黙って通さない)。これで「PG にある機能を MySQL でどう真似るか」は問いとして消え、「この契約が要る事実は何か、その方言はそれを出せるか」に置き換わる。3 層で見る: ① SQL の意味論(文法・型・エラー・名前解決)は各 server がそのまま正で、oracle で検算する ② sqlshape の契約は事実の上 ③ Go の受け型と実行時はドライバごとの表。含意:dialect.Resultに Facts を載せて obligation を方言非依存にするのが次の設計課題。方言にだけある機能と契約の交差(INSERT IGNOREは失敗モードを飲み込む、ON DUPLICATE KEY UPDATEはON CONFLICT相当、RETURNINGが無いので「書いた値を読む」規則が成立しない)は個別に裁定する。ドキュメント: 何を約束し何を約束しないかが方言ごとに変わるので、利用者向け docs は方言別の約束の表として整理し直す。実装より難しいと見ていて、契約の結線を MySQL に通すタイミングで再度整理する - 実施(2026-09-09、縦串):
x/dialectは宣言の読み取り(Declared、-- sqlshape: <name> <version>で name が postgres か登録済みの方言のもの)・Register/Lookupのレジストリ・方言非依存のAnalyzer { Analyze(sql) (*Result, error); Problems() }とResult { Params []Type; Columns []Column }(Typeは方言の綴りと Go 型名の列、Columnは名前・型・NULL 可否)だけ。vet は宣言が postgres 以外のときdialect.goの細い経路(展開 → Analyze → 解析エラー / 結果列 ↔ R / パラメータ ↔ P)を通り、PG 経路は無変更で残す。PG をResultに寄せる作業は、Resultが義務・違反・基数・束縛を運べるようになってから。プレースホルダは展開器の$nを方言側が翻訳する(MySQL は?。$は MySQL の識別子に使えるので、引用符・識別子の中は触らない)。MySQL 実装はmysql/check/postgres/analyze(Analyze(schema, sql)、独自のResult)と公開パッケージmysql/dialect(登録と Go 型表)、cmd/sqlshapeが blank import する - 文字集合レジストリ(裁定 2026-09-09):
strings/の照合ライブラリを丸ごとリンクする(ctype-.cc、collations.cc、uca9dumpが生成するzh/jaの重み表)。wasmは4.6MBで、名前だけの表なら0.9MBだが、手で持つ表をゼロにすることと、型層でPAD SPACE・mbmaxlen・既定照合を参照するときにレジストリがそのまま答えになることを優先した。サイズが問題になったら重み表(uca900_data.hとhan表、約3MB)だけを空にする - サーバ設定の宣言(裁定 2026-09-11、実施同日): 判定を変えるサーバ変数は、版と同じくschema.sqlが宣言する。構文は方言非依存で
-- sqlshape: server <var> = <value>(1行1変数、値はSQLの文字列リテラルか裸のトークン、x/dialect.Settingsが読む)、受け付ける変数の列挙は方言ごと(知らない変数・不正な値はスキーマのProblem)。MySQLが読むのはsql_modeとlower_case_table_namesの2つで、宣言が無ければ「8.4を初期化したままのサーバ」(sql_modeの既定、lower_case_table_names=0)を規定とする。sql_modeの語彙・ビット・組み合わせモード(ANSI/TRADITIONAL)の展開はx/sqlmode(sys_vars.ccのsql_mode_names/expand_sql_modeの写し。ルートに置くのは、GPLの検査器とApacheのランタイム / mysqltestの両方が同じ表を読むため —x/placeholderと同じ位置づけ)。検査器が従うのは、字句・文法のビット(ANSI_QUOTES/PIPES_AS_CONCAT/IGNORE_SPACE/NO_BACKSLASH_ESCAPES/HIGH_NOT_PRECEDENCE、shimのTHDにそのまま渡す —||は字句解析器がOR_OR_SYM/OR2_SYMを選ぶので変換層の分岐は不要だった)、ONLY_FULL_GROUP_BY(グループ検査の有無)、STRICT_TRANS_TABLES/STRICT_ALL_TABLES(Item_str_funcのNULL可否、1048の失敗モード)、REAL_AS_FLOAT(DDLのREAL)、NO_UNSIGNED_SUBTRACTION(減算のunsigned)。残りの語(日付・0除算・エンジン置換・パディング)は実行時にしか効かないので受理して素通し。lower_case_table_namesは1なら表名・ビュー名を小文字に正規化して保持(サーバの報告と同じ)、2なら宣言どおりの綴りで大文字小文字を無視して照合、0は区別する。サーバとの突き合わせ:mysqltest.Startが宣言をそのままmysqldの起動オプションに渡す(lower_case_table_namesは初期化後に変えられないのでテンプレートを値ごとに分ける。知らない変数はmysqldが起動を拒む)ので、オラクルもアプリのテストも宣言と同じ世界で走る。本番の接続に対してはmysql.Verify(ctx, db, schemaSQL)が@@SESSION.sql_mode(DSN / プールで上書きされうるのでSESSION)と@@lower_case_table_namesを読み、宣言とビットで比べて不一致を返す。退けた案:SET文をschema.sqlに書かせる(DDLに混ざり、適用対象になる)、-- sqlshape: mysql 8.4 sql_mode=...と版の行に載せる(変数が増えると読めない)、mysqltestに宣言の正規表現を複製する(表が二重になる) - マイグレーション(裁定 2026-09-11、実施中): PG と同じ 3 部構成を
check/mysql/dump/diff/migrateに置き、sqlshape diff/apply/verify-schemaは schema.sql の宣言で方言を選ぶ(cli を方言ごとの driver に切る)。正準形は「その文を適用したサーバにSHOW CREATE TABLE/SHOW CREATE VIEWで読み返した DDL」を自前のローダー(check/mysql/internal/schema)で読んだモデル。両側(目標の schema.sql と稼働 DB)を同じ経路で読むので、比較されるのは書き方でなく MySQL が保持している定義になる(PG が両側を pg_dump で読むのと同じ位置づけ。mysqldump は要らない。SHOW CREATE TABLEの出力をローダーがそのまま読めることは実測済み: 列 9 / キー 3 / CHECK 2、/*!80016 NOT ENFORCED */も読む)。読み返しで落とすもの:AUTO_INCREMENT=Nのカウンタ、ビューのDEFINER。正準化に使うサーバは、-dbがあるときはその稼働サーバ上の一時データベース(sqlshape_scratch_<乱数>を作って適用し、読み返して落とす。同じサーバ版・同じ設定で正規化されるので、別のローカル mysqld より正しい。CREATE / DROP DATABASE 権限が要る)、-from(テキスト同士)とテストでは PATH の mysqld(mysqltest、宣言した設定で起動)。宣言したsql_modeは一時 DB のセッションにSET SESSIONで入れ、lower_case_table_namesはサーバの値が宣言と違えば止める。差分はモデルの上で、表(エンジン・文字集合・照合・コメント)、列(型の正準綴り・NULL 可否・既定値・AUTO_INCREMENT・ON UPDATE・生成式と STORED・コメント・INVISIBLE・照合・位置)、キー(種別・列と接頭長・コメント)、外部キー(列・参照・ON DELETE / UPDATE)、CHECK(式・ENFORCED)、ビュー(サーバが正規化した本文・ALGORITHM・CHECK OPTION)。列の順序は PG では直せないので注記だったが、MySQL はMODIFY ... AFTERで直せるので差分として出す。トリガ・プロシージャ・イベントはローダーが読まないので比較しない(docs に明記)。seed 表は MySQL のローダーに無いので今回は範囲外。DDL の生成は MySQL 構文: drop(参照している外部キー → ビュー → 表 / 列 / キー / CHECK)、宣言された rename(RENAME TABLE/RENAME COLUMN)、alter(MODIFY COLUMNの全定義 +FIRST/AFTER、表オプション、キーと FK と CHECK は DROP + ADD)、add(正準テキストのCREATE TABLEを FK 依存順に、ビューはその後)、backfill。-- @migrateの文法は PG と同じ(enumは MySQL では列を名指す:enum orders.status: drop 'x' using 'y'→ UPDATE してから MODIFY)。verify は「稼働 DB の正準テキスト + DDL」を一時 DB に適用して読み返し、目標と比べる。apply: MySQL の DDL はトランザクションにならない(暗黙コミット)ので 1 文ずつ実行し、失敗した文で止めてどこまで進んだかを報告する。-no-transactionは MySQL では意味を持たない。退けた案: mysqldump を両側に使う(バイナリ依存が増え、SHOW CREATEと同じ情報しか出ない)、information_schema を直接読んでモデルを組む(ローダーの二重実装になる。正準 DDL を読ませれば一つで済む)、ローカル mysqld を必ず要求する(配布バイナリが無いので PG の embedded とは事情が違う) - トリガとストアドルーチン(裁定 2026-09-11 セッション末、実施): PostgreSQLのPL/pgSQL本体解析と同じ位置づけで必須とし、後回しにしない(docs/checks.mdは「失敗モードはトリガと呼び出す関数の中まで計算する」と約束しており、MySQLだけトリガ本体を読めないままだと
SIGNALの失敗モードが漏れ、本体のDMLが義務の判定を逃れる)。本体はスキーマごとに1回解析してキャッシュし(AnalyzeTrigger/AnalyzeRoutine、BodyResult)、結果をルーチンの呼び出し側・CALL・トリガを起こす文のそれぞれが読む。SIGNALのキーはSET MYSQL_ERRNOがあればその10進表記、無ければSQLSTATE(PostgreSQLのRAISE ... USING ERRCODEと同じ位置づけ。runtime側のmysql/errors.goも同じ規則でサーバのエラーを読み戻す)。-- sqlshape: error <key> = <Name>はPGのerror注釈と同じ構文で足した。当初はNameをキーの別名にしない設計だった(Violation.Key()はConstraintしか見ず、NameはdescribeViolationの説明文の装飾に留める)——理由は、MYSQL_ERRNOは同じ値でも複数のSIGNALが別の意味で使う可能性があり、キーをNameで直接上書きするとmysql.Violatesのランタイム側の照合(サーバのSQLSTATE / 番号から一意に引ける)と食い違う経路が生まれることを懸念したため。この懸念は裁定2026-09-13(上記「トリガ・ルーチンの独自コードにGoの名前を与える」)で解消した: NameはGoのsqlshape.Error(code)宣言の識別子名としてvetが照合するだけで、キーそのものの別名としてランタイムに登録されることは無い(ViolatesはスキーマもNameも知らず、渡された値のコードだけを見る)ので、複数のSIGNALがコードを共有してもNameが誤って解決される経路自体が存在しない。expect行・mysql.ViolatesはNameでも書けるようになったが、それはViolation.Nameが一致するキーの別表記として認められるだけで、キー自体(Violation.Key())は変わらずSIGNALのコードのままである。DECLARE ... HANDLER FORはブロック単位で吸収し(SQLEXCEPTION / SQLWARNING / NOT FOUND / SQLSTATE / 番号 / 条件名)、値なしRESIGNALで戻す設計はPL/pgSQLのEXCEPTIONブロックと同型。CALLの結果列は「本体のINTO無しSELECTが0個なら列無し、1個ならその列、複数あって形が全部一致すれば1つの列リスト、割れていれば検査器自身のエラー」とし、mysqld自身の拒否ではなく検査器の判断にした——mysqldは実行時にどちらの結果集合を返すか経路依存で決めるだけで、CREATE時にもCALL時にも形の一致を検査しないため、静的に扱うには検査器側で裁定するしかなかった。マイグレーションはトリガ・ルーチンをDROP + CREATEで置き換える(MySQLにCREATE OR REPLACE TRIGGERが無いのはテーブル同様の制約で、表・ビューと同じ依存順の裁定に従う: トリガのDROPは表のDROPより前、ルーチンのCREATEはビューより前、トリガのCREATEはbackfillの後)。mysqlparse.Splitの複合文分割(裁定2026-09-09)は変えず、DELIMITER非依存の;拡張方式のままトリガ・ルーチン本体にも通用した——本体を字句的に読むだけの分割なので、意味解析側の変更だけで済んだ - オプティマイザヒント(
/*+ ... */)は別の文法sql/sql_hints.yy(725行)とHint_scannerを持つ。同じ手順で後から足せる。sqlshapeの判定には効かないので初期は読み飛ばす - カタログ(裁定 2026-09-09、測定に基づく): MySQLには
pg_procに当たる表がないが、組み込み関数の定義はソースにまとまっていて機械抽出できる。①関数表sql/item_create.ccのfunc_array(347エントリ): 名前 → Itemクラス × 引数個数(固定 / 最小・最大 / 偶奇)。②キーワード構文の関数(CAST・TRIM・DATE_ADD等、81クラス)はsql_yacc.yyのアクションのNEW_PTN Item_func_*に書かれているので、アクションを剥がす前に「規則 → Itemクラス」として拾う。③結果型の種別はItemクラスの継承から取れる: 登録277クラスの直接の基底はItem_int_func(77、LONGLONG)・Item_str_func(53、文字列)・Item_dec_func/Item_real_func(21、DOUBLE)・Item_json_func(10)・Item_bool_func(8)・日時系(9)・空間系(33)で大半が決まる。④引数型・NULL可・正確な結果型は各クラスのresolve_type(257個)にあり、その多くが宣言的な呼び出し —param_type_is_default(from, to, TYPE)(97箇所、引数の既定型)、set_data_type_string / longlong / double / decimal / datetime / date / time / json、set_nullable(82)、aggregate_type(引数型の合成)— で書かれているので、本体を字句的に読んで表にできる。⑤宣言的でない残り(unsigned_flagの伝播、長さ計算、引数で結果型が変わるもの)と④の検算は、本物のmysqld(配布tarballを--initializeで起こす。embedded-postgresの役)に①②から生成したSELECT f(?, ...)をプリペアドステートメントで問い、結果メタデータで埋める。「何が存在し何個の引数を取るか」を手で列挙しないのが要点で、抽出した表が計測の入力になる。型規則(暗黙変換・数値の昇格・文字列と数値の比較)はItem_func::aggregate_typeとitem_cmpfunc.ccの比較種別決定(get_cmp_type相当)を読んで移し、mysqldとの差分テストで検算する- 型規則の実施(2026-09-10):
mysql/check/postgres/analyze/types.goが server の規則をそのまま持つ —Item_num_op::set_numeric_type(REAL > DECIMAL > INT の昇格、numeric_context_result_typeで日時は整数・文字列は実数扱い、result_precisionの unsigned 伝播)、Item_func_num1(1 引数の数値関数、Item_func_int_valは小数を scale 0 に)、Item::aggregate_type(NULL を飛ばしてfield_type_mergeで畳み、符号が混じる整数は一段広げる)。field_types_merge_rules(30×30)とfield_types_result_typeは手で写さず parsegen がsql/field.ccから抽出して catalog に生成する(catalog.Merge/catalog.ResultKind)。関数は catalog の Item クラスで判定: family が結果種別を決め、facts(set_data_type_*、set_nullable、unsigned_flag=true、param_type_is_default(from,to,TYPE)、param_type_uses_non_param)が型・NULL 可否・プレースホルダの型を補う。ヘッダにインラインで書かれたresolve_type(109 個)も parsegen が読むようにした(facts を持つクラス 144 → 323)。NULL 可否の既定は「引数のどれかが NULL 可なら NULL 可」(Item_func::fix_fields)、集約は「行が無ければ NULL」で COUNT / BIT_* / 窓関数だけ例外。読めないもの(Item_temporal_hybrid_funcの ADDTIME / DATE_ADD、サブクエリ、ユーザー変数)は未型付けで通す - mysqld オラクル(2026-09-10、実施):
mysql/check/postgres/oracle。PATH のmysqld(nix-shell -p mysql84。配布 tarball の bin/ でも同じ)を版ごとに一度--initialize-insecureして~/.cache/sqlshape/mysqld-<version>/templateに置き、Start ごとに一時ディレクトリへ複製して unix socket・networking off で起こす(約 2 秒)。Describe(sql)は SELECT を全パラメータ NULL で実行して結果セットのメタデータ(型・unsigned・NULL 可否・長さ・precision)を読む。書き込み文は prepare だけ。プレースホルダの型は COM_STMT_PREPARE が全部 VARCHAR で返すので検算できない。analyzeのTestOracleがanalyzeCases/errorCasesの全文を server に問い、列名・型・NULL 可否・エラー番号の一致をゲートにする(mysqld が無ければ skip)。初回の突き合わせで直ったもの: 文字列関数は strict mode で常に NULL 可(Item_str_func::fix_fields)、JSON 関数と型キャストも NULL 可、FLOOR / CEILING は桁が収まれば bigint、文字列リテラルの列名は値そのもの、IN (subquery)は NULL 可、x.*の不明テーブルは 1051。版の差(文法は 8.4.6、oracle は 8.4.11)は同じ LTS 系列なので許容し、Oracle.Versionに記録する - 関数表の差分テスト(2026-09-10、実施):
analyzeのTestProbeが registry の 347 関数 × 代表引数型(int / bigint unsigned / decimal / double / varchar / varbinary / datetime / date / time / json / NULL 可 int、文字列先頭+整数、整数先頭+文字列、末尾 NULL)× 引数個数で 5,267 文を生成し、server と analyzer の答えをtestdata/probe.goldenに 1 文 1 行で残す(=一致 /?未型付け /!不一致 /xserver が拒否 /Xanalyzer が拒否)。比較は型名と符号と NULL 可否で、文字列は「文字列 / バイナリ列」の 2 クラス(長さを計算しないので VARCHAR と TEXT の境目は判定できず、Go 側の受け型は同じ)。到達点: 一致 4,994、未型付け 29、不一致 10(REGEXP_REPLACE の NULL 可否 9、QUOTE の照合 1)、server 拒否 234(引数型の検査はしない)。この過程で直したもの: 文字列関数の結果照合(Item の既定はバイナリ、agg_arg_charsets_*があれば引数から、明示の charset があればそれ)、Item_geometry_funcの NULL 可、コンストラクタとfix_fieldsに書かれたset_nullable/unsigned_flag(parsegen がクラス本体も読む)、fix_fieldsの連鎖(Item_str_func::fix_fieldsに届くかで strict の NULL 可を決める)、return Base::resolve_type()形の継承、set_data_type_*は最後の文が勝つ、NULLIF / UNIX_TIMESTAMP / FROM_UNIXTIME / ST_X 系の instantiator、schema ローダーの BINARY(n) / VARBINARY(n)(parsegen が同じ引数個数の別コンストラクタで名前付けしていた)。golden の変更はレビュー対象
- 型規則の実施(2026-09-10):
- カタログの検算(裁定 2026-09-09): mysqld オラクル(配布 tarball を
--initializeで起こす)はカタログ生成のときに手元でだけ使い、生成物をコミットする。CI は検算しない(PG のcatalog/genと同じ扱い。tarball は 500MB 級で CI に載せる価値がない)。tarball は~/.cache/sqlshape/mysql-<version>に置く- マイグレーションの差分テスト(2026-09-15、実施): PG と同じ probe を
check/mysql/migrateに置く。測り方と数字は「マイグレーションは自前のdiff / apply」の「忠実度の測り方」に一本化した。MySQL 固有の判定は正準形が「その文を適用した mysqld にSHOW CREATEで読み返した DDL」であること、列の移動があること、DDL が文ごとに commit されるので apply が文単位で進むこと
- マイグレーションの差分テスト(2026-09-15、実施): PG と同じ probe を
- 回帰コーパスはMySQL自身の
mysql-test/t/*.test。パーサの受理率と、オラクルとの差分probeの両方に使う - 順序: パーサのスパイク(受理率で手段を裁定)→ 字句解析器 → CST→AST → スキーマローダー(CREATE TABLEの部分集合、
mysqldumpの正準形)→ アナライザーの型規則(mysqldをオラクルに差分テスト)→ テンプレート・vet・義務の結線(ここは共有部分なので薄い)。1.2の後
- 方言間の線引き(裁定 2026-09-10): 機能は方言の事実として現れるだけで、共通化しない。契約(
- TypeScriptフロントエンド。2つ目の言語フロントエンドで「核はSQLしか見ない」構想を検証する。言語非依存で共有するのは
check/postgres/analyze、check/postgres/schema、マイグレーション一式、失敗モード・Oneの証明・境界の規則。言語依存はその言語のデファクトに合わせる: 呼び出し箇所の発見(TypeScript Compiler APIかtsc plugin、ESLintルール)、R/P相当の型解決(query<R, P>(sql))、PG型とTS型の対応表(pg / postgres.jsが実際に返す型)、ランタイム。最初の設計論点はテンプレート構文で、Goのtext/templateを持ち込まず、sql\...`のタグ付きテンプレートと${}の断片で「有限の展開集合」を保つ方法(断片をリテラルの選択肢に限る、など)を決める。MySQLと同じく、cmd/sqlshape/internal/vetのPG固有型の切り出しが前提。横展開の見立て: 検査の大半(列と型の存在、失敗モード、Oneの証明、境界の規約、インジェクション保証、マイグレーション)はSQL側だけで閉じていてホスト言語の型を見ない。言語ごとに必須なのは「lintの口」「テンプレート定数の取り出し」「ランタイム」の3つで、R/P`の型照合は静的型がある言語で足す層(動的型の言語では実行時の行マッピング検査か、型ヒントがあれば静的に) - 2-way SQL構文(
/*{{.X}}*/'lit')。psqlでそのまま流せるテンプレート。expandとRenderの前段で同じ変換を入れる - ORMからの移行支援。ORMが発行したSQLを観測して
Query[R, P]に起こす