---
title: Migration Runtime
description: Understand db.migrate behavior, tracking, and failure semantics.
---

# Migration Runtime

`db.migrate()` applies pending migrations from your schema in order.

## What `db.migrate()` does

- Ensures `__tsql_migrations` exists.
- Reads already-applied migration names.
- Compiles schema SQL from `schema.migrations`.
- Runs each pending migration inside its own transaction.
- Records migration name and timestamp after success.

If a migration fails, that migration transaction is rolled back and execution stops.

## Operational usage

- Preferred: run in CI/deploy bootstrap step.
- Monolith: run once during startup before serving traffic.
- Safe to call repeatedly; applied migrations are skipped.

## Example bootstrap script

```ts
import { db } from "../src/db";

await db.migrate();
```

## DML in migrations

Use migration queries directly in the migration callback:

```ts
export const schema = defineDatabase((db) =>
	db
		.migration("001_create_users", (schemaBuilder) =>
			schemaBuilder.createTable("users", (t) => ({
				id: t.text().primaryKey(),
				email: t.text().notNull(),
			})),
		)
		.migration("002_uppercase_user_ids", (migration) =>
			migration
				.update("users")
				.set(({ users }) => ({
					id: users.id.upper(),
				}))
				.execute(),
		),
);
```

The same callback can mix schema and data steps in sequence.

Each migration runs in a transaction, so failures roll back cleanly; rerunning `db.migrate()` resumes from the first migration that has not been recorded yet.

<!--
Sitemap

URL: https://tsql-docs.pages.dev/v0.5.0/guides/quickstart.md
Title: Quickstart
Description: Define migrations, run them safely, and write typed SQL in application code.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/connecting.md
Title: Connecting
Description: Create a database instance from schema, dialect, and runtime connection.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/dialect-and-compilation.md
Title: Dialect & SQL Compilation
Description: Configure SQL dialect behavior and compile schema/query SQL.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/grouping-and-aggregates.md
Title: Grouping & Aggregates
Description: Use groupBy, having, and aggregate helpers for analytical queries.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/joins-and-aliases.md
Title: Joins & Aliases
Description: Join tables, use left joins, and self-join safely with aliases.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/migration-runtime.md
Title: Migration Runtime
Description: Understand db.migrate behavior, tracking, and failure semantics.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/mutations.md
Title: Mutations
Description: Insert, update, and delete data with compile or execute.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/predicates-and-expressions.md
Title: Predicates & Expressions
Description: Use Expr methods, logical operators, null checks, and expression composition.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/raw-sql.md
Title: Raw SQL
Description: Use raw templates and expression templates when fluent APIs are not enough.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/schema-and-migrations.md
Title: Schema & Migrations
Description: Define tables, columns, and indexes with ordered migration history.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/select-basics.md
Title: Select Basics
Description: Build typed select queries with from, where, order, limit, and select.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/transactions.md
Title: Transactions
Description: Use explicit begin, commit, rollback, and await using for safety.

URL: https://tsql-docs.pages.dev/v0.5.0/reference/type-utilities.md
Title: Type Utilities
Description: Derive row, insert, and update types directly from schema.
-->