scribase migrate

Sends a set of migrations to the control-plane API for a specific environment. Without --apply the server lints and plans only — run it that way first to catch issues before they touch data. With --apply the lint must pass before the migrations execute.

Usage

# From a migrations directory (recommended)
scribase migrate <org> <project> <env> --dir ./migrations [--apply]

# From a pre-built migrations JSON file
scribase migrate <org> <project> <env> <migrations.json> [--apply]

Migrations directory format

Scribase discovers .sql files in the directory. Two naming shapes are supported:

migrations/
├── 001_init.sql            # up-only migration
├── 002_add_users.up.sql    # up migration
├── 002_add_users.down.sql  # paired down migration (optional)
├── 003_indexes.sql

Files are ordered by their numeric prefix. The version is the digits before the first _; the name is everything after. Requirements:

• The version prefix must be positive digits.
• The name must not be empty.
• No two files may share the same version.
• A .down.sql file must have a matching .up.sql.
• Files must not be empty.

Migrations JSON format

The JSON file must contain an array. Each element:

{
  "version": "1",
  "name": "init",
  "up": "CREATE TABLE ...",
  "down": "DROP TABLE ..."
}

"down" is optional.

Options

Example

# Lint first — review the plan before applying
scribase migrate acme store production --dir ./migrations

# Apply after review
scribase migrate acme store production --dir ./migrations --apply

Notes

• Migrations are sent to POST /v1/organizations/{org}/projects/{project}/environments/{env}/migrations.
• The server returns a lint report. Review findings before running with --apply.
• The migration runner is idempotent by version. Re-sending an already-applied version is a no-op.
• --apply is false by default — this is intentional. Always review the plan on the first run.
• To capture changes made directly on a database back into this directory, use scribase db pull.