Source: guides/schema_evolution.md

Generated automatically from the published contract sources.

Source path: guides/schema_evolution.md.

Contract text

Schema Evolution — the served guide

This guide explains database schema changes for coding agents and their users. Its instructions derive from the requirements it cites; it declares no requirements of its own (CTX-06; CHI-L0-13).

An application can invoke the current database package's migration function before it starts serving; merely including migration files does not run them. The development operation names below describe work to implement with your project's tooling; they are not installed Turn Zero Cloud CLI commands. The platform migration and snapshot actions described under Production are planned, not available in the current build.

The discipline

Schema changes are migration files. Keep each database schema change in an ordered, versioned migration file in the application's repository. Apply the files in order. Once production has started a version carrying a migration, never edit it; write a new migration for the next change, and edit an earlier one only as the next paragraph allows. The planned platform migration action associates the applied migration set with an environment's backend version (PLD-L0-55).

When a file may still be edited. A file is applied in a database once that database's schema_migrations table records its name, and the migration function never runs a recorded name again, so an edit to it is skipped. Edit a file freely until a database records it. A file only the development database has applied may still be edited until production starts a version carrying it, at the promote with two environments or at the deploy with one. Edit it, then clear the development database with clear_development_database, so the next start applies the edited file (DBS-L0-10). Once production has started a version carrying the file, a failed deploy included, never edit or rename it; write a new migration instead.

Identify destructive changes. Identify migrations that can remove or rewrite data, such as dropping a table or column, narrowing a type, or rewriting rows. Explain the expected data loss before running one. Marking a file destructive does not make the current startup migration runner request browser approval or take a snapshot. Verify the target database and arrange the required backup before applying it.

The development commands

CHI-L0-13 describes six development operations. Provide them through the application's chosen database tooling, and document the actual commands in that application's development instructions:

migrate — apply pending migrations to the development database.
reset — rebuild the development database by replaying all migrations. This deletes its existing data; verify the database connection before running it.
seed — load a known development data set, usually after a reset.
status — report which migrations are applied and which remain pending.
diff — compare the database schema with the intended schema and draft a migration for the differences. Review the generated SQL before applying it.
snapshot — create a restorable copy before a risky change, using the backup tools available for that database.

A local run reads the development environment file, which the turnzero-cloud command's provision line writes for the development environment, so it reaches the development database and never the production database (PLD-L0-40). A reset or a seed run locally therefore changes development data alone. Point these commands at the development connection string alone. The platform never answers the production connection credential to an author (SEC-L0-07).

Production

Current behavior. The application must invoke the database package's migration function before it begins serving, following the package's integration instructions (DBS-L0-06; DB-L0-03). The function applies pending files in order and commits each file separately. It runs against the database of the environment the process serves: the development database at a development deploy or a local run, and the production database when a promoted version, or a one-environment application's production deploy, starts in production (PLD-L0-96; PLD-L0-43). If a later file fails, earlier successful files remain applied, and the application must refuse to serve. Reverting the deployment artifact does not undo those database changes. Review each migration and its recovery procedure before deployment.

Planned migration action. PLD-L0-56 specifies apply_migration: pause traffic in a declared maintenance state, take a pre-migration snapshot, apply pending migrations, increment the backend version, and resume with the matching client promoted atomically. It also specifies recovery on failure. The action is not registered in the current build; do not instruct a user to call it or rely on these safeguards today.

Client handshake. SVC-L0-11's handshake is served for the native clients a realm declares (ACS-L0-15). The client sends x-turnzero-cloud-client: <client_id>/<version> on each request, and the router refuses a version below the client's minimum_version with 426 client_upgrade_required, naming the minimum and the update_url. Every application response carries x-turnzero-cloud-version, the serving deploy version. Before a schema change an installed client cannot survive, read each client's versions_seen through read_realm, then raise its minimum_version with configure_realm, whose warnings name the versions in use that the raise refuses. A request without the header is never refused, so keep a web client and any undeclared client compatible through the application's tests. The current migration runner does not perform the planned backend version increment (PLD-L0-55).

Rollback and restore. PLD-L0-57 distinguishes promoting an older artifact within the same backend version from changing the database version. roll_back is registered in the current build: it is a promote of an earlier deployed version, it moves code only, and it takes no snapshot and changes no data (PLD-L0-43; PLD-L0-63). Across a data-model change, the user chooses between restoring a pre-migration copy taken with the application's own database tooling, which discards later writes, and applying a separately authored down-migration. The platform's restore_snapshot action and the promote-time snapshot are not registered in the current build. Explain the data effects and use a verified recovery procedure appropriate to the implemented database tooling.

Exact source Markdown

