Download the PHP package nandan108/attrecord-migrations without Composer

attrecord-migrations

Declarative schema convergence for attrecord: the Record class is the schema, so evolution is convergence — introspect the live database, diff it against the attribute-derived TableSchema, and apply a classified, guarded ALTER plan. No migration files, no second source of truth, no down scripts.

Design contract: attrecord's docs/arch-migrations.md — read it for the full rationale (why convergence beats a migration chain for attribute-driven schemas and file-replacement deployments, prior art, and the non-goals fence).

Backends: MySQL/MariaDB, PostgreSQL, SQLite — same tri-dialect matrix as attrecord itself.

Installation

Requires PHP 8.1+ and nandan108/attrecord ^0.17.1 || ^0.18. No other runtime dependencies.

Footprint: src/ is ~143 KB across 33 files (~89 KB of that is code — the other 38% is docblocks), so the published package is ~64 KB zipped. That is on top of attrecord itself, and only for consumers who want schema convergence: the split exists so writing rows never drags in the machinery that rewrites schemas.

It is a separate package by design: attrecord's DDL producer is fresh-install only, and schema evolution carries risks (destructive ALTERs, live introspection, a safety model) that have no business being reachable from a library you pull in to write rows. Nothing here runs unless you call it.

Quick start

A converged database re-plans empty — that invariant (create → introspect → identical canonical tuples on both sides) is pinned by the test suite on all three backends.

Change classes — the safety model

Every planned change carries a class; apply(allow:) is a ceiling over the ladder Safe → Destructive → Assisted, each admitting everything at or below it:

The pipeline's bias is fail-safe: an unparseable live type or ambiguous facet degrades to Manual with a reason. It never guesses an ALTER (the Doctrine schema-tool:update lesson — normalization + classification are the load-bearing parts, not the diff).

Why a constraint drop is Safe

Dropping a constraint removes no row and no column value, and re-adding it a moment later always succeeds, because the data that satisfied it still does. "Drops" in the Destructive row means drops of data-bearing things — columns, tables.

The sharper reason is what an undeclared constraint is: a rule forbidding writes the Records permit, so leaving it in place is drift that silently overrules the schema. It is not hypothetical — MySQL's CHANGE COLUMN carries a column's constraints along with it, so a declared rename can leave an ON DELETE CASCADE pointing at a table the column no longer belongs to, quietly deleting rows on the next parent delete.

The line is contradiction, not losslessness, which is why an undeclared index stays Destructive: it forbids nothing, so it adds to the model rather than overruling it. Being wrong about one is also expensive and invisible — it may be an operator's tuning index, and dropping that degrades a query plan under load rather than raising anything. Foreign keys and CHECKs both forbid, and both drop at the default ceiling.

Ownership is a separate axis, with two granularities: #[Unmanaged] names one object as somebody else's, PartiallyDeclared says it of a whole table. Prefer the first where you can name what is not yours — the interface buys its silence by going quiet about all drift on that table.

A foreign key or index whose shape changed is one replace_foreign_key / replace_index carrying both statements, not a separate drop and add, so no ceiling can authorise half of a replacement.

Saying what the Records do not

A schema describes what exists. Three things a differ has to know are in no schema at all, and the attrecord attributes that declare them (0.19.0) are inert until this package reads them.

A column rename is declared, never inferred.

produces a data-preserving RENAME/CHANGE COLUMN instead of a destructive drop+add. Inference from drop+add similarity is a known trap (Skeema refuses it; Django prompts a human).

An index rename is inferred, because a wrong guess there costs a rebuild rather than rows. An orphaned add and an orphaned drop of identical shape are the same index, emitted as one rename_index; ambiguity falls back to plain create + drop. Declare it when the shape changed too, which is the case no heuristic can see:

A retired object is declared absent, which is what makes dropping it safe rather than a guess:

An index or unique key declared absent drops at the Safe ceiling. A column does not — saying you meant it does not bring the values back — but the plan now says declared absent since 2.0.0 rather than exists live but is not declared, so a Destructive plan distinguishes the deliberate removal from the surprise.

Deleting an #[Absent] line later is safe: the object falls back to the undeclared path, still reported, just no longer automatic. The exception is a PartiallyDeclared table, where nothing undeclared is reported at all.

An object somebody else owns is declared unmanaged:

Change-attached steps

When a data transform rides a schema change, the schema state is the marker — a TEXT column is the unwrapped state, JSON the wrapped one — so attach the transform to the change rather than versioning it:

