Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

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)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
  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
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

Was this page helpful?