---
title: Migrations
description: Manage database schema changes with VibORM migrations
icon: database
---

VibORM provides two approaches for managing database schema changes:

- **Push** — history-free live schema synchronization, ideal for development
- **Migrate** — an authenticated, version-controlled estate, intended for production

Push compares your VibORM models with the live database. Migrate compares the
desired schema snapshot with an authenticated parent state, publishes that
transition, and separately verifies the live database when it applies it.

## Choose Your Approach

| | Push | Migrate |
|--|------|---------|
| **Use case** | Development, prototyping | Production, team collaboration |
| **Version control** | No history artifacts | Yes, state manifests, snapshots, and reviewed SQL blobs committed to Git |
| **Rollback** | Manual | `down()` executes the stored down artifact, honouring each migration's persisted rollback policy |
| **Production CI/CD** | Not recommended | Fully supported |

## CLI vs API

VibORM migrations can be used via the **CLI** or programmatically via the **Migration Client API**.

### CLI

The CLI is the recommended way to manage migrations during development:

```bash
# Push schema directly to database
npx viborm push

# Publish a new migration state
npx viborm migrate generate --name add-users

# Apply pending migrations
npx viborm migrate apply

# Check migration status
npx viborm migrate status
```

### Migration Client API

For programmatic control (scripts, CI/CD, custom tooling), use the migration client:

```ts title="src/db/migrations.ts"
import { createMigrationClient } from "viborm/migrations";
import { createFsStorageWriter } from "viborm/migrations/storage/fs";
import { client } from "./client";

const migrations = createMigrationClient(client, {
  storage: createFsStorageWriter("./migrations"),
});

await migrations.generate({ name: "add-users" });
await migrations.apply();
await migrations.status();

const preview = await migrations.push({
  dryRun: true,
  resolve: async (change) => {
    if (change.type === "destructive") {
      return change.proceed();
    }
    if (change.type === "ambiguous") {
      // Rename columns. Name a table pair explicitly before renaming a table.
      return change.operation === "renameColumn"
        ? change.rename()
        : change.reject();
    }
    if (change.isNullable) {
      return change.useNull();
    }
    return change.reject();
  },
});

await migrations.push({ consent: preview.consent });
```

:::info[Storage Required]
`generate` and `reset` require a storage writer. `check`, `list`, `show`,
`graph`, `status`, `verify`, `apply`, `down`, `baseline`, and `resolve` require
a storage reader. `log` reads the database ledger and `push` is history-free,
so neither reads estate storage.
:::

`viborm/migrations` carries the migration driver of every dialect. To bundle
only one, import the same API from `viborm/migrations/postgres`,
`viborm/migrations/sqlite` or `viborm/migrations/mysql`. On Cloudflare Workers
this keeps the other dialects' migration code out of the Worker.

### Capability-Typed Clients

The returned client exposes only operations that its storage can support:

| Construction | Surface |
| --- | --- |
| `createMigrationClient(client)` | `push`, `log` |
| `createMigrationClient(client, { storage: reader })` | Adds estate inspection and application operations |
| `createMigrationClient(client, { storage: writer })` | Also adds `generate` and `reset` |

This keeps a storage-less deployment script from compiling a call that can
only fail with “storage required” at runtime.

## How It Works

Both push and migrate follow the same core process:

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  VibORM Schema  │ ──▶ │   Schema Diff    │ ──▶ │  DDL Generation │
│   (your code)   │     │  (detect changes)│     │ (database SQL)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
```

1. **Serialize** your VibORM models into a schema snapshot
2. **Compare** against the current database state (push) or previous snapshot (migrate)
3. **Generate** database-specific DDL using the appropriate migration driver
4. **Execute** the DDL (push) or publish authenticated estate artifacts (migrate)

## Atomicity

Migration atomicity is a DDL-specific guarantee and is not implied by support
for client transactions. VibORM admits effectful work only when the concrete
provider proves its marker compare-and-swap, execution boundary and migration
lock. PostgreSQL takes it in each migration transaction and SQLite through
`BEGIN IMMEDIATE`, and both read the marker under it before the first effect.
MySQL DDL is the documented stepwise exception because each statement commits:

| Driver | `push` | `migrate apply` |
|--------|--------|-----------------|
| **PGlite, pg, postgres.js, Bun SQL** | Transaction when every statement permits it | Same guarantee |
| **SQLite3, Bun SQLite** | Transaction (`BEGIN IMMEDIATE`, whose write lock is the migration lock) | Same, per group: a concurrent `apply` of the same state reads the first one's marker and reports `noop`, or refuses with `V11015`. Stepwise transitions are refused (`V11021`) |
| **MySQL2** | Stepwise — a failed run can leave earlier statements applied | Same limitation, with durable progress evidence |
| **Neon HTTP** | Refused: no session; dry-run and read-only paths remain | One request per transactional group, which takes the lock and asserts the marker, the checks and the destination digest in SQL. Stepwise transitions refused (`V11021`). See [Neon HTTP](/docs/drivers/postgresql/neon-http#migrations) |
| **PlanetScale, D1, libSQL** | Effectful work refused; dry-run and read-only paths remain | Effectful work refused until the provider boundary is proven |

On the atomic paths, a successful migration applies every statement and a
failed one applies none. The portable API exposes no transaction isolation
options.

## GeoPoint physical schema

`s.point()` has one migration representation per dialect: PostGIS
`geography(Point,4326)` with GiST, MySQL `POINT SRID 4326` with `SPATIAL INDEX`,
or SQLite's checked `VIBORM_GEO_TEXT` carrier. Introspection proves the exact
subtype, SRID, nullability, and legal index role; a generic JSON, geometry, or
built-in PostgreSQL point column is not treated as equivalent.

PostgreSQL generation records a PostGIS requirement without emitting `CREATE
EXTENSION`. Before live push/apply/down/reset effects, the pinned migration
session proves the exact PostGIS extension-owned types and functions that the
runtime SQL uses. MySQL spatial indexes require one non-null point. SQLite
refuses a spatial index before effects. See
[GeoPoint migrations](/docs/schema/scalars/point#migrations).

## Next Steps

**[Push](/docs/migration/push)**

Direct schema synchronization for development

**[Migrate](/docs/migration/migrate)**

Authenticated migration history for production

**[Compared with Prisma and Drizzle](/docs/migration/comparison)**

How the history, integrity, recovery, and push models differ

**[Storage Drivers](/docs/migration/storage)**

Where migration estate artifacts are stored

**[Migration Drivers](/docs/migration/drivers)**

Database-specific DDL generation
