Build a Compatibility Matrix Before Changing a Field
Tác Giả: OmniStack
Ngày đăng: 11/18/2026

On this page
- Start with the business meaning, not the column
- List every reader and writer that can be deployed out of order
- Use parallel change to define the expansion boundary
- Build the proposed old/new reader-writer compatibility matrix
- Turn database DDL into compatibility evidence
- Make fixtures executable before rollout
- Approve rollout, rollback and contract gates separately
- FAQ
- What is a database field compatibility matrix?
- How does parallel change schema migration work?
- Should the new reader or new writer deploy first?
- Does PostgreSQL NOT VALID show that existing data is correct?
- When should an internal team own the field change?
- Sources and limits
In a hypothetical multi-site commerce system, a warehouse dashboard shows a delivery state that the order service did not write under the older contract. The database row is valid. The dashboard is reading an older interpretation of a field while a newer service has changed its meaning.
That is the deployment skew concern. A field change is often approved as a database operation when it is really a compatibility decision across software versions. One service deploys a new writer. A warehouse job, reporting export, queue consumer or admin reader still runs old code. The old reader may not understand the new meaning. The new reader may assume a field has already been populated. The database may accept both shapes while the business workflow no longer does.
A proposed database field compatibility matrix template makes those combinations explicit before production deployment. It records which old and new writers may meet which readers, what fixtures represent each state, what behaviour is expected, what failure means and whether rollback remains possible. The matrix supports a narrow approval question for a parallel change schema migration: which combinations are deliberately supported during coexistence, and which combinations are blocked by a release gate?
Start with the business meaning, not the column
A field change is acceptable only when the team has defined the old meaning, the new meaning, the valid values, the unknown state, the default behaviour and the person accountable for the business rule. The column definition is evidence of storage shape. It is not the contract by itself.
Take a hypothetical field called delivery_status. Its old meaning might be a single string such as pending, shipped or delivered. The proposed meaning might distinguish fulfilment states, failed handoffs, partial shipment and customer collection. A nullable column, a default value or a successful type conversion cannot decide whether an order is operationally ready for dispatch. The owner of that meaning must.
- Old meaning: the state the existing writer records and the existing readers interpret.
- New meaning: the state the replacement writer records and the replacement readers expect.
- Valid values: the permitted values and their business definitions, not merely an enum or database type.
- Unknown state: what a reader does when the new field is absent, null, unmapped or outside its known value set.
- Default behaviour: what happens when an old writer omits the new field or a record has not reached backfill.
- Owner: the product or operations authority who can reject a technically valid interpretation that breaks the workflow.
The proposed matrix template must be adapted to the domain. A hypothetical financial services team changing a transaction classification field has a different invariant from a hypothetical logistics operator changing parcel state. The common requirement is narrower and more demanding: every supported version combination must preserve the named business invariant during deployment skew, rollback and backfill.
Write the invariant in operational language. A parcel cannot be allocated to a carrier after it has been cancelled is testable. The status remains consistent is not. If the new field changes meaning rather than merely adding detail, create an explicit mapping from every legacy value to the new interpretation. Do not hide disputed semantics inside a migration script.
For a legacy platform, the surrounding architecture may be the harder problem. A proposed legacy system modernisation approach should preserve this contract analysis rather than treating schema work as an isolated upgrade. The field may be consumed by applications that the database team does not own.
List every reader and writer that can be deployed out of order
The most dangerous omission is a consumer that does not look like an application. A compatibility plan must include user-facing services, admin tools, warehouse jobs, payment reconciliation, exports, queues, search indexing, analytics and backfill scripts. The database accepting both shapes does not mean every supported old and new combination preserves the workflow.
This approach fails when the team inventories only the primary API. That failure mode is predictable in a hypothetical multi-site operation: the order service is visible in the deployment system, while a nightly export, a site-specific integration or a manually triggered reconciliation job sits outside the main release path. If any of those readers can run during the coexistence interval, they belong in the proposed matrix template.
Build the inventory from code, infrastructure and operational practice. Search for the field name and its aliases. Trace event payloads. Inspect materialised views, reporting queries, data warehouse transformations and queue schemas. Ask operations which spreadsheets, exports or admin screens are used when the normal path fails. A reader that is rarely used still matters if it can make a decision or write a derived value.
Path | Typical role | Compatibility question | Evidence to collect |
|---|---|---|---|
User-facing service | Reads or writes live transactions | Can old and new versions process the same record without changing the business invariant? | Request fixtures, response contracts and write queries |
Admin tool | Allows support or operations intervention | Can an operator view and update an unmigrated or unknown state as intended? | Screen queries, mutation paths and operator procedures |
Warehouse or site job | Drives physical fulfilment | Does a legacy value trigger the same operational action during rollout? | Job code, schedules, input filters and output effects |
Queue consumer | Processes delayed events | Can an old event arrive after the new writer is deployed? | Payload versions, retry policy and dead-letter handling |
Export or report | Feeds finance, partners or management | Does the new meaning preserve the report's decision rule? | Queries, transformations and report definitions |
Search or analytics indexer | Creates derived views | Can mixed records be indexed without silently dropping or misclassifying them? | Mapping code, replay process and index schema |
Backfill script | Writes historical or derived state | What does a reader see while the backfill is paused or incomplete? | Batch boundaries, restart behaviour and partial-state fixtures |
The table above is a proposed inventory template, not a deployment artefact. Record deployment order for each path. A claim that the old service will be removed first is not evidence unless the release system, queue retention and rollback procedure make that true. A delayed message can reintroduce an old payload after the writer has moved. A report may run from a replica that lags the primary. A site may remain on an older release because its operating window differs from the central deployment schedule.

