Migrations
Manage database schema changes with VibORM migrations
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:
# 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:
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 });
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) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
- Serialize your VibORM models into a schema snapshot
- Compare against the current database state (push) or previous snapshot (migrate)
- Generate database-specific DDL using the appropriate migration driver
- 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 |
| 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.
Next Steps
Push
Direct schema synchronization for development
Migrate
Authenticated migration history for production
Compared with Prisma and Drizzle
How the history, integrity, recovery, and push models differ
Storage Drivers
Where migration estate artifacts are stored
Migration Drivers
Database-specific DDL generation