Your Deployment Passed. Your Database Migration Didn't Break Anything. So Why Is Production Still at Risk?
A database migration can finish successfully, the application can pass its health checks, and the deployment pipeline can turn green — yet your production system may still be one rollback away from an outage.
The problem is often not whether the migration succeeded.
It is whether the old and new versions of your application can safely work with the database at the same time.
This becomes especially important when deploying applications through rolling deployments, where old instances are gradually replaced by new ones rather than stopped all at once.
Let's understand why this happens and how the expand-and-contract pattern helps manage schema changes safely.
1. The Problem: Application Deployments Are Not Atomic
Imagine an existing application with a PostgreSQL table:
CREATE TABLE users (
id SERIAL PRIMARY KEY,
full_name VARCHAR(255),
email VARCHAR(255)
);
Your application reads and writes the full_name column.
Now, a requirement arrives: split full_name into two separate fields:
first_namelast_name
A straightforward migration might look like this:
ALTER TABLE users
RENAME COLUMN full_name TO first_name;
Then you update the application to use first_name and last_name.
It looks reasonable. But consider what happens during a rolling deployment.
| Deployment stage | Application version | Database |
|---|---|---|
| Before deployment | Version 1 | full_name |
| Migration executed | Version 1 | first_name |
| New instances starting | Version 1 + Version 2 | first_name |
| Deployment completed | Version 2 | first_name |
The old application instances still expect full_name.
The database no longer has that column.
Those instances can start failing immediately, even though the new application code is correct.
There is another problem: what happens if the new deployment fails and you roll back to Version 1?
The old application still cannot use the renamed column.
A successful migration does not automatically mean a safe deployment.
2. Understand the Expand-and-Contract Pattern
The expand-and-contract pattern separates one potentially risky schema change into multiple backward-compatible steps.
Instead of changing the database structure and application code simultaneously, we introduce the new structure first, migrate the data, switch application behavior, and remove the old structure only when it is no longer needed.
There are three main phases:
Phase 1: Expand
Add the new database columns without removing the existing ones.
ALTER TABLE users
ADD COLUMN first_name VARCHAR(100),
ADD COLUMN last_name VARCHAR(100);
The old application continues using full_name.
The new columns are available, but existing application behavior does not depend on them yet.
Phase 2: Migrate and Switch
Deploy application code that understands both the old and new schema.
During the transition, the application can:
- Write to both old and new fields.
- Read from the old field when the new fields are not populated.
- Backfill existing records.
- Gradually move read operations to the new fields.
Once the data is verified and the new application version is fully deployed, the application can start treating the new fields as the primary source.
Phase 3: Contract
Only after confirming that no active application version depends on full_name should we remove it.
ALTER TABLE users
DROP COLUMN full_name;
This should be a separate migration and deployment step, not part of the initial release.
The important principle is simple:
Add first. Migrate second. Remove last.
3. Implementing the Pattern with FastAPI and SQLAlchemy
Let's look at how this approach can work in a Python backend.
Assume the application currently stores a user's full name in one column.
After the expansion migration, the database contains all three fields:
users
├── id
├── full_name
├── first_name
└── last_name
Step A: Update the application to support both schemas
During the transition, the application should handle records that have not yet been migrated.
A simplified SQLAlchemy model:
from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
full_name = Column(String(255), nullable=True)
first_name = Column(String(100), nullable=True)
last_name = Column(String(100), nullable=True)
The application can use a compatibility layer:
def get_user_full_name(user):
if user.first_name or user.last_name:
return " ".join(
part for part in [
user.first_name,
user.last_name
]
if part
)
return user.full_name or ""
This allows application code to work with both migrated and unmigrated records.
In a real system, the compatibility logic should also account for the business rules around names, including single-word names and empty values.
Step B: Write both old and new fields
During the transition, new updates should keep the old and new representations synchronized.
def update_user_name(user, first_name, last_name):
user.first_name = first_name
user.last_name = last_name
user.full_name = " ".join(
part for part in [first_name, last_name]
if part
)
The important detail is that all three assignments should be persisted within the same database transaction.
Otherwise, a partial failure could leave the two representations inconsistent.
Also, dual-writing is a temporary compatibility strategy, not a permanent architecture. It introduces additional consistency responsibilities and should have a clear removal plan.
Step C: Backfill existing records
Adding new columns does not automatically populate existing data.
For a small table, a simple update might work:
UPDATE users
SET
first_name = split_part(full_name, ' ', 1),
last_name = NULLIF(
substring(full_name FROM position(' ' IN full_name) + 1),
''
)
WHERE first_name IS NULL
AND full_name IS NOT NULL;
However, this is only an illustrative parsing rule. It does not correctly model every possible human name.
For large production tables, avoid treating one massive update as the default solution.
Instead, use a resumable batch process:
BATCH_SIZE = 1000
def backfill_users(session):
while True:
users = (
session.query(User)
.filter(
User.first_name.is_(None),
User.full_name.isnot(None)
)
.order_by(User.id)
.limit(BATCH_SIZE)
.all()
)
if not users:
break
for user in users:
parts = user.full_name.strip().split(maxsplit=1)
user.first_name = parts[0] if parts else None
user.last_name = parts[1] if len(parts) > 1 else None
session.commit()
Arun PottiPosted Nov 16, 2026, 5:30 AM
Good Article.