Use parallel change to define the expansion boundary
Martin Fowler's Parallel Change pattern separates a compatible change into expand, migrate and contract. Expand makes the system accept both old and new forms. Migrate moves consumers and data. Contract removes the old path after the compatibility interval has ended.
The pattern is a mechanism for coexistence, not a promise of zero downtime, complete historical conversion or reversible rollback. The proposed compatibility matrix template decides which combinations are deliberately supported and which combinations are blocked by a release gate.
In the expand phase, the database and readers must tolerate the old representation. A new nullable column, a dual-read adapter or a translation layer may be appropriate. The writer should not begin emitting a value that an active old reader cannot interpret. If it must, the team needs an adapter or a deployment gate showing that the old reader is no longer reachable.
During migrate, readers move first where practical. A new reader should handle records before backfill, after backfill and during an interrupted backfill. Writers can dual-write or write a backward-compatible representation while consumers move. The matrix should show whether both values are authoritative or whether one is derived. Two writable representations without an ownership rule create a reconciliation problem.
Contract is the removal phase. It includes deleting the old reader path, stopping legacy writes, removing translation code, enforcing the final constraint and retiring the old column only after the evidence says it is no longer needed. A successful deployment of the new reader is not the contract gate. The gate is evidence that supported old paths have either drained, been blocked or been deliberately accepted as unsupported.
Proposed expansion boundary template: the system must accept the old and new representations without changing the business invariant, and the matrix must name every path that is allowed to cross that boundary.
Do not label a release expand complete because a migration tool exited successfully. Expand is complete only when the old readers and writers have an explicit supported behaviour against the expanded shape. If the team cannot state that behaviour, the release is still changing the contract.
A field that changes meaning may need a compatibility adapter rather than a direct dual-write. The adapter can translate a new fulfilment state into the legacy status expected by an old warehouse job. That translation must have a defined loss boundary. If the old representation cannot express a new state, the matrix should mark the old-reader path as blocked rather than silently collapsing the value.
Related:data engineering and analytics services, useful when reports, indexes and pipelines are part of the field's reader inventory.

