Back to insights
What Your Migration Tool Cannot Model Becomes Release Debt
DataCat Engineering · 2026-08-24 · 6 min
A schema diff can pass while promotion still fails on grants, platform-managed schemas, partial indexes, raw SQL, and dependency ordering. The missing control is a schema-model boundary review, not another dry run.
The Promotion Looked Clean Until The Target Environment Answered Back
The migration review deck says the hard part is over.
The schema diff passed. The preview database came up. The application smoke test looked fine. Then the target environment answered back with the failure that actually matters:
- the grants are wrong for the runtime role
- the hosted platform owns part of the schema you treated as yours
- the partial index or extension path lives outside the tool's modeled surface
- a raw SQL step ran, but the verification gate did not reason about it
- dependency ordering changed just enough to break replay or promotion
That is not bad luck. It is the operating boundary between what the tool can model and what the database estate still requires you to prove.
The Common Story Versus The Operating Reality
The common story is that schema-as-code plus a successful diff plan equals database truth.
The operating reality is narrower and less forgiving: the modeled schema is only one layer of truth. Roles, grants, default privileges, platform-managed schemas, conditional indexes, extension state, custom SQL, and deployment order often sit at the edge of the model. That is where cross-environment parity breaks even when the migration run looks clean.
If a team does not label that boundary explicitly, it tends to over-trust green output from the tool and under-budget the manual proof work that still decides whether promotion is safe.
The Public Source Set Says The Boundary Is Still Moving
The evidence is not theoretical. Current public docs and issue threads still show coverage shifting across the PostgreSQL toolchain:
- Prisma's unsupported database features guidance still makes room for raw SQL and custom paths when the model is incomplete. Its public reference now describes partial-index support, but issue #29896 is a 2026 regression report showing that support and real promotion behavior can still diverge.
- Supabase's branch troubleshooting note on why a new branch does not copy the database the way teams expect and public discussions like #34270 and #45329 keep surfacing the same lesson: hosted-platform truth includes boundaries the app schema alone does not capture.
- Atlas expanded PostgreSQL permission coverage in 2026 for functions, procedures, and materialized views and then for sequences. That is useful progress, but it also proves permission modeling is an actively moving surface rather than a solved constant.
- Liquibase Secure's 5.2.1 release notes call out PostgreSQL dependency-ordering fixes. If ordering fixes are shipping in the release notes, ordering is still part of the release risk, not just an implementation detail.
- PostgreSQL's own docs on privileges and partial indexes remain the final reference point for what the estate can express, regardless of how much of that surface a migration tool models directly.
The point is not that one vendor is uniquely flawed. The point is that the model boundary is real, dynamic, and often visible in first-party documentation before it becomes visible in a failed promotion.
The Five Proof Jobs Teams Should Require Before Promotion
Serious teams should ask five explicit questions before they let a passed diff stand in for release truth:
- Which privileges and roles are first-class in the modeled workflow? If the answer stops at tables and columns, the release gate is incomplete.
- Which schemas or objects are platform-managed? Hosted platforms, reserved namespaces, and generated objects should be labeled before replay starts, not after verification breaks.
- Which advanced objects still fall back to custom SQL or partial support? Partial indexes, predicates, extensions, and procedural edges are exactly where false confidence accumulates.
- What happens to raw SQL at review time? A tool escape hatch is useful, but it is not proof by itself. The gate needs to reason about what escaped the model.
- Where is dependency and environment parity checked? If the order of creation, grants, or fixtures still changes by environment, promotion safety has not been proven yet.
That set of questions is the schema-model boundary review. Most teams do pieces of it informally. Fewer teams make it an explicit release artifact. That difference is where avoidable release debt begins.
What DataCat Treats As The Record
DataCat's job in this lane is not to pretend the modeled schema is the whole estate. It is to keep a reviewable record around the migration:
- source inventory and extracted evidence
- execution artifacts and validation output
- unresolved exceptions and handoff notes
- the boundary between automated output and operator-reviewed proof
That is the same operating discipline behind PostgreSQL Cutover Proof Before Reopening Writes and application-readiness maps before agent touchpoints. A clean run matters. A clean record of what the run did not prove matters more.
Executive Implication
The budget question is not whether the schema tool ran.
The budget question is whether the team can say, in one page, which parts of the target estate were:
- modeled directly
- owned by the platform
- carried through raw SQL or custom steps
- verified for parity before promotion
- still left to operator judgment
If the team cannot answer that cleanly, the migration has probably created release debt even if the demo environment looks healthy.
The next operator question is simple:
What part of this PostgreSQL estate still sits outside the modeled surface, and where is that proof recorded before promotion?
That question is better than another green screenshot. It is also closer to what production review will ask anyway.