A Schema Change Can Break Software That Has Not Deployed Yet

Tác Giả: OmniStack

Ngày đăng: 11/17/2026

A Schema Change Can Break Software That Has Not Deployed Yet

A hypothetical regional commerce platform completes a database migration during a release window. The migration adds a replacement status field, copies existing values and leaves the primary service healthy. The next application release then fails because a warehouse application was built against the old field and still expects the previous status values. The database change succeeded. The release plan did not.

That is the risk this guide addresses: deployment skew between a shared database contract, the producers that write it and the consumers that read or derive meaning from it. The affected software may be running now, queued for deployment, scheduled to run later, packaged in a mobile build or held as a rollback version.

A schema change is a contract change, not a migration ticket

A schema change is a contract change whenever more than one producer or consumer depends on the affected table, column, constraint, view or value meaning. The migration script is only one part of the work. The real approval question is whether every version that may run during the coexistence interval can operate with the expanded shape, and whether the intended business meaning remains intact.

This approach has a boundary. If a database is genuinely private to one service, has no scheduled jobs, no reporting extracts, no rollback build and no external operational workflow, a full dependency graph may be unnecessary. That is not the normal condition for many APAC multi-site operators. Warehouse routing, finance exports, support screens, reconciliation jobs and head-office reporting often move on different release calendars.

For an Australian or Singapore operator, the failure may not appear at the instant of ALTER TABLE. It may appear when a site deployment arrives late, a monthly report runs, a queue handler replays an old message or a rollback build is redeployed against a contracted schema. The database is shared even when the teams are not.

The useful artefact is a proposed schema change compatibility graph template. It records each producer and consumer, the field or table involved, the deployed or pending version, the expected business meaning and the evidence required before the old shape is removed. A graph turns a vague migration review into a release sequencing decision.

Teams responsible for data platforms should also separate ownership of the database contract from ownership of business acceptance. A dedicated engineering team can map dependencies, build compatibility fixtures and execute migration work when internal capacity is constrained. The business owner still needs to confirm what values mean in warehouse, finance, support and reporting workflows. Technical compatibility cannot approve a semantic change on its own.

Why software that has not deployed yet can still be broken

Undeployed software can break because the next executable version is part of the migration surface. A branch, release candidate, delayed mobile build, scheduled job or rollback package may be compiled against the old schema and become the first software to run after the destructive step.

The symptom is usually misleading. The current production service continues to read and write successfully, so the migration is marked healthy. In a hypothetical site upgrade, a reader introduced later may not understand the new nullability or status value. A reporting extract may fail at its next cycle because a column was renamed. A rollback may restore application code but not the removed data contract. Current health checks do not cover those paths if they are not current traffic.

Mobile and site deployments make this more visible. A head-office service may be updated while a warehouse application remains on the previous release. A branch may have passed compilation before the schema change and be promoted later. A background job may run outside the release window, reading historical rows that were not present in the migration test dataset.

Rollback deserves separate treatment. A rollback build is a consumer of the pre-change contract, even if the team expects never to use it. If contraction removes a column or old enum value, the previous application version may no longer start, may write data the new contract rejects or may interpret a replacement value incorrectly. A rollback plan that restores binaries without restoring their data contract is incomplete.

The same issue applies to software built but not deployed. A release candidate can be compiled, tested and waiting for a site window. If it was built against the old shape, it belongs in the dependency review. The relevant question is not what is live. It is what can run next.

For organisations formalising ownership of data contracts, data governance and data management practices can provide the operating model around definitions, owners and evidence. The migration still needs a concrete graph for the specific change.

Build the proposed producer and consumer dependency graph

The root cause of many unsafe contractions is an incomplete inventory. The graph must identify who writes, reads, derives or interprets the changed data, including software that is not part of the primary application release.

Node

Relationship to changed data

Version or timing risk

Required compatibility evidence

Order API writer

Creates or updates the changed field

New writer may deploy before all readers understand the new meaning

Dual-write or expanded write path tested against old and new readers

Warehouse reader

Reads the field to group, route or release work

May be deployed after the database migration but before the application change

Fixture showing old value, new value and absent value behaviour

Background job

Reads historical rows and writes derived state

May run on a schedule outside the release window

Dry run or bounded execution plan using the expanded schema

Reporting export

Consumes column names, nullability or semantics

May not fail until the next reporting cycle

Contract fixture for field presence, type and meaning

Rollback build

Could be redeployed after a failed release

May expect the pre-change schema

Rollback path checked before contraction

Unreleased branch

Compiled against the old contract

May become the next production deploy

Branch or release candidate check before destructive change

This graph is a proposed template for approval, not an OmniStack deployment record.

