Notable changes to sqlshape, newest first. The format follows Keep a Changelog;
versions follow Semantic Versioning. Behaviour of the checker that makes a
statement pass or fail is listed under Changed even when the old behaviour was a bug, since a
passing program may start to fail. A release candidate (v1.1.0-rc.1) carries the section of the
release it is a candidate for.
2.0.1 - 2026-09-27
- A
-- @migrate backfilldeclaration left inschema.sqlafter its step is applied is now an error (diffexits 1 and the UPDATE is not printed) when nothing else about its table changes. Before, the UPDATE was silently printed again, and applying it overwrote data the application had written since. A backfill in a step that does change the table — a new column, a newCHECK/UNIQUE/ foreign key on existing rows — is emitted as before. mysql.Verifyno longer fails on asql_modename MySQL 8.4 does not define (a server of another version or lineage runs with some): it compares the modes it knows and, on a mismatch, says which names it left out.
- On MySQL,
sqlshape applyruns the DDL under thesql_modethe schema declares (the 8.4 default when it declares none), the same setting the plan was verified under. Before, the DDL ran under the server's global mode, so the pre-check and the real run could disagree. - On MySQL, a backfill of an existing column is printed before the keys,
CHECKconstraints and foreign keys the step adds, soapplyno longer fails on rows the backfill was meant to fix.
- The README leads with what a reader needs to decide: what is checked, the supported versions, that checking needs no database, and how sqlshape differs from generators and ORMs. A Limitations section states what is out of scope, including that a server of an undeclared version still runs but its divergences are not guaranteed to be caught.
- The MySQL error catalog moved to docs/mysql-errors.md with an index by error number; docs/mysql.md now leads with the type table, the DSN requirements and the runtime. docs/migrations.md starts with the prerequisites and gained a section on running migrations across several environments.
2.0.0 - 2026-09-20
- MySQL 8.4. A
schema.sqlthat declares-- sqlshape: mysql 8.4is checked by a MySQL analyzer: the parser and lexer are the server's own, the function catalog is read from the server's source, and the verdicts (types, nullability, errors, theONLY_FULL_GROUP_BYcheck) are measured against a runningmysqld.One, the obligations and the failure modes work through the same contract PostgreSQL uses, with the constraints named as MySQL reports them (PRIMARY,orders_ibfk_1,t_chk_1) andINSERT IGNORE/ON DUPLICATE KEY UPDATE/REPLACEjudged as the server runs them. What has no MySQL counterpart is listed in docs/mysql.md. - MySQL triggers, stored procedures and functions, and events: their bodies are analyzed
(
NEW/OLD, variables, control flow, cursors,SIGNAL/RESIGNAL/HANDLER,CALL), a statement inherits the failure modes of the triggers it fires and the routines it calls, and the server's own refusals (a trigger writing its own table, 1442, among them) are reported.-- sqlshape: error <code> = <Name>names a raised error, as on PostgreSQL;-- sqlshape: not nullabove aCREATE FUNCTIONdeclares it never returns NULL. - On MySQL the checker also reads
LOAD DATA(an INSERT of the file's rows, with the server's own 1263 for a NULL field in aNOT NULLcolumn),LOCK TABLES/UNLOCK TABLES,SELECT ... INTO OUTFILE/DUMPFILE(no result set) and aSELECTwith a trailingFOR UPDATE/FOR SHARE; the loader appliesALTER VIEW. Inside a routine or trigger body the first three are the server's own 1314. - MySQL writes through views, analyzed as the server runs them (each rule measured): an
INSERT/REPLACE,UPDATEorDELETEthrough a merged view lands on its base table, with the base table's own failure modes and the view's own (WITH CHECK OPTIONas the violation 1369 -- onINSERTandREPLACEtoo -- and a base column with no default the statement leaves unassigned as the view's 1423, both matched byViolatesunder the view's name), and the server's refusals are statement errors under the server's own codes: the view's updatable / insertable flags are computed over itsFROMleaves the waysql_resolver.cccomputes them when it merges, a join view follows the server's rules for each write kind,REPLACEandDELETEnever reach one, and a subquery reading the written view itself is 1093. The rules are docs/mysql-errors.md's. - The run-time failures MySQL decides by a constant's value are judged (each measured against
mysqld; the rules are docs/mysql-errors.md's): a literal a column can never store
(1264 / 1265 / 1292 / 1366 / 1406 / 1416, in strict mode outside
IGNORE), a temporal literal the server cannot read as its type (1525) or aTIMESTAMPcolumn cannot hold, the spatial rules (1210 / 3037 / 3516 / 1416), constant arithmetic the server cannot compute (1690), the constant conversions a strict write escalates (1292; a temporal column compared with a constant string that is no datetime is 1525 whatever the statement), and the functions that judge a constant argument's value:INET_ATON/INET6_ATON/UNHEX/STR_TO_DATEfail a strict write outsideIGNORE(1411;STR_TO_DATEunder a port of the server's ownextract_date_time),UUID_TO_BIN/BIN_TO_UUID(1411) andPERIOD_ADD/PERIOD_DIFF(1210) fail every statement whatever the mode, andNAME_CONST,ESCAPE,NTILE,NTH_VALUEandMATCH ... AGAINSTare refused at resolution, rows or none. Each is the statement's own error where the server evaluates it before reading rows, and a failure modeViolatesmatches by number ("1416","1690","1292","1411") where it runs per row. A prefix key (UNIQUE (c(10))) or an expression key (UNIQUE ((n * 2))) is a violable key (1062) for the writes that assign its columns. - A MySQL function call argument carrying an alias (
f(x AS a), the loadable function syntax) is refused in the server's own order (1582 / 1583 / 1584, a data dictionary function 3566), and an explicitly scoped system variable read must match the variable's scope:@@session.xof a GLOBAL-only variable and@@global.xof a SESSION-only one are the statement's 1238 wherever the read sits, over a scope table generated from the server source (sql/sys_vars.cc) and pinned against mysqld entry by entry; a plugin's or component's variable is not judged. - The statement facts the
Oneproof and the obligations are judged on are tested against a running server the way the checker's types are:x/stmtprobegenerates schemas with rows and statements over them (joins, views, derived tables, CTEs,EXISTS/INsubqueries,GROUP BY,UNION ALL, writes), and refutes every claim of the facts -- a predicate holding on every row, a fixed column, an at-most-one-row proof, the value a write stores -- with the rows the server returns, on PostgreSQL 17 and MySQL 8.4. The same probe judges the predicted failure modes: writes against a schema carrying every constraint kind (named and unnamed keys, foreign keys with eachON DELETEaction, checks,NOT NULL;IGNORE/REPLACE/ON DUPLICATE KEY UPDATEandON CONFLICT), with every constraint error the server raises required to be a predicted violation under a keyViolatesmatches. - MySQL trigger, procedure and function bodies are tested against the server's own
CREATE-time verdict the same way (the body probe in
check/mysql/internal/analyze): every construct the server refuses when the body is created, mixed into generated bodies, must be refused by the checker too, and nothing the server accepts may be. - MySQL's own test corpus (mysql-test/t: 1,281 files, 137,000 statements) replays against a
running mysqld and the analyzer side by side (
check/mysql/internal/analyze's corpus probe, the counterpart of PostgreSQL's regress probe): each file on a server of its own, the analyzer's schema rebuilt fromSHOW CREATEafter every DDL under the session'ssql_mode, a SELECT's columns compared by name, type family and nullability, an error by number; the remaining disagreements (2,525 statements) are pinned one by one as a baseline, and a new one fails the build. mysqltest.StartOwnboots a server of its own even undermysqltest.Main, for a test that changes accounts, global variables or other databases.postgres.WrapError(err)andmysql.WrapError(err)give an error from a statement run outsideRun/Execthe wrappingViolatesjudges.sqlshape.Error(code)declares a schema's named error in Go (var OrderTooLarge = sqlshape.Error("30001"));go vetchecks the declaration against the schema both ways, an expect line may use the Name, andViolatesaccepts the value.-- sqlshape: server <var> = <value>declares the server settings the checker's judgments depend on (MySQL:sql_mode,lower_case_table_names,max_sp_recursion_depth); the checker follows them, andmysqltest.Startstarts the server with them.- The MySQL runtime,
github.com/kr9ly/sqlshape/mysql/v2(Run,Collect,First,Exec,Get/Find/ExecOne,ConstraintError,Violates) overdatabase/sql, andgithub.com/kr9ly/sqlshape/mysqltest/v2, which boots themysqldonPATHwith the application's schema; a package whoseTestMainruns throughmysqltest.Mainboots one server per set of declared settings and hands it from test to test instead of booting one perStart.examples/5-mysqlshows the whole path. sqlshape diff,applyandverify-schemaon MySQL: both sides are read as the server's ownSHOW CREATEoutput, the target canonicalized in a scratch database on the same server, and the plan written in MySQL's own DDL, statement by statement. Tables with their options, columns with their position, keys, foreign keys, checks, views, triggers, routines, events and partitions are compared; seeded rows are not.- Partitions are migrated on both dialects: a partitioned table is created, a partition added,
dropped (under a
-- @migrate dropdeclaration, since it takes its rows), attached, detached, its bound moved with the rows that no longer fit moved along, and a populated table can be partitioned after the fact, unpartitioned, or repartitioned, the rows redistributed by the server. MySQL coversRANGE,LIST,COLUMNS,HASH,KEY,LINEARand subpartitioning (a partition's explicitSUBPARTITIONname list included), with-- @migrate drop partition <table>.<partition>for a partition that goes. - The migration planner is tested against a real server the way the checker is: generated schema pairs, every kind of change the diff can report, applied with rows in the tables on PostgreSQL 17 and 18 and on MySQL 8.4, with the plan required to land on the declared schema and leave nothing to plan afterwards (docs/migrations.md). The orderings and omissions this found are fixed and pinned as regression tests.
- Row-level security, composite types, rules, extensions, schema moves, standalone sequences,
procedures, aggregates,
EXCLUDE, partial and expression indexes,NULLS NOT DISTINCTandDEFERRABLEare handled by the PostgreSQL migration plan;FULLTEXT/SPATIAL/ functional /INVISIBLEkeys,ROW_FORMAT, table charset changes and column comments by MySQL's. x/dialect.Type.ElemNotNull: an array whose elements are provably not NULL (array_agg((a, b)::t), an inner-joinedNOT NULLcolumn) binds to[]Twithout the "may contain a NULL element" note;col:",notnull"on an array field asserts the elements too.-query=pkg.Func,pkg.Other:oneregisters a program's own marker functions, read likeQuery/One.- Every example in
docs/runs as a test: the checker must produce exactly the diagnostics the docs claim.
- The checker is the product; the runtime is a library per database. The root module
github.com/kr9ly/sqlshape/v2holds only the declarations and has no dependencies. Running a statement on pgx isgithub.com/kr9ly/sqlshape/postgres/v2(postgres.Run(ctx, db, stmt, p); the methodsstmt.Run(ctx, db, p)are gone), on MySQL.../mysql/v2. The analyzers arecheck/postgres(Apache 2.0) andcheck/mysql(GPLv2, MySQL's own parser), the binarycmd/sqlshape(GPLv2,go install github.com/kr9ly/sqlshape/cmd/sqlshape/v2@latest); nothing under them is linked into your program. Every module path carries/v2, and all modules release together under one version. - The
Oneproof is written once, over the statement's facts, for every dialect. Two verdicts change on PostgreSQL:GROUP BY 1(an ordinal or an alias) is no longer a pinned constant, so such a statement is not proved single; aLIMIT 1over aUNIONand an aggregate over aFULL JOINare proved. - A template's
if/with/rangeover a path an earlier control already decided follows that decision, so impossible expansions are no longer checked; a pointer parameter inside its own{{if .X}}branch is not NULL there;-strictadvice about a table or column is reported only in packages that touch it. - PostgreSQL verdicts corrected against the server:
TRUNCATEof a still-referenced table is certain to fail;ON CONFLICTabsorbs a unique constraint only when it can be the arbiter (aDEFERRABLEkey, or a partial index whose predicate is not repeated, keeps its 23505); a domain'sNOT NULLis keyed by the domain's name;unnest(arr)in the select list is nullable;SET col = DEFAULTis a transition to the literal default;-strictrejects[]Tfor an array whose Go element cannot be NULL;intervalintotime.Durationcarries a Lossy note;pairedrequires the write, not matching values;RETURNINGasensitivecolumn is reading it. - Obligations on both databases:
require singleon an UPDATE or DELETE asks about the target table's rows alone, so a join that only filters no longer breaks the proof;transitionsreads MySQL's constants (both producers now spell a constant the same way);pinnedpropagates across a composite foreign key only into aNOT NULLcolumn (a NULL in a foreign-key column exempts the row from the constraint, so such a row joins the parent while agreeing on nothing);WITH CHECK OPTIONfollows every view of a chain the servers enforce -- an underlying view behind a join, and an underlying view with its own check option under aLOCALone. - Migrations refuse what they cannot do losslessly instead of noting it: a change of
INHERITS,OF type, a domain's base type, a range's subtype, or a composite type's attribute type while a column uses it stopsapplyas a problem.pgtestandmysqltestare sqlshape's own test tooling with no compatibility promise; the docs are reorganized per database (docs/postgres.md, docs/mysql.md).
- A subquery in a join's
ONclause referencing a joined table's column was recorded as a value known before the statement runs rather than as the row's own column, so a proof or an obligation could rest on it (found byx/stmtprobeagainst a running PostgreSQL).
1.2.0 - 2026-09-09
- PostgreSQL 18:
schema.sqldeclares its version with-- sqlshape: postgres 18, and the schema and every statement are judged with 18's grammar and catalog (RETURNING old/new,WITHOUT OVERLAPSkeys andPERIODforeign keys,NOT ENFORCEDconstraints, namedNOT NULLconstraints,VIRTUALgenerated columns).pgtestand the migration commands run the declared version. Oneproves a single row through a temporal key (valid_at @> {{.Day}}::date).
SELECT DISTINCT ONexpressions are matched to the leadingORDER BYexpressions by expression, not by position.- An UPDATE that assigns a generated column reports PostgreSQL's own message.
schema.sqlmust declare its PostgreSQL version (-- sqlshape: postgres 17); add the line to move from 1.1.- The parser is compiled to WebAssembly and run by wazero instead of linked through cgo:
go installneeds no C compiler, and prebuilt binaries cover Linux, macOS and Windows on amd64 and arm64.
1.1.0 - 2026-09-08
- Obligations:
schema.sqldeclares, above aCREATE TABLEorCREATE VIEW, what every statement touching the relation must do, and vet judges each statement against it (checks.md, Part 2):require <predicate | pinned(col) | immutable(col) | via view | never | paired(table) | single> [on <kinds>],aggregate root (children) [lock version],transitions col: a -> b,sensitive label: colswithcontext name: may read label, per-callercontext name: require ...; waive ..., and-- sqlshape: waiveas the opt-out. sqlshape check: the same judgments for SQL outside Go, one audit line per judgment.
visible where,-require-columns,-no-table-readsand-no-tablesare obligations now and are judged per occurrence of a table (a self join owes it again). Writes are counted by what the statement does: each MERGE branch, both halves ofINSERT ... ON CONFLICT DO UPDATE,TRUNCATEas a delete, a write through an updatable view as a write to the base table.pinnedon an UPDATE is satisfied by the WHERE only.- A
-- sqlshape:directive above a statement that takes none is a schema problem. - The docs are split: the README is an overview; docs/ has checks, templates, runtime, migrations and flags, in English and Japanese.
- A vet failure shared by every branch of a template is reported once, without the branch tag.
- A diagnostic on a column referenced only in GROUP BY had no position.
1.0.0 - 2026-09-07
First release: sqlshape.Query[R, P] / One[R, P] templates checked by go vet against
schema.sql (a pure Go analyzer of PostgreSQL 17 syntax and types, with PostgreSQL itself as the
test oracle), the runtime on pgx, and sqlshape diff / apply / verify-schema for migrations
from a declared schema.