Skip to content
atom®technologiesBook a call
Platform modernization

Before the first strangler cutover: prove PostgreSQL lock conflicts and read visibility, then move traffic

Approve the first strangler slice cutover only after a rehearsal that records the exact SQL statement, its documented lock mode, the commands it conflicts with, and the isolation level. This article gives the one-page gate and the evidence to collect.

A software team at a whiteboard

The decision, answered

Require the lock-and-visibility rehearsal before approving the first cutover. A written plan that names the schema or data change is not enough: the approval record should state the exact PostgreSQL statement, the lock mode the documentation assigns to it, which concurrent commands conflict with that mode, and the transaction isolation level the application will run at, backed by a rehearsal under concurrent write traffic. The rehearsal is a proposed diligence step, not a PostgreSQL guarantee.

Whether its effort is justified is a judgment your team has to make against the impact of a blocked write path; this article does not quantify that comparison.

Why the slice still needs a gate

Martin Fowler's Strangler Fig article, published 22 August 2024 as a revision of his 2004 piece, describes gradual modernization: new features are built on top of, yet separate from, the legacy code base, and bits of behavior are moved from the legacy system into the new code base. Fowler writes that a simple-sounding wholesale replacement plan has gone down in flames most of the time, because replacing a serious system takes a long time, users cannot wait for new features, and existing behavior is often hard to specify. He lists four high-level activities for the incremental approach: understand the outcomes you want, break the problem into smaller parts, deliver the parts, and change the organization so this can continue; he notes the ordering does not imply a sequence. He also states that legacy systems rarely exhibit components that can be replaced independently, so identifying seams is considerable work.

The inference here is ours, not Fowler's: a small slice reduces replacement scope, but the slice still needs a lock-and-visibility gate. Its data step can conflict with concurrent writes, and its reads can vary within a transaction at the default isolation level. Smallness reduces blast radius; it does not remove the concurrency question.

What the lock documentation actually says

The PostgreSQL Explicit Locking documentation, current for PostgreSQL 18, states that two transactions cannot hold locks of conflicting modes on the same table at the same time, and that the only real difference between lock modes is the set of modes each conflicts with. It also states that all the listed modes are table-level locks even when the name contains the word row, because the names are historical.

The documentation assigns lock modes to common commands, with one distinction that matters for a cutover plan. It states that SELECT acquires ACCESS SHARE on referenced tables, and that in general any query that only reads a table and does not modify it acquires this mode. A locking read is a different case: the documentation states that SELECT acquires ROW SHARE on all tables where one of the FOR UPDATE, FOR NO KEY UPDATE, FOR SHARE or FOR KEY SHARE options is specified, in addition to ACCESS SHARE locks on other referenced tables. So a cutover step that uses SELECT FOR UPDATE is not the plain-read case, and the gate should record which form the step uses.

The documentation also states that UPDATE, DELETE, INSERT and MERGE acquire ROW EXCLUSIVE on the target table, that CREATE INDEX without CONCURRENTLY acquires SHARE while CREATE INDEX CONCURRENTLY acquires SHARE UPDATE EXCLUSIVE, and that some modes are self-conflicting: ACCESS EXCLUSIVE cannot be held by more than one transaction at a time, while ACCESS SHARE can be held by multiple transactions. It states that pg_locks shows the currently outstanding locks in a database server, which is the inspection point for the rehearsal.

The reasoned inference: because ordinary writes acquire ROW EXCLUSIVE, a migration step holding any mode that conflicts with ROW EXCLUSIVE can block those writes for the duration of the step. That is a statement about documented conflict sets, not evidence about your workload or its timing. Whether the block matters depends on how long the step holds the lock and what write traffic exists, which is exactly what the rehearsal measures.

Name the exact statement, not the command family

The PostgreSQL ALTER TABLE documentation shows why "we will run an ALTER TABLE" is not an approvable plan. Its synopsis lists many distinct subforms and actions, including ADD COLUMN, ALTER COLUMN TYPE, ADD CONSTRAINT, VALIDATE CONSTRAINT and DETACH PARTITION. These are different operations, and the gate requires your engineer to look up the specific subform in the PostgreSQL ALTER TABLE documentation and record the documented lock level there.

A limit on this article's evidence: the ALTER TABLE excerpt we worked from is truncated and does not include the per-subform lock-level text. We therefore do not state which lock mode any ALTER TABLE subform acquires, and we do not claim the documentation says anything specific about how those levels are organized. The verification requirement stands on its own: the exact subform must be named, and its lock level taken from the named documentation, not carried from a blog post or from this article.

Read visibility at the chosen isolation level

The PostgreSQL Transaction Isolation documentation states that Read Committed is the default isolation level in PostgreSQL. At Read Committed, a SELECT without a FOR UPDATE or FOR SHARE clause sees a snapshot of the database as of the instant the query begins; the documentation states that two successive SELECT commands can see different data within a single transaction if other transactions commit changes after the first SELECT starts and before the second one starts. For a cutover step that reads a balance or a status with a plain SELECT, checks it, then acts, that gap is where the plan and reality diverge.

Locking reads need separate treatment. The documentation states that UPDATE, DELETE, SELECT FOR UPDATE and SELECT FOR SHARE find only target rows committed as of the command start time, but that such a target row might already have been updated, deleted or locked by another concurrent transaction; the excerpt we worked from truncates at that point. If your step uses a locking read, the gate should record that and the behavior should be checked against the Transaction Isolation documentation rather than assumed to match the plain SELECT case.

The same documentation carries a caveat that matters for migration steps: changes to a sequence are immediately visible to all other transactions and are not rolled back if the transaction that made the changes aborts. If your slice seeds rows through a serial column or draws from a sequence, an aborted attempt can still consume values. The gate asks whether the step uses a sequence, and records the answer.

The one-page gate, as a proposal

We propose the approval record carry these fields, each with a named owner. Exact SQL statement, including the specific subform: owned by the engineer making the change. Documented lock mode, taken from the PostgreSQL documentation for that exact subform: same engineer. Conflicting commands, derived from the documented conflict set, with a note on which of them your production path actually runs: owned by whoever owns the data model. Whether the step uses a locking read, the transaction isolation level the application uses during the step, and whether the step uses a sequence: owned by the application or platform lead. Rehearsal evidence: a run of the step against a copy with concurrent write traffic, with pg_locks inspected during the run: owned by the engineer, witnessed by the reviewer. Sign-off: the CTO or VP Engineering, on the record, not in a thread.

This gate is our proposed diligence step. It is not an established practice we can attribute to a source, and it is not a claim that any particular system has a defect. It is a way to make the cutover approvable with evidence rather than intent.

What would change the recommendation

If the slice moves no data and changes no schema, only code behind an existing interface, the lock question largely disappears and the gate shrinks to the isolation-level, locking-read and sequence fields. If the step runs in a maintenance window with writes paused, the rehearsal matters less, and the changing-read caveat does not apply while no concurrent transactions can commit between the step's reads; the sequence caveat still applies, because the documentation ties it to sequence behavior on abort, not to concurrent commits. If your database is not PostgreSQL, none of the lock-mode or isolation facts above transfer; the PostgreSQL documentation describes PostgreSQL, and the equivalent conflict and visibility questions must be answered against your engine's own documentation. And if the rehearsal shows the step conflicts with a mode your write path holds continuously, the recommendation changes from "rehearse and proceed" to "redesign the step" before any traffic moves.