Why does a GraphQL schema generated from database tables turn storage refactors into client breakages?

## One shape doing two jobs A published GraphQL schema and a database schema answer different questions. The database schema answers "how do we store this efficiently and consistently?" — and the right answers change as volume, access patterns and correctness requirements change. The published schema answers "what may a client ask for, and what will it get back?" — and the right answer there is supposed to stay still, because other people's code depends on it. Generating one from the other collapses two shapes into one. The field name is the column name; the field type is derived from the column type; the field's nullability is derived from the column's. Regeneration is not a build step, it is a *publication*: whatever the table says today becomes what clients are told today. That is the whole mechanism, and it is worth stating that plainly in an interview before listing examples, because the examples are only interesting once the mechanism is clear. ## The refactors that leak Using a job-board graph, with `applications` as the table underneath an `Application` type: * **Rename.** `status` becomes `state` for clarity. Regeneration removes a field and adds another. Every document selecting `status` now fails validation. * **Split into a lookup table.** The status string is normalised into `application_states` with a foreign key. The scalar field disappears; something object-shaped or integer-shaped appears in its place. * **Widening for a backfill.** A column is made nullable so a migration can run in stages. The generated field goes from Non-Null to nullable, and every client that assumed a value now has to handle a hole it never planned for. * **Denormalisation.** A counter is cached on the row for performance. A field appears that nobody designed, and a client starts selecting it, and now the cache is public API. * **Moving storage.** The table moves to another service or another store entirely. There was never a contract to preserve — only a table — so the port is a rewrite of the surface. None of these are database mistakes. They are ordinary, correct storage engineering, and a mirrored schema converts each into an API event. ## A worked failure An employer dashboard on the job-board graph opens a subscription for application status changes and paints a live board of candidates by stage. The storage team normalises the status column into a lookup table — a clean, well-reviewed migration with a backfill. The schema regenerates: `Application.status` is gone, `Application.stateId` has appeared. On the next connect, the dashboard's subscription document is rejected at validation with `Cannot query field "status" on type "Application"`. The dashboard, like a great many clients, treats a failed subscription as a transient network problem: it renders whatever it last had and retries quietly. Nothing turns red. Recruiters keep looking at a board that has stopped moving, and the gap is noticed 41 hours later when a candidate phones about an interview the board still shows as unscheduled. Two lessons sit in that story. The obvious one is the coupling. The subtler one is that a schema change reaches a subscription at *reconnect*, not at deploy, so the blast radius of a regenerated schema is spread across hours and looks like flakiness rather than a release. ## Where the mapping should live The fix is not "never rename a column" — that just pins the database to API vocabulary and makes the coupling bite from the other side, so the storage team inherits the API's compatibility rules. The fix is to have somewhere for the difference to live. In a hand-designed schema there are three artefacts: the published contract, the storage shape, and a mapping layer between them that belongs to the API team and is not published to anyone. When the status column splits into a lookup table, the mapping learns to read the new place, translate the row into the existing `JobApplicationStatus` enum, and hand back exactly what the contract always said. Clients see nothing. When the backfill needs the column nullable, the mapping supplies a defined value for the gap rather than passing a hole through to the contract. When the table moves to another service, the mapping changes shape and the contract does not. That layer is not free — it is code, it needs tests, and it has to be maintained as the storage drifts. But its cost is paid by one team, once, in a place they control, instead of being distributed to every consumer as a coordinated release. ## What is safe, even with generation Be fair about the other side. Adding a column is usually additive and harmless to existing documents, which is why generated schemas feel fine for months: most days you add, and adding does not break. The trouble is that generation also publishes every addition — audit columns, soft-delete flags, internal scoring — so the schema accretes fields nobody designed and now cannot remove, because a client somewhere may have found them. The failure mode is not only the loud break at a rename; it is the quiet growth of a contract nobody ever agreed to.