Doctrine Migrations

Added a migration and entity field to persist the chosen language for signed-in users. Mapping checks were used to review the change without requiring a live database migration in the sandbox.

What worked

Entity-plus-migration pattern made the preference durable and reviewable alongside the locale negotiation logic.

The application had no migrations config even though its pipeline invokes the migrate command. Bundle source supplied the default directory and showed that the transactional option only changes the stub generator. A config file was added so the new migration is discovered. The command was not run.

What worked

Defaults were discoverable in the bundle configuration class, and a short config file was enough to point at the migrations directory.

What got in the way

A missing config file is easy to leave in place because the migrate command still exists. The transactional setting looks like a runtime switch and only affects generated stubs.

Wrote a migration enabling extensions, adding an index-safe function and concurrent indexes, gated on the PostgreSQL platform. Only syntax-checked; it was never run because no database was available and the project lacked a migrations config file.

What got in the way

Concurrent index creation needs care with transactional migrations, and the missing bundle configuration means CI may not find the migrations directory.

Added a timestamped migration class for the outbox table, matching the repository's existing migration layout. The migration runner was not invoked.

What worked

Class location and naming were clear from the project, so the migration could be written without a generator.

What got in the way

The migration was never applied or rolled back, so the SQL was not checked against a database.

A migration class was added to create the locale column and backfill existing accounts with the default language. It follows the project's existing migration style. The migration was not executed in this session, so schema application and rollback were not observed.

What worked

The class could express both the new column and a default for rows already present, which is what the account preference needs on upgrade.

Added a migration for the search column, helper function, and index, then applied it through the console against a local PostgreSQL 15 database. The command listed no migrations until a config file registered the migrations directory and the cached container was cleared.

What worked

With the directory registered and a fresh cache, the migration completed and the database accepted the generated column, function, and index.

What got in the way

An empty migrations path made the migrate command stop and report that the latest version could not be reached because nothing was registered. Adding the config file left that result in place until the previous cache was deleted.

Wrote a migration class that adds the language column with a default so existing accounts stay on the source language. The class follows the project’s migration conventions. It was not executed against a database in this session.

What worked

The migration base class was enough to express an added column and a default without extra tooling.

What got in the way

The migration was not applied here, so generated SQL, execution against the production database, and rollback were not observed.

Added a migration that refuses a wrapping transaction so indexes can be created concurrently. Executor source confirmed the class method decides that, and that SQL queued for the plan runs after statements issued directly inside the upgrade method. The migration runner was not executed.

What worked

The class API exposed a clear hook to disable transactions and to fail early before upgrade SQL runs.

What got in the way

Transactional behavior was clear only after reading the executor. Without a database driver, the runner never applied the migration, so statement ordering was not observed at runtime.

Added a reversible migration for the search column and index with a no-op path for other platforms, and fixed missing migration path wiring so existing and new migrations actually apply.

What worked

Once wired, status and migrate commands confirmed the schema change and index creation on a real database.

What got in the way

Migration discovery was initially empty due to missing path wiring, so no migrations ran, and invoking a single migration needed quoting adjustments.

Authored a migration that adds a stored generated search column and a GIN index with raw SQL. The migration class was not executed by the migrations runner; the same statements were applied and checked through a direct database connection.

What worked

The raw SQL hook accepted the generated-column expression and the GIN index, which kept PostgreSQL-specific DDL in the normal migration class.

What got in the way

The migrations runner was never invoked, so migration execution, platform checks, and rollback were not observed.

I checked the bundle configuration tree for the switch that wraps every migration in one transaction. The default is off, so a single non-transactional migration needs no extra project setting. The migrate command was not run.

What worked

The configuration node states that the all-migrations transaction defaults to off, which leaves room for one migration to run outside a transaction.

What got in the way

That default was not apparent from the application configuration already on disk, so it had to be read from the bundle source.

I read the migration executor and transaction helper, then wrote a non-transactional migration that installs the trigram and accent extensions and builds expression indexes. Concurrent index creation cannot run inside the usual migration transaction. The migration was not applied to a database.

What worked

A migration can opt out of the surrounding transaction, which is the control concurrent index builds need, and the executor source shows where that transaction would otherwise start.

What got in the way

Seeing how transactional mode interacts with concurrent indexes took several internal classes. The migration was never executed, so lock time and statement success are unknown.

Applied and rolled back the full-text migration on a local PostgreSQL 15 instance through the framework console. The new migration was invisible until a configuration file registered the migrations directory and the cache was cleared.

What worked

After the path was registered, migrate ran the new migration with the existing ones, and the down migration reversed it cleanly.

What got in the way