Each node needs more than a service name. Record the exact table, column, view, constraint or value set. Mark whether the node reads, writes, derives or exports the data. Capture the deployed version and the version waiting for release. Add the schedule for jobs and reports. A monthly report is not safe to omit because it was absent from the last deployment window.

The graph should record evidence rather than assurances. A fixture showing old, new and absent values is stronger than a general compatibility statement. A dry run can be useful for a backfill job. A branch scan or release candidate test identifies code that can be promoted after the migration. A rollback rehearsal establishes whether the old binary can operate against the expanded schema.

Do not treat traffic observation as proof that a consumer no longer exists. A dormant export, manual support tool or scheduled reconciliation process can remain operationally important. The graph should contain an explicit status for unknown dependencies, with an owner and a decision date. Unknown is a risk state, not an empty cell.

Data pipelines and warehouse extracts deserve their own review because they often copy schema assumptions into another system. Data engineering and analytics delivery is relevant when the migration crosses transactional, reporting and analytical boundaries, but the business owner must still validate the meaning of the resulting data.

Database vault connected to varied software consumers and producers in an isometric engineering lab.

Separate schema compatibility from semantic compatibility

Schema compatibility means that software can technically interact with the database shape. Semantic compatibility means that the software interprets the values in the intended business way. The first does not prove the second.

A nullable column with a default may keep SQL statements working while changing operational behaviour. A status value can retain its type and still break a warehouse pick rule. A split field can leave an old reader functioning while losing information that finance expects. A renamed value can pass validation as text while causing a support workflow to classify an order incorrectly.

Use two separate questions for every graph edge:

  • Shape question: Can the consumer read and write the expanded or contracted columns, types, nullability and constraints?
  • Meaning question: Does the consumer interpret each old, new, absent and transitional value correctly for its business workflow?

A proposed compatibility fixture template should include representative states, not only a happy-path row. For a hypothetical delivery platform changing an order status, the fixture might include an old status, the replacement status, a missing replacement value during backfill and a record created by the new writer. The warehouse reader should show whether each state routes, holds or releases work. The reporting export should show whether historical and current values remain distinguishable.

Defaults require scrutiny. A default can make an insert succeed while assigning a meaning that was never valid for historical rows. Nullability can preserve a query while causing a dashboard to exclude records. A type-preserving rename can be more dangerous than a type change because automated checks may not detect the altered interpretation.

This is where domain acceptance belongs with the internal business team. A dedicated engineering team can implement the graph, fixtures, migration and release evidence. In-house operations, finance or product owners should approve whether pending, held and released still mean what their workflows require. In-house ownership wins when the semantic decision is inseparable from a business rule that only the operator can authorise.

Related:legacy system modernisation and migration guidance, useful when the schema change sits inside a wider application renewal programme.

Use expand, migrate, contract without turning it into a slogan

Verdict: expand, migrate and contract is a sequencing mechanism, not a safety promise.Martin Fowler’s Parallel Change pattern provides the useful order for changing a shared interface over time: introduce a compatible shape, move producers and consumers, then remove the old shape only after evidence shows it is no longer required.

During expand, add the replacement column, view or constraint in a way that old software can tolerate. A new column may be nullable initially. A new writer may populate both old and new fields. A reader may understand both representations. The objective is coexistence, not immediate purity.

During migrate, move producers and consumers deliberately. Backfill historical rows where required. Deploy readers that can handle both shapes before enabling the new writer. Update reports, exports, queues and scheduled jobs. Test the rollback build against the expanded schema. Monitor for old writes and unexpected values, but do not treat the absence of observed traffic as proof that a dormant consumer is gone.

During contract, remove the old field, old write path, obsolete view contract or invalid value only after the graph has no unsupported edges. Contract is the approval gate, not a housekeeping task. If one consumer remains unresolved, delay the destructive action, split the change or record the operational consequence with the accountable owner.

Parallel Change does not promise zero downtime. It does not prove that a migration is reversible. It does not validate business semantics. It does not account for every scheduled or unreleased consumer unless the team has put those nodes into the graph. The pattern reduces coordination risk by creating a coexistence interval; it does not remove the need for evidence.

For legacy estates, the coexistence interval may cross several application teams and site release windows. A system modernisation programme should therefore preserve the old contract long enough for the slowest known consumer, not the fastest service. Cloud, DevOps and CI/CD engineering can help make branch checks, migration tests and release gates repeatable, but automation only enforces the rules that the graph contains.

Engineers stage a parallel pipeline before removing the old one in a controlled server-room scene.

PostgreSQL mechanisms that help, and what they do not prove

PostgreSQL provides useful mechanisms for staged changes, but each mechanism answers a narrow database question. The PostgreSQL ALTER TABLE documentation describes operations for adding, altering and dropping columns and constraints. The operational effect depends on the operation and PostgreSQL version. Lock behaviour, table rewrites and validation work must be planned rather than inferred from the small size of the SQL diff.

