Compatibility differences
Cases where ptah-compat deliberately differs from the pinned Atlas community binary, with the measurement and current policy for each case.
The drop-in rule has two directions and they are not symmetric. ptah-compat
must never exit 0 where the pinned Atlas community binary exits 1
over a mistake in the invocation; that direction is a correctness failure and
there are no entries for it. Where the binary fails for a reason the invocation
does not cause, there are two entries:
A YDB database URL, an engine it has no driver for, and
A golang-migrate file that runs its own transaction,
a file it nests in a transaction of its own. The other direction — ptah-compat exits 1 where that binary exits 0 — is a
usability failure for a drop-in replacement, and it is allowed only where the
refusal is more useful than the acceptance.
Each retained case records what both binaries did, so a reader can evaluate the
decision rather than only the outcome. The
one-line status per capability is on the Feature matrix.
Most entries came out of
stokaro/ptah#1241; the project
migration-directory boundary is tracked in
stokaro/ptah#1118.
What parity means, and what it does not
Section titled “What parity means, and what it does not”The direction stated above — never exit 0 where the pinned binary exits 1 —
is the first of two commitments. The second is that a defect is not reproduced
for the sake of being identical. Where a measured behavior loses something the
author asked for, ptah-compat does the better thing and records the difference
here.
One case shows the second commitment on its own, and it is not an entry below
because nothing is refused. A migration can carry -- atlas:txmode none
directly above its statement, with no blank line between the two. That directive
marks a statement that must run outside a transaction, such as
CREATE INDEX CONCURRENTLY. In that shape the community binary drops the
directive, so the statement runs inside a transaction and the migration fails
partway through. ptah-compat honors both shapes.
ptah-compat therefore has two policy profiles. The default retains every
implemented Atlas Pro-like and best-effort capability on the drop-in surface.
PTAH_ATLAS_STRICT_COMPAT=1 selects a Community Edition oracle profile for
conformance runs, which exposes the pinned CE command and flag inventory and
refuses extended authored or live schema content before output or mutation.
These boundaries also remain active under
PTAH_ATLAS_STRICT_COMPAT=1. Strict mode limits the CE capability inventory;
it does not reproduce an acceptance that discards an argument, hides an edited
migration, or loses recoverable state.
The same rule protects richer live schemas. The pinned community inspector can
omit object kinds outside its edition, and its cleanup can leave or handle a
catalog differently from Ptah’s complete cleanup. Strict mode therefore
refuses a live Pro-only object before schema inspect, schema apply,
schema diff, or schema clean emits output, compares incomplete states, or
mutates the target. Default ptah-compat keeps Ptah’s complete modeled-object
behavior; the refusal exists only in the CE oracle profile.
The command-specific inventory remains read-only. Cleanup validates the writer’s complete destruction inventory, including PostgreSQL procedures, aggregates, foreign tables, collations, and default privileges. Inspection, apply planning, and database-backed or replayed schema- and migration-diff sources query those catalog-only kinds in the same schema scope. A dependent Pro-only object such as a trigger cannot disappear with a table merely because the cleanup plan does not print it as a separate line.
Cleanup validation uses the writer’s schema scope: a global
extension installed in another PostgreSQL schema does not block cleaning the
selected schema. A sequence backing a SERIAL or identity column is likewise
not treated as a forbidden standalone sequence, because it rides with the
table that owns it. A selector cannot split that ownership: selecting the
sequence without its table, or excluding it while the table remains selected,
is refused before mutation.
PTAH_ALLOW_NONINTERACTIVE_EDIT=1 remains available in strict mode. It permits
an already-configured scripted editor to run without a terminal; it does not
add an editor, command, flag, or migration semantic, so it is retained as an
execution-safety control rather than classified as a Pro capability.
The same fail-closed boundary covers authored extensions. Strict schema
workflows refuse YAML sources and a schema apply lint policy that the CE path
cannot enforce. Commands that execute, convert, or replay migration bodies
refuse Atlas txtar, Ptah directives, and SQL templates; a bare or unknown
-- +ptah directive marker is refused rather than ignored. Checksum-only reads
preserve those bytes. Default mode retains and executes the extensions. The
strict profile never turns an authored safety contract into an ignored comment
or configuration block merely to copy an edition limit.
The entries from here to What holds the #1241 entries were measured on 2026-08-09 against that binary, except where a section gives its own date, each exit status read on its own line rather than through a pipe. Where a fixture needed a hashed migration directory, that binary authored and hashed it, so no checksum quoted in them was computed by Ptah. The sections after it carry their own measurement conditions.
The entries
Section titled “The entries”| Entry | ptah-compat |
Pinned community binary v1.3.0 |
|---|---|---|
| A trailing positional argument | refuses one on a verb that defines none, naming the flag the value belongs to | accepts it and discards it without a word |
| An edited already-applied migration file | compares each applied migration against the checksum recorded when it ran, and refuses on a mismatch | records the same value and never compares it |
| A prefix migration inserted below the oldest applied revision | refuses at the default --exec-order linear with the binary’s own out-of-order line |
exits 0 with No migration files to execute, saying nothing about the file it passed over |
| A file numbered above the current version that sorts below it as text | reports it as out of order and refuses it at the default --exec-order linear |
reports OK and exits 0 with No migration files to execute under every --exec-order; the file never runs |
| A file whose Atlas version is empty | refuses the directory before anything runs and names the file, and does the same for a version that starts with a dot | runs _x.sql and records the version "", and runs .draft_x.sql as .draft |
migrate set past a file that sorts above the target |
records every file whose version is at or below the target as text | stops at the first file in file-name order whose version sorts above the target, so migrate set 1 beside 10_c.sql exits 0 and records nothing |
A file --exec-order linear-skip leaves pending |
writes one warning per skipped file on stderr | skips it without a word |
| A dirty revision left by a non-transactional body | discards the revision row only where it observed the rollback, so --tx-mode none needs --allow-dirty |
keeps the row in both cases and resumes from it |
| A project migration directory outside its root | confines a project migration.dir to the directory holding atlas.hcl |
writes the migration and atlas.sum wherever the project file points |
sql() inside check.expr and index.where |
reduces sql() to the SQL it carries, in both attributes |
refuses both with incorrect type raw |
| Revision row for a migration whose body failed | matches the binary; native ptah migrations up keeps a durable failed row |
writes no revision row when the body’s transaction rolled back |
| Failed rollback state | marks direction and partial progress in the existing Atlas columns | hides the failed-down state |
| Dirty retry verifies committed statements | proves every skipped statement has unchanged source text before resuming | resumes from applied + 1 by statement index |
Recorded revision error text on a failed migration |
records the SQLite driver’s own wording | records its own driver’s wording for the same condition |
| Pre-migration checks in a dry run | exits 1 where the guard’s verdict is knowable and negative |
implements no check semantics, so a dry run exits 0 for every checked directory |
atlas.hcl file() confinement |
reads file() only from the directory holding that atlas.hcl |
reads an absolute, parent-traversal, or link-escaping path |
| A migration that would be recorded over an invalid index | refuses while pg_index reports the index unusable, and names REINDEX |
applies the migration and records it over the unusable index |
schema inspect --include |
positively selects top-level resources through the apply and diff engine | does not register the flag: Error: unknown flag: --include |
| Exclude field selectors | honors the suffixes it can carry out and refuses the rest | accepts every such suffix and honors none of them |
| An exclude selector that matches nothing | warns on schema inspect and schema diff, refuses schema apply, and names the flag or the atlas.hcl the selector came from |
exits 0 and says nothing |
| Leading schema type selector | keeps the literal answer on every schema source | gives source-dependent answers, leaving the named table in a file diff’s plan |
| A constraint an exclude selector names | keeps the constraint and its index under [type=constraint], a wildcard, or a pattern read through the table |
accepts the selector and drops the constraint |
| The AUTOINCREMENT mark of a rebuilt SQLite table | keeps the mark, so a deleted key is not handed out again | rebuilds the table with the mark at the largest key it copies |
A SQLite file that sets legacy_alter_table |
gives each file the setting the connection held before the run | leaves the setting as one file set it for the files after it |
| One version spelled two ways | refuses the directory and names both files | applies both files as two revisions |
| Two files for one version | refuses the directory before anything runs and names both files | runs the first file, records its revision and crashes with exit 2; the second file never runs |
| A revision spelled apart from its file | refuses the history and prints the statements that respell the rows | compares versions as text and leaves a new file unapplied |
A Liquibase rollback written by migrate diff |
writes --rollback <SQL>, which Liquibase runs |
writes --rollback: <SQL>, which Liquibase reads as a comment |
| A database outside a one-database URL | refuses a document that declares another database, or puts an object in one | reads a SQL file that creates the other database first as synced, and drops what it puts there |
| A dev database holding an object the reset drops | refuses it and names the object | accepts it, then keeps or drops the object depending on the engine and the search_path |
| A whole server cleaned without an opt-in | refuses schema clean on a MySQL or MariaDB URL naming no database unless PTAH_ALLOW_SERVER_CLEAN=1, and lists the databases |
drops every user database at exit 0 |
A dev server that is the --to side, or beside one database |
refuses both on migrate diff before the replay |
replays onto a --to server that holds no database, and diffs one database against a server |
| A SQL file naming a database beside a dev database | creates a file naming one database inside the dev database, and refuses one naming two before running it | runs the file as written on the dev connection and creates its tables in the databases it names, the target included |
| A dev database beside a whole server | refuses it on schema apply for every desired schema, before the dev database is contacted |
plans a document declaring one database, and replays SQL onto the dev database’s server before it refuses |
| A YDB database URL | serves it through the YDB provider in the default profile, and refuses it in the binary’s words under PTAH_ATLAS_STRICT_COMPAT=1 |
has no YDB driver: sql/sqlclient: unknown driver "ydb" |
| A realm beside one database on a dev server | refuses the pair on schema diff, with the binary’s own schema apply sentence for it |
plans databases the one-database side never read |
| A golang-migrate file that runs its own transaction | runs it as golang-migrate does, outside the migrator’s transaction, and exits 0 |
nests it in a transaction of its own and exits 1 with pq: unexpected transaction status idle |
A txmode none file that controls its own transaction |
lint reports TX201 for each such block, and apply refuses the run before it applies the first file, exit 1 |
lint reports nothing, and apply runs the file as written, exit 0 |
| A file its transaction would refuse | refuses the run before it applies the first file, in a dry run too, exit 1 |
applies the files before it and exits 1 with PostgreSQL’s error; its dry run exits 0 |
| A file that controls the transaction it runs in | refuses the run before it applies the first file, in a dry run too, exit 1 |
applies the files before it and exits 1 with the engine’s error; its dry run exits 0 |
| A MySQL file the transaction witness refuses | refuses the run before it applies the first file, in a dry run too, exit 1 |
applies every file, exit 0 |
| A statement the bundled SQLite refuses | replays on the SQLite it bundles, reports the refusal as a replay error of the file, and exits 1 |
replays on an older SQLite that accepts the statement, and lints the selection |
| A column written with two defaults | refuses the column definition on every engine and names the column | keeps the last default on SQLite, exit 0, and refuses the file on PostgreSQL |
| A finding in a goose or dbmate file | places it on the statement’s line of the source file, at the statement’s offset | places it on line 1, the section directive, at an offset that falls there |
| Removing a column-level UNIQUE on SQLite | rebuilds the table, and the plan applies to a database the --from document created |
plans DROP INDEX for an index the database does not hold, and the apply exits 1 |
| A COLLATE on a SQLite index key | reads the key with its collation, so a change of it is planned | reads the column alone, reports the change as synced, and plans the index without it |
| A COLLATE on a SQLite column | schema inspect writes the collation a column declares, in every format, and schema diff and schema apply plan a change of it |
writes none, so the document describes a column that compares as BINARY, and reports the schemas synced |
| A COLLATE on a PostgreSQL column | schema diff and schema apply plan a change of a column’s collation |
report the schemas synced |
| A changed MySQL table collation | plans the table’s COLLATE in one statement with the reset of the column that takes it, so one apply converges |
does the same with --dev-url; without it, plans the table’s COLLATE alone, and the column keeps the old collation until a second apply |
| A foreign key over a changed collation | drops the foreign key, changes both ends, and adds the key back, so one apply converges | plans a bare MODIFY COLUMN of each end, which the server refuses while the key stands |
| A foreign key taken back under its name over a retyped column | drops the key before the referenced column changes, so the file applies | changes the referenced column first, which the server refuses while the key stands |
| A MariaDB table changed to a UCA 14.0.0 collation | writes the character set the collation names on the table, restates a column that takes it without one, and converges in one apply | writes the dev database’s character set beside a collation of another, which MariaDB refuses, and gives such a column the character set’s default collation |
A backslash on a NO_BACKSLASH_ESCAPES session |
writes a literal for the session that runs it, so the server stores the declared value | stores four backslashes where the declaration holds one |
A --config selection naming more than one file
Section titled “A --config selection naming more than one file”Type. Deliberate divergence
Current boundary. The pinned community binary registers -c/--config as
strings: comma-separated and repeatable, defaulting to [file://atlas.hcl].
Ptah reads one project file, and ptah-compat refuses a selection that names
more than one rather than reducing it.
What the pinned binary registers is read from the capture this repository
commits beside its schema-plan tests, atlas-v1.3.0-schema-plan-help/new.txt,
whose provenance.json pins the binary by digest:
-c, --config strings select config (project) files using URL format (comma-separated) (default [file://atlas.hcl])strings and (comma-separated) are what that capture establishes. How that
binary resolves two files is not measured here and is not claimed.
Measured on ptah-compat, with two project files declaring one env each:
| invocation | ptah-compat |
|---|---|
-c "file://first.hcl,file://second.hcl" --env first |
exit 1, --config names 2 files (…), and Ptah reads one |
-c file://first.hcl -c file://second.hcl --env first |
exit 1, --config was given more than once, and Ptah reads one project file |
-c file://first.hcl --env first |
exit 0 |
The refusal exists because the alternative is a silent reduction. A surface that reads one file out of two the operator named has to say which one it dropped, or the next diagnostic blames whatever the missing half declared: an env selected from the discarded file reads as an env that does not exist, which sends the operator to fix the file they actually passed.
The flag keeps its string type rather than claiming CE’s strings.
Advertising a list this surface then refuses would trade a silent loss for a
false promise, and the reader learns the limit from the refusal at the moment it
matters.
Reading several project files is the capability behind this boundary, and it is not implemented. Nothing here forecloses it: the refusal names the flag, so a run that starts working when the capability lands changes no spelling.
A trailing positional argument
Section titled “A trailing positional argument”Type. Deliberate divergence
Current boundary. ptah-compat refuses a positional argument on verbs that
define none, and names the flag the value belongs to. That binary accepts one
and discards it without a word.
Measured on SQLite, one hashed migration directory shared by every row:
command, with trailingarg appended |
pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
migrate status --dir file://migrations --url sqlite://s.db |
exit 0, status printed |
exit 1, name the migration directory with --dir |
migrate validate --dir file://migrations |
exit 0 |
exit 1, same wording |
migrate lint --dir file://migrations --dev-url … --latest 1 |
exit 0, report printed |
exit 1, same wording |
schema inspect --url sqlite://s.db |
exit 0, HCL printed |
exit 1, name the database with -u/--url |
The argument that keeps the refusal is that on every one of these verbs the
discarded value is the one an operator meant to pass to a flag. migrate status migrations and schema inspect sqlite://s.db are both the natural typo for
the correct command, and both are exit 0 on that binary against the wrong
target: the first reports on ./migrations because the flag defaulted, not
because the positional was read. A tool that answers a question the operator
did not ask, with no sign that it did so, is worse than one that refuses. This
is the reasoning the --dir defaults landed under, where a default that
silently swallowed a typo would have migrated the wrong directory at exit 0.
The refusal is not carried behind an environment variable. A variable that
restored the acceptance would have to default to the permissive side. Feature
toggles instead opt in to more permissive behavior so that a typo lands on the
strict default. The separate PTAH_ATLAS_STRICT_COMPAT policy selector narrows
the command inventory for CE oracle runs and does not relax this refusal.
migrate hash takes no positional either and refuses through the same helper,
cmdutil.NoPositionalArgsHint. That cell is measured now, and it lands on this
same argument. Read 2026-08-17 on a hashed SQLite directory, exit status taken
from an unpiped invocation:
| argv | Atlas CE v1.3.0 | Ptah |
|---|---|---|
migrate hash --dir file://mig extra |
0, zero bytes of output |
1, unexpected positional arguments ["extra"]: name the migration directory with --dir |
The zero bytes are the finding rather than the exit status. That binary does not
report the extra word, and it does the work anyway: a migration added before the
run is hashed into atlas.sum exactly as if the positional had not been typed.
So the operator who meant --dir extra and dropped the flag gets a rewritten
checksum file for a directory they did not name, at exit 0, with nothing
printed (stokaro/ptah#1623).
An edited already-applied migration file
Section titled “An edited already-applied migration file”Type. Deliberate divergence
Current boundary. ptah-compat migrate apply compares each applied
migration against the checksum recorded when it ran, and refuses when they
disagree. That binary records the same value and does not compare it, so an
edited applied file is a no-op there.
Measured on SQLite and again on PostgreSQL 17.10, identical on both. Two
migration directories sharing the version 20240101000000 and differing only
in the body — CREATE TABLE t1 (id integer primary key) against
CREATE TABLE t1 (id integer primary key, note text):
| step | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
| apply the first directory | exit 0, table created |
exit 0, table created |
| apply the second directory | exit 0, No migration files to execute |
exit 1, checksum mismatch |
The edit is real: the file that ran is not the file on disk any more. Treating
that as a no-op means the migration directory stops describing the database it
was applied to, and the difference surfaces later as a diff nobody can explain.
The refusal names the version and both checksums, and --allow-dirty is not
involved.
A prefix migration inserted below the oldest applied revision
Section titled “A prefix migration inserted below the oldest applied revision”Type. Deliberate divergence
Current boundary. This entry covers a prefix migration that sorts below
every applied revision. ptah-compat migrate apply refuses at its default
--exec-order linear with the line that binary prints for an interval
insertion, and the page that line links describes both ways forward.
--exec-order linear-skip leaves the insertion unapplied; --exec-order non-linear applies it. Those are that binary’s own flag and its own three
values, not a Ptah addition.
An insertion between two applied revisions is a different observable state.
Measured on SQLite and PostgreSQL 17.10 on 2026-08-10, both binaries refuse
that interval insertion at the default order and apply it under non-linear.
The lower applied revision is the state that distinguishes that parity cell
from the prefix divergence below.
Measured on SQLite on 2026-08-12. Both directories were authored and hashed by
that binary through migrate import, so no checksum here was computed by Ptah.
dirA holds only the later migration; dirB prefixes it with an earlier one
and holds a byte-identical copy of the later one. diff between the two copies
exits 0.
| step | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
apply dirA |
exit 0, later migration applied |
exit 0, later migration applied |
apply dirB, default order |
exit 0, No migration files to execute |
exit 1, migration file <early>.sql was added out of order |
apply dirB, --exec-order linear-skip |
— | exit 0, insertion left unapplied |
apply dirB, --exec-order non-linear |
— | exit 0, insertion applied |
The second row is the entry. That binary’s default order is linear by its own
--help, and on that row it exits 0 while never applying the inserted
migration: the table that migration creates is absent from the catalog
afterwards, and only the later revision is recorded. It prints nothing about
the file it passed over. An operator who adds a migration to a directory,
runs apply, and reads exit 0 has been told the directory is applied when one
of its migrations never ran and never will.
That is the argument for the refusal, and it is not a strictness preference.
Reproducing an exit 0 that discards an operator’s migration silently is the
kind of defect the parity rule declines to copy. The refusal names the file it
will not apply, in the wording the binary uses for an interval insertion, so
the operator chooses between skipping and applying rather than having the
choice made and not reported.
A history whose newest file was removed from the directory takes the same
answer. The recorded revision still orders the history, so a file added below
it is refused where the binary prints No migration files to execute and exits
0.
A Flyway directory shows the same boundary inside one refusal. Measured on
2026-11-14 over SQLite, with V2__a.sql applied and V1.5__c.sql and
V10__b.sql added, the binary names only V10__b.sql, whose token sorts below
2 as text, and passes over the prefix file without a word. ptah-compat
names both:
Error: migration files V1.5__c.sql, V10__b.sql were added out of order. See: https://atlasgo.io/versioned/apply#non-linear-errorWith V1__a.sql and V3__b.sql applied and V2.5__c.sql and V10__d.sql
added, neither file is a prefix, and both binaries print the same line naming
both files.
Nothing is removed by refusing it as the default. The third row is the pinned binary’s own outcome, reachable on request through its own flag, and it is pinned by a test so it stays reachable. The fourth row is the outcome an operator who inserted the migration on purpose usually wants, which that binary’s default order does not offer at all.
One thing here changed rather than being retained. The refusal used to be reported as a checksum mismatch on the later migration, whose bytes had not changed: the per-file entry in an integrity file is chained over the entries before it, so inserting anything earlier changes the recorded value of every applied migration above it. The value is an ordering key, not a content identity, and the message claimed otherwise. That is fixed; the diagnostic now describes the ordering fact it actually found. The genuine content-change case keeps the checksum wording and is the section above.
A file numbered above the current version that sorts below it as text
Section titled “A file numbered above the current version that sorts below it as text”Type. Deliberate divergence
Current boundary. In an Atlas-format directory both binaries decide
linearity on text, byte for byte: a pending file is out of order when its name
sorts before the name of an applied file, or its version sorts below the
highest applied version. 10_b.sql added after 9_a.sql meets both
conditions, because 10_b.sql sorts before 9_a.sql and 10 sorts below
9. ptah-compat reports it as out of order and refuses it at the default
--exec-order linear. The other two orders treat it as they treat any
out-of-order file.
Measured on SQLite, with 9_a.sql applied, then 10_b.sql
added and the directory rehashed:
| step | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
migrate status |
OK, Pending Files: 0 |
PENDING, Pending Files: 1 (out of order), and the refusal as ERROR |
migrate apply |
exit 0, No migration files to execute |
exit 1, migration file 10_b.sql was added out of order |
migrate apply --exec-order linear-skip |
exit 0, No migration files to execute |
exit 0, one warning, the file left pending |
migrate apply --exec-order non-linear |
exit 0, No migration files to execute |
exit 0, 10_b.sql applied |
The binary’s own rule calls the file late on both counts, and then it neither
applies the file nor refuses it. Status reports the directory as applied, and
non-linear, the order that exists to apply such a file, does not see it
either. The file never runs, and nothing says so. Copying that would tell an
operator who added a migration that it is applied when it is not, which is the
kind of defect the parity rule declines to copy.
So ptah-compat is stricter here, deliberately. The refusal is the binary’s
own line for an out-of-order file, and the page it links describes both ways
forward. A file whose number is above the current version reads as new to a
person, which is why the case is easy to meet: going from 9_ to 10_ is
the usual way a directory without zero-padded versions grows.
A file whose Atlas version is empty
Section titled “A file whose Atlas version is empty”Type. Deliberate divergence
Current boundary. Both binaries read the version of an Atlas file as the
text before the first underscore of its name, whatever it holds: 1.x.sql is
version 1.x, v1_x.sql is v1, 00_x.sql is 00. Both run and list the
files in file-name order, order the versions as text on migrate set, and
record that text in the revision table. The one name they
part on is a file whose name starts with an underscore, such as _x.sql, whose
version is the empty string. ptah-compat refuses the directory before
anything runs and names the file.
Measured on SQLite, with 1_a.sql and _x.sql in one
directory:
| step | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
migrate apply |
exit 0, runs both, records "" and 1 |
exit 1, Atlas migration file Ptah cannot run: _x.sql (version "") |
migrate status after 2_b.sql is added |
Current Version: 1, 2_b.sql out of order |
the same refusal |
No command line can name the empty version: --to-version, --baseline and
migrate set each read an empty argument as no version. A file that a person
can run but never address is a file migrate set cannot move past and
migrate down cannot select, so ptah-compat asks for a name instead.
A version that starts with a dot is refused the same way. The revision table
keeps rows of its own under such versions, such as .atlas_cloud_identifier,
and Ptah reads every one of them as the table’s own. On the pinned community
binary v1.3.0, measured on SQLite, .draft_x.sql runs, is recorded as
.draft and counts as executed. Ptah would run it and then report it pending,
so it refuses the directory and names the file.
migrate set past a file that sorts above the target
Section titled “migrate set past a file that sorts above the target”Type. Deliberate divergence
Current boundary. Both binaries order the versions of migrate set as
text. They part where a file whose version sorts above the target comes first
in file-name order. The underscore after a version sorts after digits and
capital letters, so 10_c.sql and 1R__rep.sql come before 1_a.sql, and
20_c.sql before 2_b.sql. The pinned community binary stops at the
first such file and records only the files before it. ptah-compat records
every file whose version is at or below the target.
Measured on SQLite, over an empty database and a directory hashed by the binary:
| directory | command | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|---|
1_a.sql, 10_c.sql, 2_b.sql, v1_x.sql |
migrate set 1 |
exit 0, no output, no row |
exit 0, records 1 |
1_a.sql, 1R__rep.sql |
migrate set 1 |
exit 0, no output, no row |
exit 0, records 1 |
1_a.sql, 10_c.sql, 2_b.sql |
migrate set 1 |
exit 0, no output, no row |
exit 0, records 1 |
1_a.sql, 2_b.sql, 20_c.sql |
migrate set 2 |
exit 0, Current version is 1 (1 set), records 1 |
exit 0, records 1 and 2 |
The binary drops the version the operator named and still exits 0, so with
no row recorded 1_a.sql stays pending. Where no such
file comes first, as for set 2 over the first directory, both record the same
rows.
Evidence. integration/atlas_compat_opaque_versions_e2e_test.go
A file --exec-order linear-skip leaves pending
Section titled “A file --exec-order linear-skip leaves pending”Type. Deliberate divergence
Current boundary. ptah-compat migrate apply --exec-order linear-skip
leaves each out-of-order file pending, as the pinned community binary
does, and writes one warning per skipped file on stderr. The binary writes
nothing. Stdout, the database and the exit status are the same on both.
Measured on 2026-11-14 over SQLite, with 1_a.sql and 3_c.sql applied and
2_b.sql added, each exit status read from an unpiped invocation:
| Run | Binary | ptah-compat |
|---|---|---|
migrate apply --exec-order linear-skip |
No migration files to execute, empty stderr, exit 0 |
No migration files to execute, one warning on stderr, exit 0 |
the same, with --format '{{ json . }}' |
the report, empty stderr, exit 0 |
the same report, one warning on stderr, exit 0 |
level=WARN msg="Skipping out-of-order migration" version=2 currentVersion=3The warning stays because it is the only output that names the file. Stdout
reports nothing to execute while 2_b.sql is still pending, and the binary’s
answer gives an operator no sign that a migration of theirs was passed over. A
Flyway directory names each version by its source token, such as version=1.5 currentVersion=2, never by the numeric key its conversion runs under.
Evidence. integration/atlas_migrate_apply_report_shape_e2e_test.go
A dirty revision left by a non-transactional body
Section titled “A dirty revision left by a non-transactional body”Type. Deliberate divergence
Current boundary. When a migration body fails, ptah-compat migrate apply
discards the revision row it wrote if — and only if — this invocation observed
the body’s transaction roll back with nothing committed. Under --tx-mode none
there is no transaction to observe, so the row stays and the next apply refuses
until --allow-dirty is passed. That binary keeps its row in both cases and
resumes from it.
Measured on SQLite and again on PostgreSQL 17.10, identical on both. Two migrations; the second creates a unique index that fails against duplicate rows inserted between the two applies; the duplicate is then deleted and the apply repeated. No migration file is edited at any point, so the integrity file stays valid throughout:
| step | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
| apply the first migration | exit 0 |
exit 0 |
| apply the second, duplicates present | exit 1 |
exit 1 |
repair the data, apply again, default --tx-mode file |
exit 0 |
exit 0 |
repair the data, apply again, --tx-mode none |
exit 0, resumes |
exit 1, is dirty: state=failed applied=0/1 |
The third row is the one that matters most and the two agree on it. The fix-and-rerun flow that #1241 called permanently wedged recovers under the default transaction mode, because a confirmed rollback that committed nothing is discarded.
The fourth row is retained. applied=0 is not proof that nothing happened when
no transaction wrapped the body: --tx-mode none exists so that statements
which cannot run inside a transaction can run, and on PostgreSQL a failed
CREATE INDEX CONCURRENTLY leaves an invalid index behind while the statement
counts as not applied. Ptah already refuses to record a migration over such an
index. Discarding the row automatically in that mode would hand the next run a
clean slate over a database that is not clean. --allow-dirty remains the way
through while the same migration body remains in the directory, and the
operator, unlike the tool, can look first. If that source file is removed,
Ptah refuses the now-unowned dirty exact identity even with --allow-dirty;
there is no body or verified prefix to resume.
A project migration directory outside its root
Section titled “A project migration directory outside its root”Type. Deliberate divergence
Current boundary. A migration.dir declared in atlas.hcl must remain
inside the directory containing that project file after symbolic-link
resolution. The rule applies to relative and absolute values. An explicit CLI
--dir remains operator-owned: a directly named absolute directory keeps its
normal CLI behavior.
Measured on 2026-08-12 with migrate diff, a local SQL desired schema, and a
SQLite dev database:
project migration.dir |
pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
file://migrations |
exit 0, writes migration and atlas.sum inside the project |
exit 0, same artifacts inside the project |
file://../outside |
exit 0, writes migration and atlas.sum outside the project |
exit 1, outside allowed root, outside directory untouched |
file:///absolute/outside |
exit 0, writes migration and atlas.sum outside the project |
exit 1, outside allowed root, outside directory untouched |
The project file is repository-controlled input. Letting it select an arbitrary
write destination means a configuration change in a pull request can publish a
migration and replace an atlas.sum anywhere the process can write. That is not
equivalent to an operator explicitly naming an absolute --dir at the command
line. Binding the project value to the already-open project handle preserves
the useful explicit CLI capability while refusing the implicit external write.
The refusal also closes the spelling hole. Previously a contained relative value carried the project root, while parent-relative and absolute spellings silently dropped the root and fell through to unbounded CLI resolution. The destination now determines the answer: every project-owned value is checked against the same root before output or mutation.
What holds the #1241 entries
Section titled “What holds the #1241 entries”The issue #1241 entries above are pinned by a test in
internal/cli/atlas/compat_1241_retained_divergence_test.go, and the trailing-positional
rows for migrate status, migrate validate and schema inspect are pinned in
internal/cli/atlas/compat_overstrict_test.go. The same focused file also pins all three
orders of the prefix insertion: the default refuses, --exec-order non-linear applies and remains idempotent, and --exec-order linear-skip
leaves the insertion unapplied and stays that way on a repeat run. The last of
those is the one that keeps the entry honest — it is the claim that the pinned
binary’s own outcome is still reachable, so it is guarded rather than asserted.
The project-root boundary is pinned through the real ptah-compat process in
integration/atlas_project_migration_dir_confinement_e2e_test.go and its Unix
symbolic-link companion. The tests prove both outside spellings and an escaping
symbolic link fail without artifacts, relative and absolute inside paths and a
linked project root succeed, and an explicit absolute CLI --dir remains
reachable.
Every case above is SQLite-measured; the two noted as also measured on
PostgreSQL 17.10 were re-run against a live server. The rest carry the
SQLite-only caveat that
stokaro/ptah#1241 declares.
The entries below this section come from other issues. Each names its own measurement conditions, its own engine, and the test or tracking issue that holds it.
sql() inside check.expr and index.where
Section titled “sql() inside check.expr and index.where”Type. Deliberate divergence, in the direction of accepting more
Current boundary. Ptah reduces a sql() call to the SQL it carries
everywhere an attribute is read as text, including check.expr and
index.where. The pinned community binary refuses the same two with
incorrect type raw.
Why it stays. sql() exists so a schema file can carry an expression the
HCL grammar has no spelling for, and a CHECK body is the clearest case of one.
Refusing it in the two attributes that most need it would make the function
useless where it is most useful, to match a refusal that costs the operator a
capability rather than protecting them from anything. Nothing a document writes
this way renders differently: the call reduces to its argument text, which is
what an unquoted expression would have been.
The reduction is not optional. It landed because the fallback below it hands an
attribute’s SOURCE TEXT to the renderer, which is how CHECK (sql("n > 0"))
reached a plan verbatim.
Revision row for a migration whose body failed
Section titled “Revision row for a migration whose body failed”Type. Compatibility behavior with a native safety difference
Current boundary. When a migration body fails inside a transaction and
rollback succeeds, the pinned community binary writes no revision row.
ptah-compat reaches the same end state and retries the whole file on the next
apply. Native ptah migrations up keeps a durable failed row for status and
repair workflows.
Measured across the effective transaction-mode matrix:
effective file transaction binary 0 rows ptah-compat 0 rows native 1 roweffective all transaction binary 0 rows ptah-compat 0 rows native 1 roweffective no transaction binary 1 row ptah-compat 1 row native 1 rowThe compatibility cleanup is fail-closed. It removes a zero-progress row only
after Rollback returns success. A rollback error, commit error, unknown
statement outcome, or any committed statement keeps the row. Those states
still require explicit recovery, so parity does not erase evidence when the
database outcome is uncertain.
Evidence. stokaro/ptah#1196,
stokaro/ptah#1333
Failed rollback state
Section titled “Failed rollback state”Type. Deliberate divergence, in the direction of recording more
Current boundary. ptah-compat migrate down retains the Atlas
revision-table schema and does not reproduce the hidden failed-down state.
It marks rollback direction with the existing operator_version field and
makes a partial rollback recoverable through the existing progress and error
fields. A successful down still deletes the row. An Atlas reader can inspect
the same table, but may report a Ptah-recorded failed rollback differently from
one Atlas itself hid.
Native ptah migrations down records that state in both revision-table
formats. The row is marked failed with error=<message>, direction=down, and
applied set to the number of down statements that completed — 0 when the
first one fails or the dialect rolled the body back. Status therefore reports
the dirty state, repair has a row to act on, and a later up refuses to stack
work on the unfinished rollback.
Repair follows the recorded direction. --resume-from runs the remaining
down statements and removes the revision once the rollback finishes, and a
rollback that already committed a statement is refused rather than recorded
applied unless --force says the schema was restored. See
Roll back migrations.
The pinned community binary registers migrate down as a community-abort stub,
so the capability is unreachable there. Where the verb does run, a failed down
is not recorded: measured, after a down whose second statement fails, the body
is rolled back, the revision row still reads applied=2, total=2, error='',
the status report names the version as applied, and a retry after repairing the
down file succeeds and deletes the row.
Evidence. stokaro/ptah#957
Dirty retry verifies committed statements
Section titled “Dirty retry verifies committed statements”Type. Deliberate safety divergence
Current boundary. The community binary resumes a dirty non-transactional
revision from applied + 1 by statement index. Ptah first proves that every
statement it will skip has unchanged source text. Ptah-format rows store a
partial:h1: checksum for the committed prefix; Atlas-format rows use the
existing partial_hashes column. A changed prefix, malformed metadata, or
contradictory hash count is refused, as are negative progress counters,
applied > total, and a native state=applied row whose counters are
incomplete. Invalid metadata is rejected by revision listing, status, version,
and apply operations rather than being hidden as a clean row. A row carrying no
prefix metadata at all resumes only while its full-file hash still matches.
Editing only the unapplied suffix remains supported. If that retry changes from
none to file or all and its transaction rolls back, Ptah retains the
committed applied floor rather than making a later run replay SQL. Process
exit, context cancellation, or deadline while an autocommit statement is in
flight preserves the unknown-outcome marker.
This is stricter than the community binary in the safe direction: uncertain recovery exits non-zero instead of skipping SQL on the strength of a stale integer offset.
Recorded revision error text on a failed migration
Section titled “Recorded revision error text on a failed migration”Type. Driver difference, not a behavior one
Current boundary. The Atlas revision table’s error column records the
database’s own message on both sides, but the two spell the same condition
differently because they use different SQLite drivers. On the same failing
migration:
pinned community binary v1.3.0 no such table: missing_tableptah-compat SQL logic error: no such table: missing_table (1)The column carries the error the database answered with and nothing else — no
Ptah-authored prefix, and no repetition of the statement, which the adjacent
error_stmt column already holds in full. Where Ptah rewrote the database’s
message, the column records the rewritten text: a role password the PostgreSQL
writer took out of the server’s message is recorded as [secret], and a
provider’s failure is recorded with the outcome and reason the provider
reported. error_stmt matches byte for byte, terminating semicolon included.
A statement carrying bytes that are not valid UTF-8 is the exception: those
bytes are recorded as \xFF escapes, because the revision table’s text
columns hold UTF-8 and the MySQL family refuses anything else.
What is left is modernc.org/sqlite’s wording. Closing it would mean rewriting
driver messages per driver and per dialect to match a different driver’s
phrasing, which trades a cosmetic difference for a table of string edits that
goes stale silently. The native revision format is unaffected either way: this
applies only where the revision table is Atlas-shaped, and Ptah’s own surface
keeps the context it adds.
Tracking. stokaro/ptah#1196
Pre-migration checks in a dry run
Section titled “Pre-migration checks in a dry run”Type. Deliberate divergence
Current boundary. The community binary implements no check semantics, so it
flattens the archive and runs checks.sql as an ordinary migration statement;
in a dry run it executes no SQL at all and exits 0 for every checked
directory.
ptah-compat exits 1 where the guard’s verdict is knowable and negative:
- an assertion that is malformed or is not a read-only
SELECT, decidable from the text alone; - a failing assertion on the first migration executed in the run, decidable against the live database and confirmed by the real apply failing the same way;
- a checked directory under
--tx-mode all, which the real apply refuses outright.
Matching the community binary on those inputs would make the preview report success for a run that cannot succeed.
A failure that is an artifact of the preview rather than a finding — a later
migration’s guard asking about state the dry run refused to create — is not one
of them. ptah-compat exits 0 there, which both matches the community binary
and matches what applying the directory does. See
Checks in a dry run.
Tracking. stokaro/ptah#661
atlas.hcl file() confinement
Section titled “atlas.hcl file() confinement”Type. Deliberate divergence
Current boundary. ptah-compat reads file() and fileset() inside an
atlas.hcl only from the directory holding that atlas.hcl. Three shapes are
refused that the pinned community binary reads: an absolute path, a
parent-traversal path, and a plain relative name that resolves out of the
directory through a symbolic link. The refusal names which of the three applies
and points at getenv() for passing a value in from outside.
Measured on the pinned v1.3.0 build: file("/etc/passwd") and
file("../../../../etc/passwd") in an atlas.hcl both exit 0 with the file
read, and the contents reach an observable place — a database URL, an error
message on standard error.
The reason is that an atlas.hcl is usually repository-controlled and file()
is evaluated before anything is applied. Without confinement, a config file
arriving in a pull request can read any file the process can and place the
contents somewhere a reader of the output can see. That is a different class of
cost from the footguns the drop-in rule was written for. The exit code is 1
either way for a configuration that works, so nothing a project already runs
changes; the refusal names its reason.
Both halves are measured rather than remembered. The Ptah half is pinned by
TestOraclePlacesOutsideFileContentsWhereTheCallerCanSeeThem in
config/projectconfig; the community half is pinned by four ce-gating
scenarios in the conformance repository, so the day a community build starts
confining file() the gate goes red and this divergence can be retired.
Tracking. stokaro/ptah#1042
A migration that would be recorded over an invalid index
Section titled “A migration that would be recorded over an invalid index”Type. Deliberate divergence
Current boundary. On PostgreSQL, ptah-compat migrate apply refuses a
migration while an index that migration creates is reported unusable by
pg_index (indisvalid or indisready false). The pinned community binary
applies it and records it.
Measured on PostgreSQL 17.10, identical fixture on both: a members table whose
duplicate rows made an earlier CREATE UNIQUE INDEX CONCURRENTLY fail, the
duplicates then removed, and one migration carrying -- atlas:txmode none and
the same CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS statement.
| pinned community binary v1.3.0 | ptah-compat |
|
|---|---|---|
migrate apply --allow-dirty |
exit 0, -- ok, 1 statement |
exit 1, names the index and REINDEX |
pg_index afterwards |
indisvalid=f, indisready=f |
unchanged, nothing written |
| revision row afterwards | 20260808000001 applied 1/1, no error |
no row |
duplicate INSERT afterwards |
accepted, 2 rows share the email | n/a |
after REINDEX INDEX CONCURRENTLY |
n/a | exit 0, indisvalid=t, row recorded, duplicate rejected |
The leftover keeps the name, so IF NOT EXISTS skips it and the statement
reports success over an index that enforces nothing. Recording that as applied
means the tooling reports a constraint the database does not have, and nothing
will look again. Ptah also rejects another index or non-index relation that owns
the schema-level name. It resolves an unqualified drop and target through the
active search_path, permits cleanup only when that exact drop will run first
in this attempt, and positively rechecks the active transaction or connection
before recording the revision. A drop skipped by dirty-resume is not cleanup.
The divergence is stricter, not looser: ptah-compat exits 1 where the binary
exits 0, never the reverse, so no invocation the binary refuses succeeds here.
Tracking. stokaro/ptah#1101
schema inspect --include
Section titled “schema inspect --include”Type. Deliberate divergence
Current boundary. ptah-compat schema inspect --include positively selects
the top-level resources inspection keeps, through the same engine as
schema apply and schema diff: schema universe, then include selection, then
exclusion. The pinned community binary does not register the flag at all —
schema inspect -u sqlite://app.db --include users exits 1 with
Error: unknown flag: --include. Atlas registers it, and Ptah’s behavior
diverges from it in two measured ways, both deliberate:
| Input | Atlas | Ptah |
|---|---|---|
--include 't1' |
t1 with its columns, plus schema "main" |
same selection |
--include '*.t1' |
pattern is read at child depth: t1 rendered without its columns and t2 rendered as an empty shell, exit 0 |
*.t1 is the wildcard spelling of the qualified name main.t1, so t1 is rendered whole and t2 is dropped |
--include 'main.t1.*' |
Error: too many parts in pattern: ["main" "main" "t1" "*"], exit 1 |
rejected before any database is contacted: child resources ride along with their parent and cannot be selected on their own |
Ptah has no child-level include selection in either spelling, so it keeps whole
objects instead of emitting partial ones. It also refuses a selection that drops
a dependency of a selected object, where Atlas renders the reference anyway —
its *.t1 output keeps primary_key { columns = [column.id] } on a table whose
id column the same output omits. The Atlas-side rows are the recorded
transcripts, so behavior beyond those inputs is not established here.
There is no atlas.hcl spelling of this selector. Atlas documents exclude but
no include attribute on the env block; the community binary accepts
include = [...] there only because it accepts any unknown env attribute. A run
with not_a_real = [...] is likewise accepted and prints the full schema. Ptah
accepts env.include under the same unknown-name rule, leaves it without
effect, and writes a location-aware warning to standard error.
Tracking. stokaro/ptah#933
Exclude field selectors
Section titled “Exclude field selectors”Type. Deliberate divergence
Current boundary. A field selector is the .field suffix behind a
[type=...] selector: --exclude '*[type=table].comment' asks for the comment
of every table to be dropped while the tables themselves stay. The pinned Atlas
community binary accepts every such suffix and honors none of them. Measured on
PostgreSQL 16 with two commented tables across two schemas, all three of
--exclude '*[type=table].comment'--exclude 'public.*[type=table].comment'--exclude '*[type=table].*'are exit 0 there with output byte-identical to the same command without the
flag, comments included.
ptah-compat honors the ones it can carry out — [type=extension].version,
.comment on table, view and materialized_view, and .* for all of them
— and refuses the rest by name before a database is contacted. So the first and
third of those commands are exit 0 with the tables rendered and their comments
gone, and a suffix such as .charset is exit 1 naming the fields that would
have worked.
The reason not to copy accept-and-ignore is the one recorded for file() above:
an --exclude selector is a scoping instruction, and the reason to write one is
usually that the object must not be touched. Accepting one and silently not
carrying it out defeats that intent with no diagnostic, and on schema apply
and schema diff the same shape of miss reaches a DROP. Both directions here
are safe under the drop-in rule: honoring a selector subtracts more from a plan
rather than less, and refusing one exits 1 where that binary exits 0, never
the reverse.
The second of those commands is decided by the pattern-depth rule rather than
the field rule, so its exit status follows the URL. On a schema-bound URL both
binaries refuse it — the schema slot is already filled by the connection. That
binary quotes the prefixed pattern,
too many parts in pattern: "public.public.*[type=table].comment"; Ptah quotes
the one that was typed. On a URL that names no schema the pattern is
realm-relative, public fills the schema slot itself, and both binaries accept
it. Measured on both URLs against the same PostgreSQL 17 database.
Tracking. stokaro/ptah#933
An exclude selector that matches nothing
Section titled “An exclude selector that matches nothing”Type. Deliberate divergence
Current boundary. A selector that matches no object protects nothing, and
reads exactly like one that worked. The pinned community binary exits
0 and prints nothing for such a selector, whether --exclude or an atlas.hcl
env’s exclude list carries it. ptah-compat reports it. schema inspect and
schema diff keep their exit status and write a warning on stderr. schema apply refuses the run, because a selector that named nothing leaves the plan
free to change the object it was written to keep out. migrate down --plan,
which the community binary does not have, refuses for the same reason;
PTAH_ATLAS_ALLOW_UNMATCHED_EXCLUDE=1 turns either refusal back into a warning.
Each line names where the selector came from, since the command line may not
carry it. Measured on SQLite with an atlas.hcl env holding
exclude = ["nosuch_object"]:
| invocation | pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
schema inspect --env local |
exit 0, empty stderr |
exit 0, Warning: the exclude selection from atlas.hcl matched no objects: "nosuch_object". |
schema apply --env local --dry-run |
exit 0, plan printed |
exit 1, Error: the exclude selection from atlas.hcl matched no objects: "nosuch_object"; schema apply refuses a selection that protects nothing, … |
schema inspect --env local --exclude other_object |
exit 0, empty stderr |
exit 0, Warning: the --exclude selection matched no objects: "other_object". |
A project file named with --config file://./atlas.hcl is named as --config
spells it, ./atlas.hcl. An --exclude flag replaces the env’s list, so the
last row reports the flag.
Tracking. stokaro/ptah#933
Leading schema type selector
Section titled “Leading schema type selector”Type. Deliberate divergence
Current boundary. --exclude '*[type=schema].*[type=table]' means every
table inside every schema on every Ptah schema source. The leading schema glob
may be narrowed, as in app[type=schema].*[type=table].
The pinned community binary gives source-dependent answers. On a live
PostgreSQL database containing tables and enums in public and app, the
selector removes both tables and keeps both enums. On a SQLite file diff between
one table and the same schema plus a second table, it exits 0 but leaves the
second table’s CREATE TABLE plan unchanged. Removing the selector from that
SQLite run produces byte-identical output; *[type=table] is the control that
does remove the plan.
Ptah keeps the literal PostgreSQL answer on both source kinds. Making the selector a no-op only for a file diff would make one accepted scoping instruction mean two different things depending on its input. It would also report success while leaving exactly the table the selector names in the migration plan. This is a defect Ptah does not copy; the complete compatibility surface keeps the coherent behavior rather than narrowing it to this community-binary result.
The integration contour pins the file-diff result in
TestAtlasCompatLeadingSchemaTypeSelectorE2E. The filter tests separately pin
the schema glob, the final resource type, and the surviving non-table objects.
Tracking. stokaro/ptah#933
A constraint an exclude selector names
Section titled “A constraint an exclude selector names”Type. Divergence: a defect not copied
Current boundary. An exclude selector names a constraint through its
table, as table.constraint or schema.table.constraint. The pinned community
binary keeps a constraint only under the type it names it by: a
UNIQUE or EXCLUDE constraint under [type=index], and a CHECK constraint
under [type=check]. Under every other selector that names the constraint, it
accepts the selector, exits 0 and drops the constraint. ptah-compat keeps
the constraint. The index the server enforces a primary key, UNIQUE or
EXCLUDE constraint with leaves the comparison with the constraint, so the plan
holds no DROP INDEX the server refuses with SQLSTATE 2BP01. The key and
unique flags a read derives for the constraint’s column leave with it too, so
native schema compare reports no difference on the column.
Measured on 2026-11-18 with schema apply --dry-run on PostgreSQL 18, on a URL
that names no schema. The table kinds holds the key kinds_pkey, the unique
constraint kinds_code_key and the check code_len, and the desired schema
declares only the key, or nothing for the kinds_pkey row. The tables rooms
and desks each hold an EXCLUDE constraint, room_slot and desk_slot,
and the desired schema declares neither.
--exclude |
Binary | ptah-compat |
|---|---|---|
public.kinds.kinds_code_key[type=index] |
keeps kinds_code_key |
keeps it |
public.kinds.code_len[type=check] |
keeps code_len |
keeps it |
public.kinds.kinds_code_key[type=constraint] |
drops kinds_code_key |
keeps it and its index |
public.kinds.code_len[type=constraint] |
drops code_len |
keeps it |
public.kinds.kinds_pkey, untyped or with [type=index] or [type=constraint] |
drops kinds_pkey |
keeps it and its index |
public.kinds.*[type=index] |
keeps kinds_code_key and drops kinds_pkey |
keeps both |
kinds.kinds_code_key |
drops kinds_code_key |
keeps it |
*[type=constraint], *[type=check] or *[type=index] |
drops every constraint the desired schema leaves out | keeps every constraint the type names |
public.rooms.room_slot[type=constraint] |
drops room_slot |
keeps it and its index |
rooms.room_slot |
drops room_slot |
keeps it |
Ptah reads these selectors more widely than the binary, and each wider reading subtracts from the plan:
[type=constraint]names every constraint, as PostgreSQL records each one inpg_constraint, and[type=index]also names a primary key, whose index carries its name.- On a URL that names no schema, the binary reads
*in*[type=constraint]as the schema slot, so the selector names no constraint. Ptah reads a wildcard selector of a child type as naming that type in every table. - On the same URL, the binary reads
kinds.kinds_code_keyandrooms.room_slotasschema.object, so neither names a constraint. Ptah also reads a two-part pattern astable.constraintin the connection’s schema.
A selector is written to keep an object out of the plan, and each of these rows
on the binary reports success while dropping the object the selector names.
The drop-in rule allows the difference in this direction: the plan holds fewer
statements, never more, and nothing the binary refuses succeeds here.
PTAH_ATLAS_STRICT_COMPAT=1 keeps the same answers. Strict mode refuses a
capability the binary lacks; it does not reproduce a defect.
A type that names none of the constraint’s types matches nothing:
public.rooms.room_slot[type=check] and public.kinds.kinds_code_key[type=unique]
are accepted by the binary, which then drops the constraint, and refused by
schema apply here; see
An exclude selector that matches nothing.
A primary key declared without a name is named by the server’s primary key on
the same table, whatever the server calls it. With kinds holding
CONSTRAINT pk_kinds PRIMARY KEY (id) and a desired schema declaring
id int NOT NULL PRIMARY KEY, public.kinds.pk_kinds keeps the key on both
binaries. public.kinds.kinds_pkey, the name PostgreSQL gives a new key, names
nothing: the binary plans nothing, and schema apply here refuses the selector
as matching nothing. A table renamed from kinds to types that kept
kinds_pkey answers the same way to public.types.kinds_pkey and
public.types.types_pkey.
A foreign key on MySQL and MariaDB stands on an index, and the server builds
one when no index covers the key’s columns. The binary excludes the key under
[type=fk] and keeps the index in the plan: DROP INDEX, which MySQL 26.10 and
MariaDB 12.3 refuse with ERROR 1553 while the key stands, so the apply fails.
Ptah names the key under [type=fk], [type=foreign_key] and
[type=foreign-key], and leaves the index the server built out with it, so the
plan is synced. The binary keeps a foreign key only under [type=fk]. Ptah
keeps it under all three spellings, deliberately, since a selector is written
to keep what it names.
An index the author declared under such a key stays in the plan on both
binaries. The binary plans DROP INDEX kids_parent_idx alone, and the server
refuses it with ERROR 1553 after the statements before it ran: measured on
MySQL 8.4, a plan that also dropped the column alpha.x dropped it, then
failed. ptah-compat adds an index for the key in the statement that
drops the declared one, under the name the server gives the key’s index, with a
comment above it. The next run plans nothing, on MySQL 8.4 and 26.10 and
MariaDB 11.8 and 12.3.
On SQLite, a plan changes most of a table by writing a new one from the
declaration and copying the rows, and the declaration holds nothing a selector
keeps out of scope. The pinned binary writes the new table without those parts.
ptah-compat carries each one into the new table from its live definition.
With the table kinds(id, name, extra) holding values in extra, the index
idx_name and the trigger trg_name, and a desired schema that declares id
and name, the selectors answer as follows:
kinds.extra[type=column]: the binary applies and the values inextraare gone;ptah-compatkeeps the column, its default and its values.kinds.idx_name[type=index]andkinds.trg_name[type=trigger]: the binary applies without the index or the trigger;ptah-compatkeeps it.
With the table holding a column UNIQUE, the check code_len and the index
kinds_code, and a desired schema that declares none of them:
kinds.code_len[type=check]: the binary plansDROP INDEX kinds_codetwice, and itsschema applyfails on the second statement withno such index: kinds_code.ptah-compatwrites the new table with theCHECKand without theUNIQUE.*[type=constraint]: the binary writes a new table without theUNIQUEand theCHECK. Every constraint stays out of scope onptah-compat, so nothing of the table changes.*[type=index]: the binary writes a new table without theUNIQUEand drops the index.ptah-compatkeeps the index and theUNIQUE, which SQLite enforces with an index.kinds.*leaves out every column of the table and its constraints with them, and both binaries plan nothing.
A column with AUTOINCREMENT keeps the keyword on its own PRIMARY KEY
clause where the declaration holds no primary key, and keeps its high-water mark;
see The AUTOINCREMENT mark of a rebuilt SQLite table.
A view, or a trigger of another table, that names the rebuilt table stays as it
is, because the plan renames the new table with legacy_alter_table on. The
plan cannot read the value the connection holds, so it sets the pragma off after
the rename, and ptah-compat puts back the value it found when the transaction
ends.
Where a part cannot be carried as it stands, ptah-compat refuses the plan and
names the part. A part is refused when it reads a column the new table drops: a
trigger, a CHECK, a generated column, a view, a constraint over the column,
and an index whose columns, key expression or WHERE clause read it. A primary
key beside the one the declaration holds is refused too, and so is a column with
AUTOINCREMENT beside a declared primary key. With a trigger that reads extra
and a selector that keeps only the trigger, the binary applies and leaves the
trigger out; ptah-compat stops before any change.
Evidence. integration/constraint_selector_e2e_test.go,
integration/exclusion_selector_e2e_test.go,
integration/foreign_key_selector_e2e_test.go,
integration/key_selector_names_e2e_test.go,
integration/sqlite_rebuild_carry_e2e_test.go,
internal/atlasfilter/constraint_selector_test.go,
internal/atlasfilter/foreign_key_backing_test.go,
internal/planner/dialects/sqlite/dependents_test.go,
internal/planner/dialects/sqlite/out_of_scope_test.go
The AUTOINCREMENT mark of a rebuilt SQLite table
Section titled “The AUTOINCREMENT mark of a rebuilt SQLite table”Type. Divergence: a defect not copied
Current boundary. SQLite holds the high-water mark of an AUTOINCREMENT
key in sqlite_sequence, so a key a deleted row held is not handed out again.
A rebuild copies the rows into a new table, drops the old table, which deletes
its mark, and renames the new one, whose mark is the largest key the copy wrote.
The binary writes the rebuild in those four statements, and a deleted key at the
top comes back. ptah-compat writes
INSERT INTO sqlite_sequence (name, seq) SELECT 'new_kinds', seq FROM sqlite_sequence WHERE name = 'kinds';
between the CREATE TABLE and the copy, under the comment
-- Keep the AUTOINCREMENT high-water mark of "kinds", wherever the live table
and the new one both have AUTOINCREMENT. A key a selector keeps out of scope
keeps its mark the same way.
Measured on 2026-11-19 on SQLite with schema apply and migrate apply. The
table kinds(id INTEGER PRIMARY KEY AUTOINCREMENT, name, extra) holds rows 1 to
3, row 3 is deleted, and the desired schema drops extra.
| Binary | ptah-compat |
|
|---|---|---|
sqlite_sequence row of kinds after the rebuild |
3 before, 2 after |
3 before, 3 after |
| key of the next row | 3, the key the deleted row held |
4 |
migrate lint summary over the file migrate diff writes |
1 schema change |
4 schema changes |
migrate lint summary over the file ptah-compat writes |
4 schema changes |
4 schema changes |
The binary counts a rebuild as one change only where exactly one statement
stands between the CREATE TABLE and the DROP TABLE, and both binaries count
the same file the same way. The statement cannot go before the CREATE TABLE:
sqlite_sequence exists only once a table with AUTOINCREMENT does, and the dev
database of a run that keeps the key out of scope holds none. It cannot go after
the DROP TABLE either, which deletes the mark it reads.
Evidence. integration/sqlite_rebuild_carry_e2e_test.go
(TestSQLiteRebuildKeepsTheAutoincrementMarkE2E),
internal/planner/dialects/sqlite/sequence_test.go,
internal/planner/sqliterebuild/sqliterebuild_test.go,
internal/lintkit/rebuild_test.go
A SQLite file that sets legacy_alter_table
Section titled “A SQLite file that sets legacy_alter_table”Type. Divergence: a defect not copied
Current boundary. PRAGMA legacy_alter_table belongs to the connection and
outlives the transaction that set it. With it off, a table rename rewrites the
views and triggers that name the table; with it on, it leaves them as they are.
The binary runs a directory’s files on one connection, so a file that sets the
pragma decides how the renames of every later file treat views. migrate apply
on ptah-compat reads the value before the first statement that names the
pragma and puts it back after the file, in every --tx-mode, so each file runs
under the setting the connection held before the run.
Measured on 2026-11-19 on a SQLite file with migrate apply. The first file
holds PRAGMA legacy_alter_table = on;, and the second creates t, creates the
view v as SELECT a FROM t, and renames t to t2.
| Binary | ptah-compat |
|
|---|---|---|
| exit status | 0 |
0 |
text of v afterwards |
CREATE VIEW v AS SELECT a FROM t, a view of a table that no longer exists |
CREATE VIEW v AS SELECT a FROM "t2" |
A connection that starts with the pragma on, from ?_pragma=legacy_alter_table(1)
in the URL, keeps it on for every file, so the second file leaves v as written.
Evidence. integration/sqlite_rename_setting_e2e_test.go,
migration/migrator/rename_setting_test.go
One version spelled two ways
Section titled “One version spelled two ways”Type. Deliberate divergence
Current boundary. ptah-compat refuses an Atlas directory that spells one
version number two ways, such as 1_a.sql beside 001_b.sql. The pinned
community binary applies both files as two revisions.
Measured on PostgreSQL 18 on 2026-09-24, with the directory hashed by that binary:
| pinned community binary v1.3.0 | ptah-compat |
|
|---|---|---|
migrate apply |
exit 0, applies 001 and then 1 |
exit 1, names both files and both spellings |
| revision rows afterwards | 001, 1 |
none, and no revision table |
Both binaries record a version as the file name spells it, so 001_b.sql is
revision 001 on each. The order is where they part. That binary orders files
by name, and Ptah runs migrations in numeric order, where both files are 1.
Nothing in the directory says which of the two should run first, so the refusal
names the files instead of choosing. Renaming one of them to a number of its
own gives a directory both binaries apply the same way.
TestCompatMigrateApply_OneVersionSpelledTwoWaysRefuses pins the refusal and
that nothing reaches the database, and the migrator’s own tests pin the same
refusal for a pair of up and down files spelled apart.
Tracking. stokaro/ptah#3532
Two files for one version
Section titled “Two files for one version”Type. Deliberate divergence
Current boundary. ptah-compat refuses an Atlas directory where two files
carry the same version, such as 20260101000000_a.sql beside
20260101000000_b.sql, and names both files. The pinned community binary runs
the first file and then crashes.
Measured on SQLite on 2026-11-19 with the community binary v1.3.0 and v1.4.0, with the directory hashed by that binary:
| community binary v1.3.0 and v1.4.0 | ptah-compat |
|
|---|---|---|
migrate apply |
exit 2, panic: runtime error: index out of range [0] with length 0 on stderr, after it ran 20260101000000_a.sql |
exit 1, Error: error registering migrations: duplicate Atlas up migration for version 20260101000000: 20260101000000_a.sql and 20260101000000_b.sql |
| revision rows afterwards | 20260101000000, description a |
none, and no revision table |
a second migrate apply |
exit 0, No migration files to execute |
exit 1, the same refusal |
migrate status afterwards |
exit 0, Migration Status: OK, no pending files |
exit 1, the same refusal |
On that binary the second file never runs, and nothing says so: the revision row
covers the version, so the next apply has nothing to do and migrate status
reports OK. Nothing in the directory says which file the author meant, so
ptah-compat refuses instead of choosing, as it does for
one version spelled two ways. migrate hash
and migrate validate without --dev-url accept the directory on both
binaries, because they read the files’ checksums and run nothing. Giving one
of the files a version of its own gives a directory both binaries apply the
same way.
TestCompatMigrateApply_DuplicateVersionRefuses pins the refusal and that
nothing reaches the database. TestAtlasDuplicateVersion_FailurePath pins the
migrator’s refusal for two up files, two down files, and a down file beside a
txtar down section.
Tracking. stokaro/ptah#6324
A revision spelled apart from its file
Section titled “A revision spelled apart from its file”Type. Deliberate divergence
Current boundary. ptah-compat refuses a history whose revision row spells
a migration file’s version another way, such as the row 1 for 001_a.sql,
and prints the statements that respell the rows. The pinned community binary
reads the same history by comparing versions as text.
Measured on PostgreSQL 18 on 2026-09-25. The revision rows were 1 and 2, and
the directory spelled 001_a.sql, 002_b.sql and a new 003_c.sql:
| pinned community binary v1.3.0 | ptah-compat |
|
|---|---|---|
migrate status |
exit 0, Migration Status: OK, current version 2, no pending files |
exit 1, names the rows and prints one UPDATE per row |
migrate apply |
exit 0, No migration files to execute |
exit 1, the same refusal |
003_c.sql afterwards |
never ran | never ran |
That binary sorts 003 below the recorded 2 as text, so it reads the new file
as applied and never runs it. Ptah refuses instead, because the readers of this
history disagree about what ran: to a reader that compares numbers, the row 1
is the file 001_a.sql, and to one that compares text it is not. A write that
addresses the row by the file’s spelling misses it, so a rollback would run the
down migration and leave the row behind. Both binaries record a version as the
file name spells it, so neither writes this history; it comes from a table
written some other way, such as by hand. Running the printed statements gives
every row its file’s spelling, and both binaries then agree.
TestCompatMigrateApply_RevisionSpelledApartFromItsFileRefuses pins the refusal
and that 003_c.sql does not run. The migrator’s tests pin the same refusal for
status, apply, rollback, checksum verification and migrate set, and live tests
run the printed statements on PostgreSQL, MySQL and ClickHouse.
Tracking. stokaro/ptah#3550
A Liquibase rollback written by migrate diff
Section titled “A Liquibase rollback written by migrate diff”Type. Deliberate divergence
Current boundary. migrate diff into the Liquibase layout
(--dir 'file://migrations?format=liquibase') writes each line of the
changeset’s rollback as --rollback <SQL>, with one blank after the keyword.
The pinned community binary writes --rollback: <SQL>. Liquibase 5.0.4
reads a rollback line only with that blank, so it reads a line with the colon
as a comment in the changeset’s SQL, and the changeset has no rollback.
Measured on SQLite on 2026-09-26, with a diff that creates widgets into an
empty directory, and the changeset each binary wrote run by Liquibase 5.0.4:
| pinned community binary v1.3.0 | ptah-compat |
|
|---|---|---|
| rollback line written | --rollback: DROP TABLE |
--rollback DROP TABLE IF EXISTS |
Liquibase update |
creates widgets |
creates widgets |
Liquibase rollback-count --count=1 |
exit 1: no automatic rollback for raw SQL; widgets stays |
exit 0; widgets is dropped |
A rollback that spans several lines, such as the CREATE TABLE that undoes a
dropped table, is written as one --rollback line per line of SQL, and
Liquibase joins them with a line break after each. Liquibase rolled a dropped
widgets back to the table with both of its columns.
PTAH_ATLAS_STRICT_COMPAT=1 does not change this. The layout migrate diff
writes is Ptah’s in both profiles – one changeset per migration and Ptah’s
renderer’s SQL, not the community binary’s – so the colon would buy no byte
parity, and it would lose the rollback the plan wrote.
TestCompatMigrateDiff_LiquibaseRollbackIsOneLiquibaseRuns pins the spelling
under both policies. TestComposeMigrationArtifacts_LiquibaseRollbackIsOneLiquibaseReads
reads the written changeset back through the reader that follows Liquibase’s
formatted-SQL parser, and TestLiquibaseDiffRollbackE2E_HappyPath imports two
written migrations and rolls both back.
Tracking. stokaro/ptah#3752
A dev database holding an object the reset drops
Section titled “A dev database holding an object the reset drops”Type. Deliberate divergence
Current boundary. ptah-compat refuses a dev database that holds anything
its reset would drop, not only a table. Each writer lists what its reset drops
through the query the reset runs, and the check reads that list:
- PostgreSQL, CockroachDB and YugabyteDB: a view, a materialized view,
a function, a procedure, an aggregate, a sequence, a type, a collation, on
PostgreSQL a large object, and a default privilege the reset would take
away: one set in a schema when the URL pins no
search_path, and on CockroachDB every default privilege, global ones included. - MySQL and MariaDB: a view, a procedure, a function, an event, a sequence, or a system-versioned table.
- SQLite: a view.
- SQL Server: a view, a procedure, a function, a sequence, a synonym, a type, an XML schema collection, or a user schema.
- ClickHouse: a view, a materialized view, or a dictionary.
- Oracle: a view, a sequence, a synonym, or a type.
The refusal names the object, in the shape the pinned binary uses for a table:
connected database is not clean: found view "v" in connected schema when a
PostgreSQL URL pins a search_path, found view "v" in schema "public" when it
does not, and found view "v" in schema "dev" on the other engines, which name
the database or the account. SQLite has one schema, so it prints
found view "v". Native ptah refuses the same databases. Objects an
installed extension owns are kept, and so is every PostgreSQL schema outside a
pinned search_path; neither refuses. So are the PostgreSQL and YugabyteDB
default privileges set in the schema a search_path pins, and the global
ones in either scope: each reset returns them to what they were when the run
took the dev database. An image that grants its roles through them, such as
Supabase’s, can be the dev database.
Measured on 2026-09-27 against PostgreSQL 18.6, with each object alone in the
dev database and migrate validate and schema apply run against it:
| Dev database | Pinned community binary v1.3.0 | ptah-compat without the refusal |
ptah-compat |
|---|---|---|---|
?search_path=public, a view, function, sequence, enum, domain, composite type or collation |
exit 0, the object kept |
exit 0, the object dropped |
exit 1, names the object, kept |
no search_path, the same objects |
exit 0, every object dropped but the enum |
exit 0, the object dropped |
exit 1, names the object, kept |
| a large object, either scope | exit 0, kept |
migrate validate exit 0, dropped |
exit 1, names it, kept |
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES, migrate validate |
exit 0, kept with a search_path, revoked without one |
exit 0, revoked |
exit 0, kept with a search_path; exit 1 without one, names it, kept |
ALTER DEFAULT PRIVILEGES FOR ROLE app_owner REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC, either scope, migrate validate |
exit 0, kept |
exit 0, returned to the built-in default |
exit 0, kept |
Measured the same day on the other engines, with the same verbs:
| Engine and object | Pinned community binary v1.3.0 | ptah-compat without the refusal |
ptah-compat |
|---|---|---|---|
| MySQL 26.7 and MariaDB 12.3: a view, procedure, function or event; on MariaDB a sequence or a system-versioned table | exit 0, kept |
exit 0, dropped |
exit 1, names it, kept |
| SQLite: a view | exit 0, dropped |
exit 0, dropped |
exit 1, names it, kept |
| SQL Server 2025: a view, procedure, function, sequence or synonym | unknown driver |
exit 0, dropped |
exit 1, names it, kept |
| SQL Server 2025: a type or an empty user schema | unknown driver |
migrate validate exit 0, dropped |
exit 1, names it, kept |
| ClickHouse 26.9: a view, or a materialized view with its rows | unknown driver |
exit 0, dropped |
exit 1, names it, kept |
| ClickHouse 26.9: a dictionary | unknown driver |
migrate validate exit 0, dropped |
exit 1, names it, kept |
No verb reaches the Oracle reset, because the dev lock refuses Oracle first. Its reset drops a view, a sequence, a synonym and a type and keeps a function, a procedure and a package; the check counts the first four.
The binary keeps most of those objects because it does not model them, so its
snapshot neither sees nor restores them. Keeping them in Ptah would mean hiding
them from every read of the dev database, since a replay and a rehearsal read
it back and compare it, and a migration’s CREATE ... IF NOT EXISTS would
then pass against the kept object instead of creating its own. Refusing loses
nothing and proves as much as before. Where the binary drops an object in
silence, as it does on SQLite and on PostgreSQL with no search_path, that is
the defect this refusal does not copy.
Default privileges are the exception, and are kept where the binary keeps
them. The comparison leaves alone a default whose grantor the desired schema
does not manage, so keeping one hides nothing from a read, and a migration
that sets the same default runs as it would on the target. Each reset returns
the kept ones to what they were when the run took the dev database. A default
the run set survives the binary’s cleanup, measured on 2026-10-03 with
migrate diff; Ptah’s reset takes it back
(stokaro/ptah#4034).
A PostgreSQL text search configuration or dictionary is not refused, because
the reset never drops it. The realm cleanup drops a schema with RESTRICT, so
the schema that holds one stays, and the failure names it in the server’s
words: failed to drop user schema "public" from PostgreSQL database realm (text search configuration keep_ts depends on schema public): .... The binary
keeps it with a search_path and drops it without one.
The divergence is stricter, not looser: ptah-compat exits 1 where the binary
exits 0, never the reverse.
Tracking. stokaro/ptah#3808,
stokaro/ptah#3851
A whole server cleaned without an opt-in
Section titled “A whole server cleaned without an opt-in”Type. Deliberate divergence
Current boundary. A MySQL or MariaDB URL that names no database is the
whole server, and ptah-compat schema clean against it would drop every user
database. It refuses that, dry run included, unless PTAH_ALLOW_SERVER_CLEAN=1
is set, and the refusal lists the databases in the form a dry run prints them:
Error: refusing to clean a whole MySQL or MariaDB server without PTAH_ALLOW_SERVER_CLEAN=1: the URL names no database, and the cleanup would drop every user database on the server:- DROP DATABASE `app`- DROP DATABASE `audit`Set PTAH_ALLOW_SERVER_CLEAN=1 to clean the server, or name a database in the URL to clean that database aloneWith the variable set, the confirmation and --dry-run work as on any other
URL. A URL that names a database is not affected, and neither is a server with
no user database. Native ptah db drop-all refuses the same way.
Measured on 2026-09-27 against MySQL 8.4.11 and MariaDB 11.8.9, a server holding two user databases:
| Run | Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
--auto-approve |
exit 0, both databases dropped |
exit 1, both listed, both kept |
--auto-approve, PTAH_ALLOW_SERVER_CLEAN=1 |
not read | exit 0, both databases dropped |
--dry-run |
exit 1, --dry-run is not supported by the community version |
exit 1 and the list; exit 0 and the plan with the variable |
| a table in one database with a foreign key into a database that sorts before it | exit 1, error 3730 when it reaches the referenced database |
with the variable, exit 0: the key is dropped first |
A server is often shared, and the scope is chosen by what the URL leaves out
rather than by anything the operator names. One confirmation, or
--auto-approve in a script, would drop databases nobody listed, and the
community binary offers no dry run to look first. The variable restores the
binary’s behavior, so strict mode keeps it.
The divergence is stricter, not looser: ptah-compat exits 1 where the binary
exits 0, never the reverse.
Tracking. stokaro/ptah#3789
A database outside a one-database URL
Section titled “A database outside a one-database URL”Type. Deliberate divergence
Current boundary. A MySQL, MariaDB or ClickHouse URL that names one database
limits schema apply and schema diff to it, and on the native surface ptah schema compare, ptah schema drift, ptah migrations generate and ptah migrations plan too. A document that declares another database, or puts a table,
view, routine, sequence or trigger in one, is refused by name before anything is
planned.
Measured on 2026-09-28 against MySQL 8.4.11, with the URL naming app:
| Document | Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
CREATE TABLE other.u (…); CREATE TABLE t (…) |
exit 1, Error 1049 (42000): Unknown database 'other' |
exit 1, table "other.u" is in database "other", … |
CREATE DATABASE other; CREATE TABLE other.u (…); CREATE TABLE t (…) |
exit 0, Schema is synced: other.u is dropped without a word |
exit 1, the document declares database "other", … |
an HCL document declaring schema "other" alone |
exit 1, mismatched HCL and database schemas: "app" <> "other" |
exit 1, the document declares database "other", … |
CREATE TABLE app.t (…), naming the URL’s own database |
exit 1, Error 1049 (42000): Unknown database 'app', run on the dev database |
exit 0, the table is in app |
The binary runs the document on the dev database, so what it accepts depends
on what that database can hold rather than on what the URL names. Without the
refusal, the plan creates other.u on the server, in a database the URL does
not name. The last row is the reverse: a name qualified with the URL’s own
database is that database’s, and the binary refuses it only because the dev
database has another name.
Tracking. stokaro/ptah#3928
A dev server that is the --to side, or beside one database
Section titled “A dev server that is the --to side, or beside one database”Type. Deliberate divergence
Current boundary. A --dev-url that names no MySQL or MariaDB database is a
whole dev server, which migrate diff, migrate lint and migrate validate
empty after the replay. migrate diff refuses two pairs before anything is
replayed:
- a dev server that is the server
--toreads, compared by the server’s UUID on MySQL and by its host name, port and data directory on MariaDB:--to database must differ from --dev-url because the dev database is reset during planning; - a
--tonaming one database beside a dev server:cannot diff a schema "app" with a database connection.
Measured on 2026-09-27 against MySQL 8.4.11 and MariaDB 11.8.9:
| Run | Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
--to and --dev-url the same server, holding no database |
exit 0, replays the directory there and empties it |
exit 1, nothing replayed |
| the same server holding a database | exit 1, found schema "r1" |
exit 1, the same refusal |
--to mysql://host/r1 beside a dev server |
exit 0, writes ALTER TABLE statements for r1 |
exit 1, nothing replayed |
A server that holds no database from the dev URL’s point of view can still hold what another account sees, and the cleanup would drop what the replay created there. Comparing the server’s identity costs one query. A database against a server compares two scopes as if they were one.
The divergence is stricter, not looser: ptah-compat exits 1 where the binary
exits 0, never the reverse.
Tracking. stokaro/ptah#3789
A realm beside one database on a dev server
Section titled “A realm beside one database on a dev server”Type. Deliberate divergence
Current boundary. Beside a dev server, schema diff refuses a URL naming
one database compared with an HCL document that declares more than one
database, in either order:
cannot use HCL with more than 1 schema when --from is limited to schema "app".
The sentence is the one the binary’s schema apply gives the same pair.
Measured on 2026-09-28 against MySQL 8.4.11. The server holds app, with a
table t carrying a column extra, and more, with a table keepme. The
realm file declares app and more:
| Run | Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
schema diff --from mysql://…/app --to file://realm.hcl --dev-url <dev server> |
exit 0, plans CREATE DATABASE more and ALTER TABLE app.t DROP COLUMN extra |
exit 1, the refusal |
| the binary’s plan, run against the server | ERROR 1007 (HY000): Can't create database 'more'; database exists |
not planned |
schema diff --from file://realm.hcl --to mysql://…/app --dev-url <dev server> |
exit 0, plans DROP DATABASE more, which holds keepme |
exit 1, the refusal |
schema apply -u mysql://…/app --to file://realm.hcl --dev-url <dev server> |
exit 1, cannot use HCL with more than 1 schema when url is limited to schema "app" |
exit 1, refused before anything is contacted |
A URL naming one database reads that database alone, so a plan that creates or
drops another database reaches a database that side never read. The binary’s
own schema apply refuses the pair, so its schema diff writes plans its
apply will not run. An HCL document declaring one database is compared with the
database, as the binary compares it. A SQL file or a migration directory beside
one database is refused by both, in the binary’s words.
The divergence is stricter, not looser: ptah-compat exits 1 where the binary
exits 0, never the reverse.
Tracking. stokaro/ptah#3885
A SQL file naming a database beside a dev database
Section titled “A SQL file naming a database beside a dev database”Type. Deliberate divergence
Current boundary. On MySQL and MariaDB a schema is a database. A --from
document that schema diff creates on a dev database, and a document that
schema inspect reads through one, may name its tables with a database. When
the document names one database, Ptah creates it inside the dev database under
the dev database’s own name, as the binary does for an HCL document. When it
names two, or switches to another database, it is refused before anything runs.
Measured on MySQL 8.4 and MariaDB 11.4, with the same results on both. The
target f3a holds t1, and the dev database f3dev is on the same server:
--from beside --to f3a |
Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
a SQL file creating f3a.t9 |
exit 0, plans CREATE TABLE t1 and CREATE TABLE t9, and leaves f3a.t9 in the target |
exit 0, plans CREATE TABLE t1 and DROP TABLE t9, the target untouched |
a SQL file creating f3a.t9 and other.t8 |
exit 0, and leaves f3a.t9 and other.t8 behind |
exit 1, the statement and the database it names, nothing created |
an HCL document declaring f3a alone |
exit 0, plans CREATE TABLE t1 and DROP TABLE t9 |
the same |
The binary runs a SQL file as written on the dev connection, so a table the
file names in the target database is created there, by a command that only
previews a change. Ptah does not copy that. The two-database refusal is
stricter, not looser: ptah-compat exits 1 where the binary exits 0.
A dev database beside a whole server
Section titled “A dev database beside a whole server”Type. Deliberate divergence
Current boundary. schema apply refuses a --dev-url naming one database
beside a target URL naming none, before the dev database is contacted. A plan
for a whole server creates and drops databases, and Ptah rehearses the plan
before it applies it. A rehearsal on one dev database would reach the other
databases of its server, so it needs a whole dev server, a --dev-url naming
no database. Where the binary refuses the pair, the sentence is the binary’s.
Measured on 2026-09-28 against MySQL 8.4.11 and MariaDB 11.8.9, with the same
results on both. The target server holds app; the dev URL names devdb:
--to |
Pinned community binary v1.3.0 | ptah-compat |
|---|---|---|
an HCL document declaring app and more |
exit 1, cannot use HCL with more than 1 schema when dev-url is limited to schema "devdb" |
exit 1, the same sentence |
an HCL document declaring app alone |
exit 0, plans ALTER TABLE app.t ADD COLUMN name |
exit 1, a dev database beside a whole server is refused |
a SQL file creating app and more |
exit 1, cannot diff a schema "devdb" with a database connection, and app and more left on the dev database’s server |
exit 1, the same sentence, the dev server untouched |
| a migration directory creating them | exit 1, the same, with the same databases left |
exit 1, the same sentence, the dev server untouched |
The binary replays SQL onto the server the dev database is on, creating
databases outside it, and leaves them there when it refuses. Ptah refuses
before it connects. The divergence is stricter, not looser: ptah-compat
exits 1 where the binary exits 0, never the reverse.
Tracking. stokaro/ptah#3885
A YDB database URL
Section titled “A YDB database URL”Type. Ptah extension
Current boundary. No Atlas edition has a YDB driver. The default profile
takes a ydb:// or ydbs:// URL on the schema, migrate and script verbs,
with no PTAH_* variable to turn it on, and serves it through the
YDB provider: the installed one, or the one the
manifest PTAH_PROVIDER_CONFIG names. The strict profile refuses it in the
binary’s words, from a flag, atlas.hcl or a data source the file connects to.
The binary answers schema inspect, schema apply, schema diff, schema clean, migrate apply, migrate status and migrate set on a YDB URL with
sql/sqlclient: unknown driver "ydb". See: https://atlasgo.io/url, naming
"ydbs" for a ydbs:// URL, and the strict profile answers with the same
sentence. Measured against local-ydb 26.2.1.14, every exit status read from an
unpiped invocation:
| URL | Binary | Strict |
|---|---|---|
--url ydb://... |
exit 1, unknown driver |
exit 1, the same sentence |
--url ydbs://... |
exit 1, unknown driver |
exit 1, the same sentence |
--dev-url ydb://... |
exit 1, unknown driver |
exit 1, the same sentence |
a data "sql" source |
exit 1, unknown driver |
exit 1, unknown driver |
The never-looser rule is about an invocation the binary refuses because the
user got something wrong. A YDB URL is a request for an engine the binary lacks,
and refusing it in the default profile would remove a capability Ptah has.
docker://ydb/... asks the YDB provider to start a local-ydb container for the
run in the default profile. The strict profile answers unsupported docker image "ydb", as the binary does.
Tracking. stokaro/ptah#4204
A golang-migrate file that runs its own transaction
Section titled “A golang-migrate file that runs its own transaction”Type. Divergence: a defect not copied
Current boundary. ptah-compat migrate apply runs a golang-migrate
directory the way golang-migrate runs it, which opens no transaction around a
file. A PostgreSQL file that opens and closes its own transaction runs as
golang-migrate’s default mode runs it, outside any transaction of the
migrator’s, with its revision row written after the file’s last statement. A
PostgreSQL file of one statement runs without one. The pinned community binary
wraps each file in a transaction of its own, so a file with its own
block nests in it, and its COMMIT ends the binary’s transaction early.
Measured on PostgreSQL 18, each directory applied to a fresh database:
second migration binary ptah-compatBEGIN; CREATE TABLE t1 (id int); applies, records 4 of 4, applies, records 4 of 4,INSERT INTO t1 VALUES (1); COMMIT; exits 1: unexpected exits 0 transaction status idleBEGIN; CREATE TABLE t2 (id int); COMMIT; t2 stays, records 3 of 4 t2 stays, records 3 of 4INSERT INTO missing_table VALUES (1); with the error, exits 1 with the error, exits 1CREATE INDEX CONCURRENTLY base_id_idx fails: cannot run inside a builds a valid index,ON base (id); transaction block, exits 1 records 1 of 1, exits 0Directories in every other layout keep the per-file transaction on both binaries; Transactions in a golang-migrate directory has the rules.
Evidence. stokaro/ptah#4962
A txmode none file that controls its own transaction
Section titled “A txmode none file that controls its own transaction”Type. Deliberate divergence
Current boundary. A migration that carries -- atlas:txmode none and holds
its own BEGIN and COMMIT is refused by ptah-compat migrate apply, and
ptah-compat migrate lint reports it as TX201. Without a transaction, Ptah
records the progress of each statement in the revision table. A BEGIN in the
file would put that record outside the file’s transaction, so the migrator
refuses any statement that controls transaction state, on every engine and in
the up and the down half. The pinned community binary runs the file as
written and lints it clean. The lint rule reads the same statements the
migrator refuses, so a directory that lints without a TX201 finding is not
one the migrator stops at for this reason.
Measured on 2026-11-14 over SQLite, with 1.sql holding
CREATE TABLE users (id int); and 2.sql holding the lines below, each exit
status read from an unpiped invocation:
-- atlas:txmode none
BEGIN;INSERT INTO users VALUES (1);COMMIT;| Run | Binary | ptah-compat |
|---|---|---|
migrate lint --dev-url 'sqlite://dev?mode=memory' --latest 1 |
1 version ok, no diagnostics, exit 0 |
L3 [TX201] as a warning, 1 version with warnings, exit 0 |
migrate apply --url sqlite://t.db |
applies both files, exit 0 |
refuses the run before it applies migration 1, with migration 2 cannot run up statement 1 without a transaction because "BEGIN" controls transaction state, and records no revision, exit 1 |
The same file without the directive runs inside the transaction each migrator
opens around a file. The binary’s lint is clean and its apply fails with
cannot start a transaction within a transaction after it applied the first
file; ptah-compat migrate apply refuses it before the first file, as
A file that controls the transaction it runs in
records, and a lint that replays it on a dev database fails the same way as the
apply.
The refusal is stricter than the binary on purpose. A file that runs half of its own transaction and then fails leaves the database and the revision table disagreeing about what was applied, which is the shape the rule exists to keep out. The way forward is to remove the transaction control, or to run the file with a runner that opens its own transactions, as A golang-migrate file that runs its own transaction describes.
Evidence. integration/migrate_lint_transaction_control_e2e_test.go,
stokaro/ptah#6004
A file its transaction would refuse
Section titled “A file its transaction would refuse”Type. Deliberate divergence
Current boundary. ptah-compat migrate apply reads every file of the run
before it applies the first. When a file holds a statement PostgreSQL refuses
inside the transaction the file runs in, such as a lone
CREATE INDEX CONCURRENTLY under the default --tx-mode file, the run is
refused: no file is applied and no revision row is written. A dry run is
refused the same way. The pinned community binary applies the files
before it, then sends the statement and exits 1 with PostgreSQL’s error. Its
dry run sends nothing and reports every file ok.
Measured on 2026-11-14 on PostgreSQL 18, with 1_base.sql holding
CREATE TABLE base (id int); and 2_idx.sql holding
CREATE INDEX CONCURRENTLY base_id_idx ON base (id);, each run on a fresh
database, each exit status read from an unpiped invocation:
| Run | Binary | ptah-compat |
|---|---|---|
migrate apply |
applies and records version 1, then fails version 2, exit 1 |
refuses the run, creates nothing and records no revision, exit 1 |
migrate apply --dry-run |
lists both versions as ok, exit 0 |
refuses the run, exit 1 |
The binary’s failure at version 2 is PostgreSQL’s answer to the statement:
pq: CREATE INDEX CONCURRENTLY cannot run inside a transaction block (25001)ptah-compat names the file, the line and the way out, before anything runs:
Error: error applying migrations: 2_idx.sql cannot run inside a transaction: line 1 CREATE or DROP INDEX CONCURRENTLY is refused inside a transaction block; mark the file `-- +ptah no_transaction`, or move the concurrent index into a migration of its ownSQL: CREATE INDEX CONCURRENTLY base_id_idx ON base (id)The refusal is stricter than the binary on purpose. The binary’s run cannot
reach its target, and that is known before it starts. It stops with the schema
changed and the run half done. Refusing the run first leaves the database as it
was, and the change to the directory is the same either way: mark the file
-- atlas:txmode none, or move the statement into a file that runs without a
transaction. The refusal names Ptah’s own -- +ptah no_transaction; in a
directory both binaries apply, -- atlas:txmode none is the directive to use.
A file that runs without a transaction is not refused, such as a file of one
statement in a
golang-migrate directory,
which that runner sends alone.
Under --format the refusal is reported in the document. Measured on
2026-11-14 over SQLite, with 1_a.sql creating t1 and 2_b.sql holding
CREATE TABLE t2 (id int); and VACUUM;: the binary applies 1_a.sql, sends
both statements of 2_b.sql, and writes a report whose version 2 carries
SQLite’s cannot VACUUM from within a transaction, exit 1, leaving t1
behind. ptah-compat writes a report whose Error is the refusal and which
lists no applied file, because the refusal comes before the first file runs,
exit 1. Neither table is created.
Evidence. integration/migrations_up_transaction_preflight_e2e_test.go,
integration/atlas_migrate_apply_report_shape_e2e_test.go
A file that controls the transaction it runs in
Section titled “A file that controls the transaction it runs in”Type. Deliberate divergence
Current boundary. ptah-compat migrate apply reads every file of the run
before it applies the first. A file that holds its own BEGIN and COMMIT
under the default --tx-mode file controls the transaction the migrator runs
it in, and the run is refused: no file is applied and no revision row is
written. A dry run is refused the same way. The pinned community binary
applies the files before it, then sends the BEGIN inside the transaction it
opened for the file and exits 1 with the engine’s error. Its dry run sends
nothing and reports every file ok.
Measured on 2026-11-14 over SQLite, with 1_base.sql holding
CREATE TABLE base (id int); and 2_two.sql holding the lines below, each run
on a fresh database, each exit status read from an unpiped invocation:
BEGIN;CREATE TABLE b (id int);COMMIT;| Run | Binary | ptah-compat |
|---|---|---|
migrate apply --url sqlite://db.sqlite |
applies and records version 1, then fails version 2 with cannot start a transaction within a transaction, exit 1 |
refuses the run, creates nothing and records no revision, exit 1 |
migrate apply --url sqlite://db.sqlite --dry-run |
lists both versions as ok, exit 0 |
refuses the run, exit 1 |
ptah-compat names the migration and the statement before anything runs:
Error: error applying migrations: migration 2 cannot run tx-mode file up statement 1 because it controls transaction state; remove the transaction control and let Ptah manage the transactionThe refusal is stricter than the binary on purpose, for the reason
A file its transaction would refuse
gives: the binary’s run cannot reach its target, and that is known before it
starts. The change to the directory is the same on both binaries: remove the
transaction control, because the migrator already runs the file in one
transaction. Marking the file -- atlas:txmode none is no fix on ptah-compat;
A txmode none file that controls its own transaction
says why.
Evidence. integration/migrations_up_text_refusal_e2e_test.go
A MySQL file the transaction witness refuses
Section titled “A MySQL file the transaction witness refuses”Type. Deliberate divergence
Current boundary. On MySQL and MariaDB, ptah-compat migrate apply runs a
file under the default --tx-mode file with Ptah’s transaction witness, which
refuses a statement whose effect it cannot tie to the file’s transaction, such
as a table on a non-transactional storage engine.
Recovering from a migration body that failed part-way
lists the forms. The refusal reads the file alone, so the run is refused before
it applies the first file, in a dry run too. The pinned community binary
runs the file as written.
Measured on 2026-11-14 on MySQL 8.4, with 1_base.sql holding
CREATE TABLE base (id int); and 2_two.sql holding
CREATE TABLE b (id int) ENGINE=MyISAM;, each run on a fresh database, each
exit status read from an unpiped invocation:
| Run | Binary | ptah-compat |
|---|---|---|
migrate apply |
applies and records both versions, exit 0 |
refuses the run, creates nothing and records no revision, exit 1 |
migrate apply --dry-run |
lists both versions as ok, exit 0 |
refuses the run, exit 1 |
Error: error applying migrations: migration 2 statement 1 selects non-transactional storage engine MyISAM; tx-mode file requires InnoDB on MySQL-family databasesThe refusal is stricter than the binary on purpose. MySQL commits around DDL,
so a file in --tx-mode file can fail with part of it committed, and the
witness is how Ptah records which part. A MyISAM table’s writes do not share
the transaction the witness is written in, so that record could not be
trusted. The same file marked -- atlas:txmode none applies on both binaries,
measured the same way.
Evidence. integration/migrations_up_text_refusal_e2e_test.go
A statement the bundled SQLite refuses
Section titled “A statement the bundled SQLite refuses”Type. Deliberate divergence
Current boundary. ptah-compat migrate lint replays a SQLite directory on
the SQLite Ptah bundles. SQLite 3.54 refuses to rename a column to oid,
rowid or _rowid_, with cannot rename to rowid alias, and the SQLite in the
pinned community binary, 3.49.1, renames it. The binary’s own fixture
cli-migrate-lint-project.txtar has such a rename in its base. Measured on
2026-11-13 with that fixture’s directory and project file, each exit status read
from an unpiped invocation:
| Run | Binary | ptah-compat |
|---|---|---|
migrate lint --env log_name |
prints 3.sql, exit 0 |
prints 1.sql, exit 1 |
migrate lint --env log_count |
prints 2, exit 0 |
prints 1, exit 1 |
migrate lint --latest 1 |
analyzes version 3 and reports its DROP TABLE, exit 1 |
reports Error: executing statement: SQL logic error: cannot rename to rowid alias: oid (1), exit 1 |
migrate apply on a new database |
applies the three migrations, exit 0 |
refuses the rename in migration 1, exit 1 |
Ptah reports the refusal in the binary’s shape for a replay error rather than skipping the statement or emulating the older engine. The refusal is SQLite’s own, and the apply refuses the same statement on the same engine, so a lint that accepted it would pass a directory Ptah cannot apply.
Evidence. integration/atlas_migrate_lint_replay_failure_e2e_test.go
A column written with two defaults
Section titled “A column written with two defaults”Type. Divergence: a defect not copied
Current boundary. A column definition in a SQL schema file that writes
DEFAULT twice is refused, on every engine, before anything is planned:
column n carries a second DEFAULT: a column has one default; remove one of them. The pinned community binary replays the file on the dev database
and keeps the engine’s answer. PostgreSQL refuses n int DEFAULT 1 DEFAULT 3
with multiple default values specified for column "n", and SQLite accepts it
and keeps the last default, so the binary plans the column with DEFAULT 3 and
exits 0.
A schema file that writes two defaults for one column has lost one of them,
whichever the engine keeps, and SQLite keeps it without a word. Refusing it on
every engine says so before a plan does. PTAH_ATLAS_STRICT_COMPAT=1 keeps the
refusal: it refuses capabilities the binary lacks, and does not reproduce a
defect.
Evidence. internal/parser/default_operator_test.go
A finding in a goose or dbmate file
Section titled “A finding in a goose or dbmate file”Type. Divergence: a defect not copied
Current boundary. ptah-compat migrate lint reports a finding in a
directory of another layout against the source file the directory holds. A
file’s .Name is that file’s name, its .Text is the file as written, and a
diagnostic’s .Pos is the offset of the statement in that text, so the text
report’s -- L<n>: and {{ $file.Line .Pos }} give the statement’s line. The
pinned community binary does the same in golang-migrate, Flyway and
Liquibase directories. In a goose or dbmate file it reports the same .Text
with an offset counted from the start of the up section, so the line it prints
is line 1, the section directive, however far below it the statement is.
Measured with migrate lint --dev-url sqlite://dev?mode=memory --latest 1 on
two files, where the second drops a table on line 4:
| Second file | Binary | ptah-compat |
|---|---|---|
goose: -- +goose Up, a blank line, -- note, DROP TABLE t;, then a down section |
-- L1:, .Pos 10 |
-- L4:, .Pos 22 |
dbmate: -- migrate:up, a blank line, -- note, DROP TABLE t;, then -- migrate:down |
-- L1:, .Pos 9 |
-- L4:, .Pos 23 |
golang-migrate 2_b.up.sql: -- note, a blank line, DROP TABLE t; |
-- L3:, .Pos 9 |
-- L3:, .Pos 9 |
A line that points at the directive sends the reader to the wrong place in the file, and the binary’s own answer in the other three layouts shows it means the source line. Ptah places the finding where the statement is.
Evidence. integration/migrate_lint_converted_source_lines_e2e_test.go
Removing a column-level UNIQUE on SQLite
Section titled “Removing a column-level UNIQUE on SQLite”Type. Divergence: a defect not copied
Current boundary. SQLite keeps a UNIQUE that a column declares as an
index it builds for itself, sqlite_autoindex_parent_1, and DROP INDEX
cannot name it. Removing it means rebuilding the table, which is the plan
ptah-compat schema diff writes. The pinned community binary v1.3.0 names the
index parent_code and plans DROP INDEX. Measured on 2026-11-18 with
schema diff --dev-url "sqlite://dev?mode=memory" from
parent (id INTEGER PRIMARY KEY, code TEXT NOT NULL UNIQUE) and
child (id INTEGER PRIMARY KEY, code TEXT REFERENCES parent(code)) to the same
document without the UNIQUE and without the foreign key:
| Step | Binary | ptah-compat |
|---|---|---|
| The plan | DROP INDEX parent_code, then a rebuild of child |
a rebuild of parent, then a rebuild of child |
The plan, run with sqlite3 on a database created from the first document |
fails at its second statement with no such index: parent_code |
applies, and both rows remain |
schema apply --auto-approve on that database |
exits 1 with the same error |
exits 0, and both rows remain |
schema diff from the database to the second document afterwards |
plans the same DROP INDEX again |
Schemas are synced, no changes to be made. |
A plan that fails on every database the --from document describes loses the
change the author asked for. In the other direction both binaries write a plan
that applies: the binary creates a standalone unique index, and ptah-compat
rebuilds parent with the UNIQUE on the column, as the document declares it.
Evidence. integration/sqlite_column_unique_removal_e2e_test.go
A COLLATE on a SQLite index key
Section titled “A COLLATE on a SQLite index key”Type. Divergence: a defect not copied
Current boundary. ptah-compat reads a SQLite index key that carries a
COLLATE of its own, CREATE UNIQUE INDEX pc ON parent (code COLLATE NOCASE),
as its text, spelled as a document’s key is spelled whatever the quoting, the
ASC, comments or spacing, so the two compare equal and a change of the
collation is a change. The pinned community binary v1.3.0 reads
the column alone. Measured on 2026-11-18 with schema diff --dev-url "sqlite://dev?mode=memory", a database holding parent (id INTEGER PRIMARY KEY, code TEXT NOT NULL) and that index:
| Run | Binary | ptah-compat |
|---|---|---|
--from the database, --to a document with pc ON parent (code) |
Schemas are synced, no changes to be made. |
drops pc and creates it as ("code") |
--from the database, --to a document with the same index |
Schemas are synced, no changes to be made. |
Schemas are synced, no changes to be made. |
--to the database with child (code REFERENCES parent(code)) added, --from a document with parent alone |
plans CREATE UNIQUE INDEX pc ON parent (code) and child, exit 0 |
refuses the foreign key, exit 1 |
A read that drops the collation changes what the index compares, without a
word, in both the first and the third row. In the third, SQLite holds the
database and fails every write to child with foreign key mismatch, since
the parent key’s index does not use the column’s collation. ptah-compat
refuses that key on the database as it refuses it in a --to document.
Evidence. integration/sqlite_index_key_collation_e2e_test.go
A COLLATE on a SQLite column
Section titled “A COLLATE on a SQLite column”Type. Divergence: a defect not copied
Current boundary. ptah-compat schema inspect writes the collation a
SQLite column declares, b TEXT COLLATE NOCASE, as collate = "NOCASE" in
the HCL document, "collate":"NOCASE" in the JSON one and COLLATE NOCASE
in the SQL one. A column that declares none, or declares BINARY, the
collation it takes without one, is written without it. The pinned community
binary v1.3.0 writes no column collation for SQLite at all. Measured on
2026-11-18 on a database holding t (a TEXT, b TEXT COLLATE NOCASE, c TEXT COLLATE BINARY, d TEXT DEFAULT 'x' COLLATE RTRIM):
| Format | Binary | ptah-compat |
|---|---|---|
| HCL | no collate on any column |
collate = "NOCASE" on b, collate = "RTRIM" on d |
{{ json . }} |
no collate on any column |
"collate":"NOCASE" on b, "collate":"RTRIM" on d |
{{ sql . }} |
no COLLATE |
COLLATE NOCASE on b, COLLATE RTRIM on d |
schema diff and schema apply compare the collation too. Against a
database holding t (id INTEGER PRIMARY KEY, a TEXT, b TEXT COLLATE NOCASE, c TEXT COLLATE RTRIM) and a desired file declaring a TEXT COLLATE NOCASE
and b TEXT, the binary reports Schemas are synced, no changes to be made.,
and ptah-compat rebuilds the table with "a" text COLLATE NOCASE and
"b" text.
A document without the collation describes b as a column that compares as
BINARY, so an apply of it builds a column that sorts and compares
differently, and nothing says so. The binary reads the HCL document Ptah
writes, collate included.
Evidence. internal/dbschema/sqlite/column_collation_test.go,
integration/sqlite_column_collation_e2e_test.go
A COLLATE on a PostgreSQL column
Section titled “A COLLATE on a PostgreSQL column”Type. Divergence: a defect not copied
Current boundary. ptah-compat schema diff and schema apply compare the
collation a PostgreSQL column declares with the one the desired schema names,
and plan ALTER COLUMN ... TYPE <type> COLLATE ... where they differ. The
pinned community binary v1.3.0 does not compare column collations. Measured on
2026-11-18 on a database holding t (id integer PRIMARY KEY, a text, b text COLLATE "C", c text COLLATE "C"), against a desired file declaring a text COLLATE "C", b text COLLATE "POSIX" and c text:
| Command | Binary | ptah-compat |
|---|---|---|
schema diff |
Schemas are synced, no changes to be made. |
ALTER TABLE "t" ALTER COLUMN "a" TYPE text COLLATE "C", ALTER COLUMN "b" TYPE text COLLATE "POSIX", ALTER COLUMN "c" TYPE text; |
schema apply --dry-run |
Schema is synced, no changes to be made |
the same statement |
A collation decides how a column’s values sort and compare, and which index a query can use. A plan that reports the schemas synced leaves a column comparing differently from the declaration, and nothing says so.
Evidence. migration/schemadiff/internal/compare/column_collation_test.go,
integration/postgres_column_collation_e2e_test.go
A changed MySQL table collation
Section titled “A changed MySQL table collation”Type. Divergence: a defect not copied
Current boundary. A column that names no collation takes its table’s
default collation. ptah-compat schema apply plans a changed table default as
ALTER TABLE ... COLLATE in one statement with the reset of each column that
takes it and holds the old one, so one apply converges, with or without
--dev-url. The pinned community binary plans the same statement when
it is given --dev-url. Without it, the binary plans the table’s COLLATE
alone. ALTER TABLE ... COLLATE leaves the collation of every existing column
as it is, so the column keeps the old collation after the apply, and only the
next plan resets it. Measured on 2026-11-19 on MySQL 8.4 and MariaDB 11.8, on
a table retable (id int PRIMARY KEY, n varchar(20)) with
COLLATE=utf8mb4_bin, against an HCL document declaring
collate = "utf8mb4_general_ci" on the table and no collation on n:
| Step | Binary without --dev-url |
Binary with --dev-url, and ptah-compat |
|---|---|---|
first schema apply |
ALTER TABLE `retable` COLLATE utf8mb4_general_ci; |
ALTER TABLE `retable` COLLATE utf8mb4_general_ci, MODIFY COLUMN `n` varchar(20) NULL; |
n after it |
utf8mb4_bin |
utf8mb4_general_ci |
second schema apply --dry-run |
ALTER TABLE `retable` MODIFY COLUMN `n` varchar(20) NULL; |
no change planned |
ptah-compat qualifies each table with its database, which the table above
leaves out. A plan that needs a second apply describes a state the first apply
does not reach. Both binaries reset a column that holds another collation than the one
its table gives it, and both leave alone a column that takes its collation from
a character set it names.
Evidence. migration/schemadiff/inherited_collation_test.go,
integration/mysql_inherited_collation_e2e_test.go
A foreign key over a changed collation
Section titled “A foreign key over a changed collation”Type. Divergence: a defect not copied
Current boundary. A foreign key stands on the collation of both its ends,
so MySQL refuses a change of either end’s collation while the key stands with
Error 3780, and MariaDB with Error 1832. ptah-compat schema apply drops the
key, changes both ends, and adds the key back, as it does for a change of the
columns’ type, so one apply converges and every row keeps its parent. The
pinned community binary v1.3.0 plans a bare MODIFY COLUMN of each end, and
the first statement fails. Measured on 2026-11-19 on MySQL 8.4 and MariaDB
11.8, with --dev-url, on parent (code varchar(10) PRIMARY KEY) and
child (id int PRIMARY KEY, code varchar(10), FOREIGN KEY (code) REFERENCES parent (code)),
both columns COLLATE utf8mb4_unicode_ci, against a SQL file declaring both
COLLATE utf8mb4_bin:
| Step | Binary | ptah-compat |
|---|---|---|
| first statement | ALTER TABLE `child` MODIFY COLUMN `code` varchar(10) NULL COLLATE utf8mb4_bin; |
ALTER TABLE `child` DROP FOREIGN KEY `child_code_fk`, MODIFY COLUMN `code` varchar(10) COLLATE utf8mb4_bin NULL; |
| last statement | the parent column’s MODIFY COLUMN |
ALTER TABLE `child` ADD CONSTRAINT `child_code_fk` FOREIGN KEY (`code`) REFERENCES `parent` (`code`) ...; |
| apply | exits 1 with Error 3780 on MySQL and Error 1832 on MariaDB; both columns keep utf8mb4_unicode_ci |
both columns hold utf8mb4_bin, and the key stands |
The same holds where the columns take the collation from their tables’ default, or from a character set each names.
Evidence. internal/planner/dialects/mysql/fk_collation_test.go,
integration/mysql_foreign_key_collation_e2e_test.go
A foreign key taken back under its name over a retyped column
Section titled “A foreign key taken back under its name over a retyped column”Type. Divergence: a defect not copied
Current boundary. MySQL and MariaDB refuse a change of a referenced
column’s type while a foreign key stands on it. Where a plan drops a foreign
key and adds it back under the same name, and the column it references changes
type, ptah-compat migrate diff and schema diff drop the key first, in a
statement of its own, then change both ends, then add the key back. The pinned
community binary v1.3.0 changes the referenced column first, and the server
refuses that statement. Measured with --dev-url on MySQL 8.4 and MariaDB
11.8, from p (id int PRIMARY KEY) and
a (id int PRIMARY KEY, p_id int, CONSTRAINT fk FOREIGN KEY (p_id) REFERENCES p (id))
to p.id bigint, a.p_id bigint, a new column a.x and ON DELETE CASCADE
on fk:
| Step | Binary | ptah-compat |
|---|---|---|
| first statement | ALTER TABLE `p` MODIFY COLUMN `id` bigint NOT NULL; |
ALTER TABLE `a` DROP FOREIGN KEY `fk`; |
| last statement | ALTER TABLE `a` MODIFY COLUMN `p_id` bigint NULL, ADD COLUMN `x` int NULL, ADD CONSTRAINT `fk` ...; |
ALTER TABLE `a` ADD COLUMN `x` int NULL, ADD CONSTRAINT `fk` ...; |
| apply | the first statement fails with Error 3780 on MySQL and Error 1833 on MariaDB | applies, and the key stands with ON DELETE CASCADE |
Both binaries write the drop of the key as a statement of its own.
Evidence. internal/planshape/order_test.go,
integration/atlas_migrate_diff_statement_order_e2e_test.go
A MariaDB table changed to a UCA 14.0.0 collation
Section titled “A MariaDB table changed to a UCA 14.0.0 collation”Type. Divergence: a defect not copied
Current boundary. MariaDB lists its UCA 14.0.0 collations, such as
utf8mb3_uca1400_ai_ci, with no character set, and the pinned community
binary v1.3.0 reads the character set of a table that holds one as the
schema’s. A change of a table’s default to such a collation, with a column
that names no collation and so takes the table’s, is planned differently in
two places:
- The table’s
CHARSET. Where the other side is not a UCA 14.0.0 collation,ptah-compatwrites the character set the collation names. The binary writes the dev database’s character set, which can be another, and MariaDB refuses the statement with Error 1253. - The column.
ptah-compatrestates it without a character set, so it takes the collation the table declares. The binary addsCHARSET utf8mb3, which gives the column the default collation ofutf8mb3. Where the table declares that default, the result is the same; where it declares another, the column holds the default, and every later plan restates it.
Measured with --dev-url on MariaDB 11.8 and 12.3, on
t (id int PRIMARY KEY, n varchar(20) NULL). ptah-compat qualifies the
table with its database, which the statements below leave out. Between two
UCA 14.0.0 collations both binaries write the table’s COLLATE without
CHARSET, since the collation names its character set.
utf8mb4 to utf8
Section titled “utf8mb4 to utf8”The binary writes:
ALTER TABLE `t` COLLATE utf8mb3_uca1400_ai_ci, MODIFY COLUMN `n` varchar(20) CHARSET utf8mb3 NULL;ptah-compat writes the same without CHARSET utf8mb3. After either, n
holds utf8mb3_uca1400_ai_ci.
utf8mb4 to utf8 with a collation that is not the default
Section titled “utf8mb4 to utf8 with a collation that is not the default”The table declares COLLATE=utf8mb3_uca1400_as_cs. The binary writes:
ALTER TABLE `t` COLLATE utf8mb3_uca1400_as_cs, MODIFY COLUMN `n` varchar(20) CHARSET utf8mb3 NULL;After it, n holds utf8mb3_uca1400_ai_ci, and the next plan restates the
column. ptah-compat writes the same without CHARSET utf8mb3; n holds
utf8mb3_uca1400_as_cs, and the next plan is empty.
latin1 to utf8
Section titled “latin1 to utf8”The binary writes a statement MariaDB refuses with Error 1253:
ALTER TABLE `t` CHARSET utf8mb4, COLLATE utf8mb3_uca1400_ai_ci, MODIFY COLUMN `n` varchar(20) CHARSET utf8mb3 NULL;ptah-compat writes one that applies:
ALTER TABLE `t` CHARSET utf8mb3, COLLATE utf8mb3_uca1400_ai_ci, MODIFY COLUMN `n` varchar(20) NULL;Evidence. integration/mariadb_uca_collation_change_e2e_test.go
A backslash on a NO_BACKSLASH_ESCAPES session
Section titled “A backslash on a NO_BACKSLASH_ESCAPES session”Type. Divergence: a defect not copied
Current boundary. A MySQL or MariaDB session whose sql_mode names
NO_BACKSLASH_ESCAPES reads a backslash in a string as the character.
ptah-compat schema apply writes a declared default, comment, enum value and
declared row for the session that runs it, so the server stores the characters
the declaration holds. The pinned community binary stores four backslashes
where the declaration holds one. Measured on 2026-11-19 with the community
binary v1.4.0 on MySQL 26.10, and with v1.3.0 the same way, with --dev-url
on a session under the same sql_mode, against a SQL file declaring
a varchar(20) DEFAULT 'a\\b':
| Step | Binary | ptah-compat |
|---|---|---|
| the column in the plan | DEFAULT "a\\\\b" |
DEFAULT 'a\b' |
| the default an inserted row takes, in hexadecimal | 615C5C5C5C62 |
615C62 |
On a database the binary created, ptah-compat schema apply plans the column’s
default back to the declared value. SQL ptah-compat writes for later, such
as a migration file or schema diff output, is written for the default
sql_mode; see MySQL.
Evidence. integration/backslash_escapes_session_e2e_test.go,
integration/escaped_literal_apply_e2e_test.go
Not on this page
Section titled “Not on this page”--to file://../schema.sql and --dir file://../dir used to be refused as
outside allowed root where that binary exits 0 (item 11 of that issue). They
are accepted now, and the divergence is closed rather than retained.
The refusal came from a containment that applied to relative CLI paths only: the
identical file named by an absolute path was accepted, and migrate diff --to
against it succeeded. A boundary that refuses one spelling of a path and accepts
another spelling of the same path contains nothing, so the refusal could not be
defended as a safety control — and it cost a behavior the community binary has.
pathguard.ResolveCLIPath therefore imposes no boundary at all now, and both
spellings of one destination answer identically
(stokaro/ptah#1622).
Containment did not disappear with it. pathguard.ResolveWithinRoot and
OpenDirectoryWithinRoot take an explicit root and bind every spelling against
it, which is what the project migration-directory confinement uses, and a
write directive in a --format template still cannot compute a filename that
leaves the root the operator chose.
Both migrate hash cells of that issue – the trailing positional of item 13
and --var of item 12 – were unread when this page was written, because the
sandbox those sweeps ran in refused any command containing that bare word. They
were read on 2026-08-17 in an environment that does not, and they split:
- the trailing positional is a divergence, argued under Positional arguments a flag already names above, where it joins the verbs that already refuse one;
--varis parity.migrate hash --dir file://mig --var x=1exits0on both binaries with byte-identical output, which is none.
Neither is an unknown on this page any more (stokaro/ptah#1623).