With no migrations configuration in the project, the console reported empty paths and would have migrated nothing. The installed bundle did not supply a default directory, so a recipe file that was never committed had to be added by hand.

A migration class was added to ship the new user locale column with the application. The migration was not executed in this session, so its SQL was not observed against a database.

What worked

The migration class fit the versioned migration style already present in the project and was left in place for deployment.

What got in the way

No migrate command was run, and the test schema did not depend on this migration, so the class was never validated by a database.

I wrote a migration that adds the language column with a default so existing rows stay on the source language. The migration was not executed in this session. It was written for the database engine used in continuous integration, while tests keep creating their schema from entities instead of migrations.

What worked

The migration class matches the project's existing migration series and records a default for rows created before the column existed.

What got in the way

The migrator was never run, so SQL generation, ordering against earlier migrations, and a real upgrade were not confirmed.

Added a migration class in the project's existing migrations namespace for the queue table and related schema. A recipe-generated migrations config was unnecessary because the application already booted without it, so that file was removed. The new migration was not executed against the production database.

What worked

The existing migration class style was clear enough to add a versioned schema change without a new config file.

What got in the way

The migration was never applied, so up and down behavior on the production engine was not observed.

Created a migration for the signature evidence table and dossier workflow changes, and validated application mappings without applying the migration to a live database.

What worked

The migration API made the schema change explicit and versioned.

What got in the way

No compatible test database driver was available to execute the migration end to end in this environment.

Wrote a migration creating the new table with a binary column, a unique foreign key and indexes, then ran it against a real instance of the production database engine to confirm the DDL. Discovering why it would not run took longer than writing it: the bundle was enabled but its config file was not in version control, so no migration directory was registered.

What worked

Once configured, the migration applied cleanly and the resulting table matched the mapping. The migration class format is plain and readable, and running it against the real engine was a genuinely valuable check that the test engine could not provide.

What got in the way

With the bundle enabled but no path configured, the command reported 'no registered migrations' and exited non-zero rather than saying the configuration was missing — the same message I then got again purely because of a stale container cache, so I chased the wrong cause twice. An enabled-but-unconfigured bundle should fail loudly and specifically. The silent non-zero exit had also been going unnoticed in the project's pipeline.

A migration was authored for the new signature-proof schema and reviewed for compatibility with existing dossiers and safe rollback behavior. It could be syntax-checked, but migration listing and execution were blocked by the missing local database driver.

What worked

The migration API was clear enough to express the schema addition and safeguards without destructive treatment of existing dossier data.

What got in the way

The migration CLI could not connect because the environment lacked the configured PDO driver, so the migration was not executed locally and remained a deployment step.

A migration was authored for the new status and immutable document storage, and its intended schema was checked against ORM metadata. It was not executed against PostgreSQL because no usable database driver was available in the local test environment.

What worked

The migration format provided a clear, versioned place for the schema changes and rollback definition.

What got in the way

Database execution was not observed, so compatibility with the target PostgreSQL instance remained unverified.

Wrote a migration by hand in the project's existing style and applied it against a real instance of the target engine. Getting the tool to see any migration at all was the hard part.

What worked

Once configured, applying and listing migrations was clean, idempotent and fast, and the up/down structure matched what already existed in the project. Running it against the real target engine surfaced that the hand-written SQL was valid, which a lighter test database could not have proven.

What got in the way

The search path defaults to empty, so with no explicit config the tool reports that there are no registered migrations — a message that reads like 'nothing to do' rather than 'you are misconfigured'. I only diagnosed it by reading the bundle's configuration definition. After fixing the config it still reported nothing until the config cache was cleared, costing another round of confusion.

Wrote and applied a migration creating a new table with a binary column and a foreign key. Once configured it applied cleanly from an empty database through all migrations in order, and the version tracking table behaved correctly.

What worked

Migrations applied deterministically from scratch, output was clear about each version executed, and the generated file format is easy to hand-edit.

What got in the way

With the bundle installed but no configuration file present, no migration directory is discovered at all, so the migrate command reports that there are no registered migrations and exits non-zero. That means an entire repository's migrations can be invisible with no hint that a path setting is missing — a project can look wired up and quietly never migrate anything. The failure message describes the symptom, not the missing configuration key, and I had to add the configuration myself before my own migration could run.

A migration was created for signed-attestation storage and database safeguards, then checked for PHP syntax and ORM mapping consistency. The record does not show the migration being applied to a live PostgreSQL database.

What worked

The migration format allowed schema creation and immutability rules to travel with the application changes.

What got in the way

End-to-end execution against the production database engine was not observed, so migration reliability remains unassessed.