The PostgreSQL explicit locking documentation is relevant to approval because a migration plan should identify what lock is taken and when validation or rewrite work occurs. A short statement can still wait behind active transactions or block other work, depending on the operation and workload at the time.

  • Pin the PostgreSQL major version before publishing or approving migration examples. Syntax, lock behaviour and operational details must be checked against the version actually deployed.
  • Identify the lock acquired by each operation and the point at which it is acquired.
  • Separate adding a constraint from proving existing rows satisfy it.
  • Measure backfill and validation behaviour separately from the schema alteration.

PostgreSQL’s NOT VALID option for some constraints can support staged enforcement. A constraint can be added without immediately validating all existing rows, with validation performed later. This is useful when introducing new invariants to a live table. It does not prove historical data is clean before validation, and it does not prove that application producers and consumers understand the new invariant.

A proposed migration worksheet template should capture the database mechanism and its limit:

  • Operation and PostgreSQL major version
  • Expected lock and possible waiting behaviour
  • Whether a table rewrite or validation scan is involved
  • Rows already conforming and rows requiring remediation
  • Backfill timing and validation timing
  • Producer and consumer evidence required before contraction

This worksheet is a proposed template, not an OmniStack deployment record.

The database can enforce a constraint, but it cannot know whether a warehouse status is semantically correct. It can accept a dual-write, but it cannot prove that both values represent the same business event. It can show database-level references, but it cannot discover every unreleased branch or monthly extract. PostgreSQL mechanisms support the plan; they do not replace the dependency graph.

Approval gate for the destructive step

The destructive step should be approved only when the proposed graph, deployment skew, rollback compatibility and consumer evidence are visible to the accountable decision-maker. The decision is approve, delay or split the contraction. It is not that the migration script passed review.

Use a proposed approval gate template with named evidence:

  • Graph completeness: every known producer, reader, derived-state writer, report, export, queue handler, scheduled job, mobile or site build, rollback version and unreleased branch has an owner.
  • Shape evidence: each consumer has been tested against the expanded schema, including absent, old and new values where relevant.
  • Semantic evidence: the business owner has approved the meaning of transitional and final values for operational, finance, support and reporting workflows.
  • Deployment sequencing: the order of producer and consumer releases is recorded, including delayed sites and scheduled work.
  • Rollback compatibility: the stated rollback build can operate against the schema at the point where the release could fail.
  • Exception ownership: every unknown or unsupported consumer has a named owner, a decision date and an explicit consequence.

A multi-site operator should be especially strict about delayed deployments. A head-office release may be ready while a warehouse site remains on the previous version. If the old site reader cannot tolerate the expanded shape or new value meaning, the contraction must wait. A reporting extract that runs after the release window belongs in the gate even if its owner is outside engineering.

Delivery model

Who coordinates the schema work

What the operator must still own

Failure mode to watch

Internal team

Internal engineering and domain owners

Technical sequencing, semantic acceptance and final approval

Capacity pressure causes scheduled, reporting or rollback consumers to be deferred

Dedicated engineering team

Team technical lead with client product and operations owners

Business meaning, risk acceptance and final approval

The team maps technical dependencies but lacks access to domain decision-makers

Shared internal and external delivery

Named internal owner with the delivery lead

Semantic decisions and approval to remove the old contract

Technical evidence and business acceptance are tracked in different places

The next decision is specific. Name the proposed contract change, list every producer and consumer that could run before the next release window, and mark the first unknown dependency. If that unknown cannot be assigned an owner and evidence date, do not approve the destructive step.

FAQ

What is a schema change compatibility graph?

A schema change compatibility graph is a proposed map of producers, consumers, derived-state jobs, reports, exports, queues, branches and rollback versions connected to the database object being changed. It records the affected field or table, deployment timing, business meaning and evidence required before contraction.

Why include software that has not deployed?

Undeployed software may be the next version to run. A release candidate, delayed site build, scheduled job or rollback package can still depend on the old schema and fail after a destructive change.

What is the difference between schema and semantic compatibility?

Schema compatibility means the code can technically read or write the database shape. Semantic compatibility means it interprets the values and business rules correctly. A query can continue to work while a warehouse, finance or reporting workflow produces the wrong result.

Does expand, migrate, contract remove downtime risk?

No. The sequence creates a coexistence period that can reduce deployment skew, but it does not promise zero downtime, reversibility or correct business meaning. Those require separate operational, rollback and domain acceptance evidence.

What does PostgreSQL NOT VALID prove?

For supported constraints, NOT VALID can defer validation of existing rows. It is evidence about database enforcement timing, not evidence that historical data is clean or that application producers and consumers understand the new invariant.

Sources and limits

These sources support mechanisms and sequencing only. They do not validate any hypothetical scenario, business outcome or operational acceptance decision.