Renaming a database column can take one line of SQL. Making that change while a product keeps running takes more planning.

The current application may still query the old name. A background worker may finish a job using yesterday’s code. A rollback may restore an application version that expects a column the migration has already removed.

The problem is the transition between versions.

An expand and contract database migration creates an intermediate state where the old structure remains available while the application moves to the new one. Prisma’s official migration guide describes the core sequence: introduce the replacement, move the data, and remove the old field after it is no longer used. Prisma migration guide

For a production project, that sequence needs explicit rules about reads, writes, verification, and rollback.

Start with the versions that must coexist

Consider a hypothetical application with a customers table:

id
display_name

The team wants to rename display_name to public_name. The meaning and data type stay the same.

A direct rename may be reasonable during a controlled maintenance window. During a rolling deployment, however, some application instances may still issue queries for display_name.

Before writing the migration, list every consumer:

  • Web application instances
  • Background workers
  • Scheduled jobs
  • Imports and exports
  • Reporting queries
  • Administrative scripts

Then ask which versions can run at the same time.

A deployment plan that accounts only for the web server can miss a worker that continues writing the old field for hours.

Expand the schema first

For this example, introduce public_name while retaining display_name.

The expanded schema gives the team room to deploy compatible application code before removing anything.

An illustrative PostgreSQL statement is:

ALTER TABLE customers
ADD COLUMN public_name text;

This is an example, not a complete production migration. The real column type, constraints, permissions, and operational settings must match the application.

Adding a column also does not mean the operation is free of blocking. PostgreSQL documents that ALTER TABLE acquires an ACCESS EXCLUSIVE lock unless a particular subcommand specifies otherwise. Review the exact operation and database version before scheduling it. PostgreSQL ALTER TABLE reference

A small-looking schema change still deserves a rehearsal under representative conditions.

Define one authoritative value during the transition

Two columns introduce a new question: which value is correct if they disagree?

For this simple rename, a practical transition policy is:

  1. Keep reading display_name.
  2. Deploy code that writes the same value to both columns.
  3. Wait until every writer uses that compatible version.
  4. Copy existing values into public_name.
  5. Verify agreement before switching reads.

When both writes happen in the same database, make them part of the same transaction. Two unrelated updates can leave one column changed and the other unchanged if the second operation fails.

This sequence assumes that the team can identify and retire every old writer. If an external integration or long-running process still writes only display_name, the new column can become stale again.

A database trigger or another compatibility mechanism may be appropriate in some systems. That is an architectural choice with its own behavior to test, not something to add automatically.

The essential requirement is a clear answer to this question:

What keeps the old and new representations consistent while both exist?

Backfill existing records deliberately

New application code handles future writes. A backfill handles records already stored.

For a small table, one update may be sufficient. For a large or busy table, a bounded process can make progress easier to observe and pause.

For the example above, the backfill should copy values from the authoritative field using database-side updates. Avoid reading a value into a script, waiting, and later writing that old snapshot over a more recent change.

A useful backfill plan defines:

Decision Example
Scope Existing customer records
Source display_name
Destination public_name
Progress Last completed primary-key range
Restart behavior Completed ranges can be checked or repeated safely
Failure behavior Stop and record the failed range
Verification Compare both columns using null-aware equality

Batch size should come from observation. A fixed number copied from another project says little about this database’s row size, indexes, traffic, or available capacity.

Also separate “the process finished” from “the data is correct.” A script can exit successfully after selecting the wrong records.

Switch reads only after verification

Before changing the application to read public_name, verify that the migration’s invariant holds.

For this rename, the intended invariant is:

Every customer’s new public name matches the existing display name, including null values.

Check the whole relevant dataset, not only a handful of examples. Then exercise the real paths that create and update customers.

A suggested release sequence is:

Stage Reads Writes
Original application Old column Old column
Compatibility release Old column Both columns
After backfill and verification New column Both columns
After the rollback window closes New column New column

Keeping both columns updated after switching reads preserves a useful rollback option: returning to the compatibility release.

That option disappears if the old column stops receiving current values. Define the supported rollback target explicitly instead of assuming that any earlier build remains safe.

Treat rollback as a data decision

Application rollback and database rollback are different operations.

Redeploying old code does not reconstruct deleted information. It also does not automatically reverse data transformations performed after deployment.

Our rename example is relatively simple because both fields have the same meaning. A transformation such as splitting a full address into structured fields is harder. The new representation may not contain enough information to recreate the original text exactly.

Before release, document:

  • Which application version can be restored.
  • Which schema it requires.
  • Whether writes remain compatible after rollback.
  • Whether the transformation is reversible.
  • What happens to data created during the new version’s operation.

Backups are part of recovery planning, but restoring a backup also requires decisions about writes accepted since that backup was taken.

A credible rollback plan describes what happens to those records.

Contract only when the old structure is unused

Removing the old column is the final step.

Before doing it, confirm that application code, workers, reports, scripts, and supported rollback versions no longer depend on it.

Do not use a clean repository search as the only evidence. Queries may live in another service, an external reporting tool, or an operational script.

PostgreSQL also documents that dropping a column removes associated indexes and table constraints, while dependencies outside the table may require additional handling. Inspect those dependencies before approving the removal. PostgreSQL ALTER TABLE reference

Keep the removal in a separate, reviewable migration. The delay between expansion and contraction should be based on evidence that the transition is complete.

Rehearse the transition, not just the final schema

A test database created directly from the newest schema skips the part most likely to cause trouble: moving from the old state.

A migration rehearsal should start with the previous schema and representative data.

Test these situations:

  1. The old application runs against the expanded schema.
  2. Compatible writers keep both values synchronized.
  3. The backfill stops partway through and resumes.
  4. Customer updates occur during the backfill.
  5. Reads switch to the new field.
  6. The application returns to its documented rollback version.
  7. The old field is removed only after compatibility is no longer needed.

Observe lock waits, application errors, backfill progress, and data mismatches. Use the results to decide whether the planned release window and migration approach are appropriate.

For a client, the useful deliverable is a release plan with clear stopping points. “Migration included” is not enough detail to understand how existing data and ongoing work will be protected.

Make the intermediate states part of the feature

Expand and contract introduces temporary complexity: extra fields, compatibility code, and cleanup work.

That cost is justified when the product needs old and new application versions to coexist. For a small system with an acceptable maintenance window, a simpler coordinated migration may be the better choice.

The decision should follow the product’s availability needs and operational capacity.

When staged migration is appropriate, define every intermediate state as carefully as the final one. Each stage should have a known reader, a known writer, a verification rule, and a supported recovery path.

The migration is complete when the new structure works, the old dependencies are gone, and the temporary compatibility code has been removed.

Related reading

Deployment compatibility also affects retained frontend assets. See HTTP Caching: Faster Websites Without Stale Content.

Sources

Sources checked November 12, 2026. The customer-table example and release checklist are illustrative recommendations, not reported client results.