---
title: "Source: guides/schema_evolution.md"
description: "Generated page for the indexed contract source guides/schema_evolution.md: its schema fields or contract text, and its published text."
slug: /reference/sources/guides/schema-evolution
order: 3
visibility: public
redirects_from: []
---

# Source: guides/schema\_evolution\.md

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

Source path: guides/schema\_evolution\.md.

## Contract text

### Schema Evolution — the served guide

This guide explains how you change a database schema\. 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, beside a hash of the file's content \(DB\-L0\-03\)\. A start that finds a recorded file edited fails before any file runs, naming the file, so an edit is never skipped in silence\. 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

Six development operations follow \(CHI\-L0\-13\)\. 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 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 returns the production connection credential to you \(SEC\-L0\-07\)\.

### Production

**Current behavior\.** The application applies its migration files before it begins serving, through the database package's migration function, following its integration instructions, or through its own code \(DBS\-L0\-06; DB\-L0\-03\)\. Its own code keeps the same convention: ordered files, a ledger table, and a transaction advisory lock taken inside each transaction it guards\. Either way, pending files apply in order and each file commits 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\.** The planned `apply_migration` action will 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 will also recover on failure \(PLD\-L0\-56\)\. The action is not registered in the current build: do not call it, tell anyone to call it, or rely on these safeguards today\.

**Client handshake\.** The client handshake is served for the native clients a realm declares \(SVC\-L0\-11; 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_app_sign_in`, then raise its `minimum_version` with `configure_app_sign_in`, 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\.** Promoting an older artifact within the same backend version is not the same as changing the database version \(PLD\-L0\-57\)\. `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, ask the account's owner to choose 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\.<br>

## Source Markdown

```text
# Schema Evolution — the served guide

This guide explains how you change a database schema. 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, beside a hash of the file's content (DB-L0-03). A start that finds a recorded file edited fails before any file runs, naming the file, so an edit is never skipped in silence. 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

Six development operations follow (CHI-L0-13). 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 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 returns the production connection credential to you (SEC-L0-07).

## Production

**Current behavior.** The application applies its migration files before it begins serving, through the database package's migration function, following its integration instructions, or through its own code (DBS-L0-06; DB-L0-03). Its own code keeps the same convention: ordered files, a ledger table, and a transaction advisory lock taken inside each transaction it guards. Either way, pending files apply in order and each file commits 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.** The planned `apply_migration` action will 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 will also recover on failure (PLD-L0-56). The action is not registered in the current build: do not call it, tell anyone to call it, or rely on these safeguards today.

**Client handshake.** The client handshake is served for the native clients a realm declares (SVC-L0-11; 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_app_sign_in`, then raise its `minimum_version` with `configure_app_sign_in`, 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.** Promoting an older artifact within the same backend version is not the same as changing the database version (PLD-L0-57). `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, ask the account's owner to choose 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.

```