The selector is "kind table.subject" in the same vocabulary a plan prints, so it can be read off plan()'s own output. Steps run at their position in the apply order, are recorded in the run ledger, and a failing step stops the run and is reported against the change it was attached to.

A selector matching no change is a no-op, on purpose. On the second boot of a converged install the change was applied long ago and the plan is empty, while your code still attaches its step — erroring there would fail every subsequent boot. The mistake that can be caught, a kind that does not exist, is refused when you write it; unmatched steps are recorded, so "my backfill never ran" is answerable afterwards.

The pair is not atomic on MySQL or MariaDB, and no API can make it so: DDL auto-commits there, so a step and its change cannot share a transaction. PostgreSQL and SQLite have transactional DDL and let a caller wrap the whole apply. Write steps to be re-runnable where the transform allows it.

Run-once data steps

Schema converges because its state is introspectable. Data shape is not — so transforms the differ cannot see (content changes within an unchanged column type) use the run-once registry:

At most once per database, recorded in the step ledger (attrecord_schema_steps) — the one place the ledger is authoritative. There is no down(): on a file-replacement deployment model no code exists to run it at the right moment; roll forward or restore a backup.

Circular foreign keys

Two tables that reference each other have no creation order that works while every FK is emitted inline — whichever goes first points at a table that does not exist yet. Rather than refuse the model, one edge of each loop is deferred:

Nothing to configure: the cycle is found in the declared graph, and which edge gets deferred falls out of the input order, so the same model set always resolves the same way. The deferred ADD is ordered after every create in the plan, because its target may be created later in the same run.

Tables whose shape is computed

Some tables have a shape that is only known at runtime: a registry that grows a column per registered dimension, an extension table a plugin writes into. A Record class cannot describe those, so plan() also accepts a ready-made TableSchema — derive one with attrecord's TableSchema::extendedWith() and pass it alongside your class-strings:

Those columns are then created, converged and diffed like any other — including being added to an existing table when the runtime set grows. fingerprint() covers them too, so the fast path notices when the runtime set changes. Describing them beats the alternative, a hand-written ALTER TABLE run at boot: a second source of DDL that no tooling can see or verify.

When you can't describe them: PartiallyDeclared

If the extra columns genuinely cannot be enumerated, the Record can opt out of drift detection for whatever it does not declare:

The differ is then narrowed to what the Record declares: missing declared columns and indexes are still added, declared ones still converge, but nothing undeclared is ever proposed for dropping — columns, indexes and constraints alike. The trade-off is one-directional, which is why it is opt-in per Record: on such a table, a genuinely stray column from an old version is never surfaced either. Prefer describing the columns when you can; this is the fallback.

If you can name the objects that are not yours, #[Unmanaged] is the better tool — it excludes exactly those and leaves the rest of the table under the differ's eye. Reach for the interface only when the shape is genuinely computed and cannot be named ahead of time.

(The two do not combine: a TableSchema you built is taken at face value, since the point of building it is that the columns are now described.)

Fingerprint fast path

sha256 over the dialect's own buildCreateTable() output. Store the last-converged value (e.g. a WordPress option) and skip even plan()'s introspection while the running code's fingerprint matches.

The ledger

Every apply() run is recorded in attrecord_schema_runs (statements + outcomes + error) — for forensics only. The differ never reads it: truth about the live schema comes from the live schema, so a restored backup or hand-edited database simply re-plans correctly.

Both ledger tables can live under your own naming — subclass the Record with its own #[Table] and hand the subclass to the migrator:

Limitations (all fail LOUD as Manual or Assisted, never silently wrong)