Build the proposed old/new reader-writer compatibility matrix
Verdict: do not approve a production field change until each supported writer-reader combination has a fixture, an expected result, a failure interpretation and a rollback note.
Writer | Reader | Fixture | Expected behaviour | Failure means | Rollback note |
|---|---|---|---|---|---|
Old writer | Old reader | Existing value | Current behaviour remains unchanged | Expansion broke the old path | Must remain usable until contract gate |
Old writer | New reader | Null or missing new field | New reader derives a value or treats it as unknown by contract | New code assumes completed backfill | Rollback should not require data repair |
New writer | Old reader | New value plus legacy value | Old reader sees a supported legacy representation | New write is not backward compatible | Block deployment or add adapter |
New writer | New reader | New semantic value | New invariant is checked in the target path | Target behaviour lacks evidence for the fixture | Allow only after dependent paths pass their gates |
Backfill script | Named application reader | Partially migrated record | Reader handles mixed state according to the contract | Rollout assumes atomic population | Define pause and resume behaviour |
Old event producer | Queue consumer | Delayed old payload after new reader deployment | Consumer accepts, rejects or routes the event according to the stated contract | Queue retention or retry behaviour was omitted from the plan | Keep adapter or drain queue before contract |
New writer | Export or report | Unknown enum value or legacy value with new meaning | Report applies the approved decision rule or marks the record as unclassified | Reporting logic has encoded obsolete semantics | Block report publication or keep legacy representation |
Backfill script | Search or analytics indexer | Record written while backfill is paused | Indexer preserves the record and exposes the intended state marker | Derived view can silently misclassify mixed records | Reindex plan must include mixed-state records |
The table above is a proposed template, not an OmniStack deployment artefact. Extend it for every relevant path. Named application reader is a placeholder that must become a specific service, job, report or consumer before approval. A matrix that hides readers behind a broad label cannot support an operational decision.
Add the states that cause production incidents rather than testing only a clean new value:
- the field is omitted by an old writer;
- the field is explicitly null;
- a database default supplies a value that was never present in the business event;
- an enum value is unknown to the reader;
- a legacy value maps to more than one new state;
- the record was written before backfill;
- the record was written during backfill;
- the backfill paused after one representation changed but before the other did;
- a delayed queue message carries the old payload after the new writer is live.
Each row should answer five questions in plain language. What record enters the path? What does the reader return or write? Which invariant is being checked? What does a failure tell the release owner? Can the system be rolled back without repairing data first?
Use a separate row when the same service has different read paths. An API response, a reconciliation query and a background retry handler may share a codebase but have different assumptions. The matrix is about executable behaviour, not organisational ownership.
The acceptance claim must stay narrow. These tests support the listed paths and fixtures. They do not show that every possible record history, retry sequence or operator action is acceptable.
Turn database DDL into compatibility evidence
PostgreSQL DDL is not compatibility evidence by itself. The PostgreSQL ALTER TABLE documentation describes operations such as adding columns, changing defaults, changing types and adding constraints. Those operations have different effects and operational implications. The exact PostgreSQL major version, statement sequence, indexes, table size and concurrent workload must be pinned before an executable migration is approved.
PostgreSQL's NOT VALID option for some constraints can allow a constraint to be added without immediately checking every existing row, with validation performed later. That can help separate enforcement for new writes from historical validation. It does not show that old rows satisfy the intended business rule. The proposed matrix template still needs fixtures for old rows, invalid legacy values and partially migrated records.
DDL or control | Compatibility question | Evidence required | Common false conclusion |
|---|---|---|---|
Add nullable column | How do old writers and new readers behave while the column is absent or null? | Old-write and null-read fixtures, plus default analysis | The column exists, so the new contract is ready |
Change default | Does the default represent a real business state or merely fill storage? | Insert tests from every writer and explicit omitted-field cases | Every new row has a correct semantic value |
Change type | Can old readers consume the stored or returned representation? | Conversion fixtures, lock observation and rollback path | A successful cast establishes compatibility |
Add constraint | Which writes are rejected, and what happens to historical violations? | Invalid new-write fixtures and old-row validation evidence | Constraint enforcement establishes historical correctness |
Add constraint as | Can new writes comply while old rows remain unvalidated? | New-write tests, explicit validation plan and invalid legacy fixtures |
|
Validate constraint | Can validation run within the production lock and workload assumptions? | Version-pinned rehearsal and monitoring plan | Validation is operationally free because it is separate from creation |
The table above is a proposed DDL review template. PostgreSQL documentation should support the mechanism claim, not replace testing. The PostgreSQL explicit locking documentation is relevant because DDL and concurrent operations can interact through locks. Do not overstate lock behaviour without pinning the PostgreSQL major version and the actual statement sequence.
The team should rehearse the exact statement sequence in an environment that represents production closely enough for the decision being made. Observe lock waits, transaction duration, replica behaviour and application error handling. The PostgreSQL transaction isolation documentation is useful for reasoning about visibility under concurrent transactions, but it does not answer whether a reader understands the business meaning of a field.
Database locks and transaction visibility are only part of the evidence. A migration can complete while application traffic continues to violate the intended semantic contract. The DDL plan and the reader-writer matrix must be reviewed together. A technically available column does not make a new reader acceptable to deploy.
For systems with reporting or event pipelines, schema work may also require a controlled CI/CD and DevOps delivery plan so release gates, migration execution and rollback signals are visible in one operating procedure. The link is relevant only when those delivery paths are part of the change, not as a substitute for database evidence.
Make fixtures executable before rollout
A fixture is useful only when it can fail the release. Convert each matrix row into a contract test using old payloads, new payloads, omitted fields, nulls, defaults, unknown enum values and partial backfill records. Include queue consumers, exports and reports where they can make operational decisions. The acceptance claim must remain limited to the paths and fixtures actually tested.
- Freeze the contract examples. Store representative old and new payloads with the semantic meaning expected by the product or operations owner.
- Test old readers against expanded data. Include new writers that emit a legacy-compatible representation and values that cannot be represented without loss.
- Test new readers against incomplete data. Run records with missing fields, nulls, defaults, legacy values and backfill pauses.
- Replay delayed work. Feed old queue messages, retries and exports after the new reader is deployed.
- Test interruption. Stop the backfill between batches and confirm that readers, alerts and operational procedures behave as designed.
- Record the narrow claim. State that the tests support named paths and fixtures. Do not claim that every possible record history is acceptable.
Unknown enum values deserve a deliberate test because they expose an assumption about future change. An old reader may reject them, map them to an unsuitable default or silently discard the record. The correct behaviour belongs to the business contract. Ignore unknown values is not automatically acceptable for payment, fulfilment or formal reporting workflows.
Default values need the same scrutiny. A database default can make a row look complete while concealing that the writer did not know the state. If unknown is a real state, name it and make downstream handling visible. If it is an error, reject the write or route it to an operational queue. A default that merely keeps inserts working can make the matrix pass while the workflow fails.
Backfill tests should include three temporal positions: before the backfill reaches the record, after it completes, and while the record is in a mixed state. A backfill that exits with code zero is not enough evidence for this guide. The reader must show that it can handle records created while the process was paused, retried or interrupted.
Keep the proposed test worksheet template beside the release record. It should include fixture identifier, writer version, reader version, database state, expected invariant, observed result, owner and release decision. This is a proposed template, not a deployment artefact.
Approve rollout, rollback and contract gates separately
Rollout, rollback and contract are different approvals. A team can show that a new reader works without showing that a new writer can be rolled back. It can pause a backfill without showing that old readers tolerate the mixed state. The proposed decision record template must give each gate its own conditions.
Gate | Minimum decision question | Evidence | Block condition |
|---|---|---|---|
New reader release | Can the reader handle old, null, default, unknown and partially migrated states? | Matrix fixtures and observed contract-test results | Reader requires completed backfill without a proven dependency |
New writer release | Can active old readers consume the new write or is an adapter in place? | Old-reader tests, deployment inventory and adapter behaviour | New meaning cannot be represented by an active old reader |
Backfill start | Can readers handle records before, during and after conversion? | Pause, resume and partial-state tests | Mixed state produces an unacceptable business action |
Rollback | Can the old writer and reader resume without data repair? | Rollback rehearsal and dual-representation ownership rule | Rollback depends on deleting or rewriting new values first |
Contract | Are legacy writers, readers and representations no longer reachable? | Traffic evidence, queue drain evidence and owner sign-off | Any supported path still depends on the old field |
The table above is a proposed gate template. Rollback deserves a concrete design. If the new writer has populated a value that the old reader cannot understand, switching application binaries back may not restore service. A rollback plan that says redeploy the previous version is incomplete. The matrix should state whether the old representation is preserved, whether an adapter remains available, whether new writes are blocked or whether the release must move forward.
In a hypothetical APAC multi-site operation, deployment skew may be intentional. Sites can have different release windows, network conditions or local integrations. The matrix should identify the longest supported coexistence interval and the path that controls its end. If that interval cannot be bounded, contract cannot be scheduled responsibly.
There is also a clear point where this approach is the wrong choice. If the field's business meaning is disputed, no compatibility matrix can resolve the dispute. An internal domain team should own the decision when semantics are subtle, formal or inseparable from institutional knowledge. A matrix can expose disagreement, but it cannot manufacture authority.
OmniStack can be considered as a dedicated engineering team option when the buyer already has a clear product or domain owner and needs sustained execution capacity for tests, migration code, release gates and operational follow-through. An in-house team is usually the better owner when the field meaning is contested or depends on institutional judgement that has not been written down.
Use this proposed decision record template before opening the migration ticket:
- the old and new meanings are written in business language;
- every reader, writer, queue, job, export and index path has an owner;
- the supported old/new combinations are marked in the matrix;
- unsupported combinations have a release gate or adapter;
- fixtures cover omission, null, default, unknown, legacy and partial states;
- the exact PostgreSQL version and DDL sequence have been rehearsed;
- rollback does not depend on unplanned data repair;
- backfill pause and resume behaviour is tested;
- the contract gate has evidence that old paths are drained or deliberately blocked.
The next decision is not whether the column can be altered. It is whether the business can tolerate each named combination while old and new software coexist. If the answer is no, choose the corrective action before implementation begins: add an adapter, split the release, delay the writer change, keep the old representation or assign an internal domain owner.
FAQ
What is a database field compatibility matrix?
A proposed database field compatibility matrix template records how old and new writers behave with old and new readers during a field change. It includes fixtures, expected behaviour, failure meaning and rollback notes for application paths, jobs, queues, reports and backfill processes.
How does parallel change schema migration work?
Parallel change separates a compatible migration into expand, migrate and contract. Expand supports old and new representations, migrate moves readers and data, and contract removes the old path after the matrix evidence shows it is no longer required.
Should the new reader or new writer deploy first?
The new reader usually needs to tolerate the old representation before the new writer emits changed meaning. The correct order depends on the matrix. If an old reader cannot represent the new value, use an adapter or block the writer until that reader is no longer reachable.
Does PostgreSQL NOT VALID show that existing data is correct?
No. NOT VALID can defer checking existing rows for some constraints while applying enforcement to new writes. Historical rows still require explicit validation, and the compatibility matrix must include legacy and partially migrated fixtures.
When should an internal team own the field change?
An internal domain team should own the change when the field's meaning is disputed, highly specialised or tied to formal operational judgement. External delivery capacity can execute defined work, but it should not be expected to decide the business semantics.
Sources and limits
- Martin Fowler, Parallel Change: used for the expand, migrate and contract mechanism. It is not treated as evidence of zero downtime, complete historical conversion or reversible rollback.
- PostgreSQL documentation, ALTER TABLE: used for the mechanisms of adding columns, changing defaults, changing types and adding constraints, including
NOT VALIDwhere applicable. - PostgreSQL documentation, Explicit Locking: used only for the mechanism that DDL and concurrent operations can interact through locks. Lock behaviour should be assessed against the pinned PostgreSQL version and exact statement sequence.
- PostgreSQL documentation, Transaction Isolation: used for visibility mechanics under concurrent transactions. It does not determine application-level field semantics.