# Schema Evolution — the served guide

This guide explains database schema changes for coding agents and their users. Its instructions derive from the requirements it cites; it declares no requirements of its own (CTX-06; CHI-L0-13).

An application can invoke the current database package's migration function before it starts serving; merely including migration files does not run them. The development operation names below describe work to implement with your project's tooling; they are not installed Turn Zero Cloud CLI commands. The platform migration and snapshot actions described under Production are planned, not available in the current build.

## The discipline

**Schema changes are migration files.** Keep each database schema change in an ordered, versioned migration file in the application's repository. Apply the files in order. Once production has started a version carrying a migration, never edit it; write a new migration for the next change, and edit an earlier one only as the next paragraph allows. The planned platform migration action associates the applied migration set with an environment's backend version (PLD-L0-55).

**When a file may still be edited.** A file is applied in a database once that database's `schema_migrations` table records its name, and the migration function never runs a recorded name again, so an edit to it is skipped. Edit a file freely until a database records it. A file only the development database has applied may still be edited until production starts a version carrying it, at the promote with two environments or at the deploy with one. Edit it, then clear the development database with `clear_development_database`, so the next start applies the edited file (DBS-L0-10). Once production has started a version carrying the file, a failed deploy included, never edit or rename it; write a new migration instead.

**Identify destructive changes.** Identify migrations that can remove or rewrite data, such as dropping a table or column, narrowing a type, or rewriting rows. Explain the expected data loss before running one. Marking a file destructive does not make the current startup migration runner request browser approval or take a snapshot. Verify the target database and arrange the required backup before applying it.

## The development commands

CHI-L0-13 describes six development operations. Provide them through the application's chosen database tooling, and document the actual commands in that application's development instructions:

- **migrate** — apply pending migrations to the development database.
- **reset** — rebuild the development database by replaying all migrations. This deletes its existing data; verify the database connection before running it.
- **seed** — load a known development data set, usually after a reset.
- **status** — report which migrations are applied and which remain pending.
- **diff** — compare the database schema with the intended schema and draft a migration for the differences. Review the generated SQL before applying it.
- **snapshot** — create a restorable copy before a risky change, using the backup tools available for that database.

A local run reads the development environment file, which the turnzero-cloud command's `provision` line writes for the development environment, so it reaches the development database and never the production database (PLD-L0-40). A reset or a seed run locally therefore changes development data alone. Point these commands at the development connection string alone. The platform never answers the production connection credential to an author (SEC-L0-07).

## Production

**Current behavior.** The application must invoke the database package's migration function before it begins serving, following the package's integration instructions (DBS-L0-06; DB-L0-03). The function applies pending files in order and commits each file separately. It runs against the database of the environment the process serves: the development database at a development deploy or a local run, and the production database when a promoted version, or a one-environment application's production deploy, starts in production (PLD-L0-96; PLD-L0-43). If a later file fails, earlier successful files remain applied, and the application must refuse to serve. Reverting the deployment artifact does not undo those database changes. Review each migration and its recovery procedure before deployment.

**Planned migration action.** PLD-L0-56 specifies `apply_migration`: pause traffic in a declared maintenance state, take a pre-migration snapshot, apply pending migrations, increment the backend version, and resume with the matching client promoted atomically. It also specifies recovery on failure. The action is not registered in the current build; do not instruct a user to call it or rely on these safeguards today.

**Client handshake.** SVC-L0-11's handshake is served for the native clients a realm declares (ACS-L0-15). The client sends `x-turnzero-cloud-client: <client_id>/<version>` on each request, and the router refuses a version below the client's `minimum_version` with 426 `client_upgrade_required`, naming the minimum and the `update_url`. Every application response carries `x-turnzero-cloud-version`, the serving deploy version. Before a schema change an installed client cannot survive, read each client's `versions_seen` through `read_realm`, then raise its `minimum_version` with `configure_realm`, whose `warnings` name the versions in use that the raise refuses. A request without the header is never refused, so keep a web client and any undeclared client compatible through the application's tests. The current migration runner does not perform the planned backend version increment (PLD-L0-55).

**Rollback and restore.** PLD-L0-57 distinguishes promoting an older artifact within the same backend version from changing the database version. `roll_back` is registered in the current build: it is a promote of an earlier deployed version, it moves code only, and it takes no snapshot and changes no data (PLD-L0-43; PLD-L0-63). Across a data-model change, the user chooses between restoring a pre-migration copy taken with the application's own database tooling, which discards later writes, and applying a separately authored down-migration. The platform's `restore_snapshot` action and the promote-time snapshot are not registered in the current build. Explain the data effects and use a verified recovery procedure appropriate to the implemented database tooling.