• SQLite: no in-place column modification and no FK add/drop — those changes classify Manual (the table-rebuild dance is phase 2). ADD COLUMN with a non-constant default likewise. This also means a cyclic schema only partly converges there: the tables are created, but the deferred constraint (see "Circular foreign keys" above) cannot be added and is reported as Manual.
• Enum members are visible on all three backends. MySQL-family carries them in the column type; PostgreSQL and SQLite have no native ENUM, so the producer stores them in a chk_<column>_enum CHECK constraint and they are read back out of it. PostgreSQL applies a member change by swapping that constraint; SQLite detects but cannot apply it (no DROP CONSTRAINT — it needs the table rebuild), so it classifies Manual. A constraint body this package cannot parse yields "members unknown", and an unknown on either side skips the comparison rather than guessing — the fail-safe direction, and the one that keeps an unparseable body from planning a swap forever.
• Primary keys are compared but never altered. A key that differs from the declaration — composite or not — is reported Manual with both sides named, because rebuilding a primary key rewrites the clustered index and can fail outright on duplicate rows. Composite keys are comparable (a #[PrimaryKey(columns: …)] table converges from empty and re-plans empty on all three backends), not alterable.
• MySQL-family json folds to longtext (MariaDB stores JSON as LONGTEXT) — json↔longtext drift is undetectable there.

• Generated columns are compared on every facet except nullability, which the engine owns outright — it reports the column nullable whatever you wrote, so comparing it would make a correct database report drift forever.

  The expression is compared, against the engine's own re-printing of it rather than your spelling: identifier quoting and whitespace are dropped, and bracket pairs are removed where no operator can bind across them (MariaDB drops the outer pair you wrote, MySQL adds one around a compound function argument — neither means anything). Brackets that group are kept and compared. A difference the canon cannot absorb is reported Assisted with both spellings quoted, so a normalization gap looks like one at a glance instead of like a schema change; adopting it is harmless either way. A column gaining or losing generation entirely is a plain modification.

• CHECK constraints are converged by name, never by expression. No engine stores the expression you wrote (MySQL re-prints it with charset introducers, PostgreSQL adds casts), so a body comparison would report drift on a correct database forever. attrecord's own #[Check] names carry a digest of the expression, so an edited rule arrives here as a differently-named constraint — one add, one drop — which makes name-only diffing complete for constraints this producer emitted. A hand-written constraint whose body someone edits in place, keeping the name, is genuinely invisible. Adding one is Safe but flagged mayRejectExistingRows: the statement validates every existing row and fails atomically if any breaks the rule. SQLite has neither ADD nor DROP CONSTRAINT, so both classify Manual there.

  Two kinds of CHECK are recognised as column-owned and never proposed for dropping: the chk_<column>_enum member list on PostgreSQL/SQLite, and MariaDB's automatic CHECK (json_valid(col)) on a JSON column (MariaDB has no JSON type — it is LONGTEXT plus that constraint, engine-created, declared by nobody).

• ON UPDATE CURRENT_TIMESTAMP drift and PostgreSQL BIT round-trips are not compared.
• Tables the Records don't declare are invisible — never dropped, never touched.
• An index whose leading columns are a foreign key's columns is treated as that FK's supporting plumbing and never proposed for dropping, even if the Records don't declare it. A genuinely operator-added index on exactly an FK's columns therefore survives — the fail-safe direction.

Running tests

Integration tests reuse attrecord's containers but their own database (attrecord_migrations_test, auto-created by the test support layer) — never attrecord's attrecord_test. Environment variables (defaults shown):

An unreachable engine makes its suite skip, which locally is a convenience and in CI would be a lie — so CI runs with --fail-on-skipped. A skipped backend is not a passing backend.

Two suites carry most of the weight, both against real engines:

• Golden round-trip — every portable ColumnType (plus SET/BIT on MySQL, where they exist) created by the DDL producer, introspected back, and asserted to normalize to identical tuples on both sides. A type missing here is a type that could false-positive an ALTER at a consumer.
• Drift matrix — one scenario per kind of drift (widen/narrow, nullability, default, integer and decimal widening, enum members, rename, index reshape, FK action change, undeclared FK), injected as raw DDL into a converged database, then plan → assert kind + class → apply → re-plan EMPTY. Each backend states its own expectations, so the drifts an engine cannot see (SQLite stores affinity, not width) are pinned as explicitly empty rather than quietly untested. The enum-member scenario is why that matters: it sat pinned as empty on PG and SQLite for a release, which is exactly how long the blind spot went unnoticed — the expectations now say modify_column/Safe and manual/Manual.

Code style & static analysis

Style is enforced with PHP CS Fixer (the @Symfony ruleset plus project overrides in .php-cs-fixer.php), and types with Psalm at level 1:

All three run in CI against PHP 8.1–8.4 with MySQL 8.0/8.4, MariaDB 10.11/11.4, PostgreSQL 14–17 and SQLite — the same published attrecord release a consumer would get.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for the dev setup and the checks to run. Behavioural design changes belong in the design contract (attrecord's docs/arch-migrations.md), whose §7 is the non-goals fence.

License

MIT © Samuel de Rougemont