A migration engine that treats your schema as a ledger, not a hope.

1 · Add to the service

# srv-*/Cargo.toml
[dependencies]
lib-surrealdb-migrate = { path = "../lib-surrealdb-migrate" }

2 · Wire into your api_cli

use lib_surrealdb_migrate::{bootstrap, connect_surrealdb, MigrationRunner, MigrationCommands};

// bootstrap is special-cased: it runs at root, before init_db() USEs the ns/db.
if let MigrationCommands::Bootstrap { namespace, database } = &migrate_cmd {
    let db = connect_surrealdb(&surreal_url).await?;
    db.signin(Root { username: "root", password: "root" }).await?;
    bootstrap(&db, namespace, database).await?;
    return Ok(());
}

// normal path: init_db() connects + USEs the configured ns/db.
let db = init_db().await?;
let runner = MigrationRunner::new(db, "migrations");
runner.handle_command(migrate_cmd).await?;

3 · Run

cargo run -- migrate bootstrap development linkit
cargo run -- migrate up
cargo run -- migrate status

The Rust crate is the reference: the TypeScript and Gleam ports mirror its task IDs, exit-code taxonomy, and tracking schema.

1 · Install (JSR over the npm compat layer)

// package.json
"dependencies": {
  "@servicecute/surrealdb-migrate": "npm:@jsr/servicecute__surrealdb-migrate",
  "surrealdb": "^2.0.0"
}
# .npmrc
@jsr:registry=https://npm.jsr.io

2 · One-line CLI with dispatchArgv

// scripts/migrate.ts
import { MigrationRunner, dispatchArgv, connectSurrealdb } from "@servicecute/surrealdb-migrate";

const db = await connectSurrealdb(process.env.SURREAL_URL ?? "ws://localhost:8000/rpc", {
  username: process.env.SURREAL_USERNAME,
  password: process.env.SURREAL_PASSWORD,
  namespace: process.env.SURREAL_NAMESPACE,
  database: process.env.SURREAL_DATABASE,
});

const runner = new MigrationRunner(db, "migrations");
process.exit(await dispatchArgv(runner));

3 · Run

bun run migrate create add_user_table
bun run migrate up
bun run migrate status

bootstrap must run on a connection not yet use'd into the ns/db — call it directly in the host script, not through dispatchArgv.

1 · Add to gleam.toml

# gleam.toml
[dependencies]
lib_surrealdb = { path = "../lib-surrealdb" }
lib_surrealdb_migrate = { path = "../lib-surrealdb-migrate" }

2 · Bootstrap, then build a runner

import lib_surrealdb
import lib_surrealdb_migrate.{Up, default_up_args}

pub fn run_migrations(client: lib_surrealdb.Client) {
  // enforces namespace ∈ {production, staging, development}
  let assert Ok(Nil) =
    lib_surrealdb_migrate.bootstrap(client, namespace: "development", database: "my_app_db")

  let runner = lib_surrealdb_migrate.new(client, "./migrations")
  let assert Ok(Nil) =
    lib_surrealdb_migrate.handle_command(runner, Up(default_up_args()))
}

3 · The command sum type

pub type MigrationCommand {
  Init  Up(UpArgs)  Down(sudo, yes, to)  Redo(sudo, yes)
  Verify(backfill)  AcceptDrift(version, sudo)
  Plan(to)  Show(version)  Status(json)  Log
  Create(name)  List(all)  Drop(..)  DropAll(..)  Backup(..)  Restore(..)
}

Drift detection, targeted apply/rollback, preview and state visibility are all live. The P7 baseline verbs (stamp / squash / reinit / diff) are the remaining gap — the ledger's stamped column and a SchemaDiff error variant are already scaffolded for them.