Skip to content
PtahDocs
latest

Graphic preview

100%
Page type: status

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.

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.

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.

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).

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-error

With 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.

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=3

The 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.

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.

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 row
effective all transaction binary 0 rows ptah-compat 0 rows native 1 row
effective no transaction binary 1 row ptah-compat 1 row native 1 row

The 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

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

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_table
ptah-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

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

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

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

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

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

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

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 in pg_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_key and rooms.room_slot as schema.object, so neither names a constraint. Ptah also reads a two-part pattern as table.constraint in 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 in extra are gone; ptah-compat keeps the column, its default and its values.
  • kinds.idx_name[type=index] and kinds.trg_name[type=trigger]: the binary applies without the index or the trigger; ptah-compat keeps 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 plans DROP INDEX kinds_code twice, and its schema apply fails on the second statement with no such index: kinds_code. ptah-compat writes the new table with the CHECK and without the UNIQUE.
  • *[type=constraint]: the binary writes a new table without the UNIQUE and the CHECK. Every constraint stays out of scope on ptah-compat, so nothing of the table changes.
  • *[type=index]: the binary writes a new table without the UNIQUE and drops the index. ptah-compat keeps the index and the UNIQUE, 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

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

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

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

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 alone

With 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

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 --to reads, 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 --to naming 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.

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

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-compat
BEGIN; 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 idle
BEGIN; CREATE TABLE t2 (id int); COMMIT; t2 stays, records 3 of 4 t2 stays, records 3 of 4
INSERT INTO missing_table VALUES (1); with the error, exits 1 with the error, exits 1
CREATE 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 0

Directories 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

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 own
SQL: 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 transaction

The 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 databases

The 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

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

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

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

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

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

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

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

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

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-compat writes 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-compat restates it without a character set, so it takes the collation the table declares. The binary adds CHARSET utf8mb3, which gives the column the default collation of utf8mb3. 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.

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.

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

--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;
  • --var is parity. migrate hash --dir file://mig --var x=1 exits 0 on both binaries with byte-identical output, which is none.

Neither is an unknown on this page any more (stokaro/ptah#1623).