scribasedocs

Getting Started

Migrate from Supabase, Neon, Clerk or Resend

scribase-migrate is a small command-line tool that moves an existing setup onto Scribase: Postgres schema and data, users, storage and sending domains. Your source is only read, never changed.

It is version 0.1.1 and runs straight from its repository on Rithub, with nothing to install:

Terminal
npx --yes git+https://rithub.dev/caelum0x/scribase-migrate.git --version
# 0.1.1

Needs Node 20 or newer. On Node below 22.13 npm prints an EBADENGINE warning for the scribase SDK; the command still runs. With Bun, use bunx -p git+https://rithub.dev/caelum0x/scribase-migrate.git scribase-migrate in place of the npx part.

Before you start

  1. Create a Scribase account at console.scribase.com/signup.
  2. Sign in once from the terminal. scribase-migrate finds the same token the scribase CLI stores; SCRIBASE_ACCESS_TOKEN in the shell works too (how to create a token).
Terminal
npx scribase login

The resend source needs neither step: it only writes a JSON file.

To keep the commands below short, set a shell alias first:

Terminal
alias scribase-migrate='npx --yes git+https://rithub.dev/caelum0x/scribase-migrate.git'

Try it in a preview environment first

This creates an empty preview environment named try1 and moves your schema, data and users into it. A preview environment can be deleted afterwards; a production one cannot.

Terminal
scribase-migrate neon \
  --to <org>/<project>/try1 --create-project --kind preview \
  --source-url "$DATABASE_URL" --migrate-auth-users

Add --dry-run to any command to see the plan without applying anything. Add --out result.json to keep the full result.

What a run looks like

Real output from 2026-11-17: a Postgres 16 database with 2 users, 2 profiles and 3 notes, moved into a brand-new Scribase preview environment. Project creation included, the whole run took 35 seconds.

  exporting auth.users rows
  auth.users: 2 rows, applied=true
  dumping public schema
  public schema: 0 lint findings, applied=true
  dumping public data
  public data: applied=true

Full result also written to run1.json

From the JSON result of the same run, with --verify-row-counts public.profiles --verify-row-counts public.notes:

JSON
"rowCounts": [
  { "table": "public.profiles", "sourceRows": 2, "targetRows": 2, "match": true },
  { "table": "public.notes", "sourceRows": 3, "targetRows": 3, "match": true }
],
"rlsDecisions": [
  { "schema": "public", "table": "notes", "kind": "join", "detail": "profile_id -> public.profiles.id -> id = auth.uid()" },
  { "schema": "public", "table": "profiles", "kind": "direct", "detail": "id = auth.uid()" }
]

A migrated user then signed in on the new environment with their old password. Running the same command a second time applied nothing and wrote no new files.

What moves

Source Postgres schema and data Users and passwords Storage
Supabase yes yes, password hashes kept yes
Neon (or any Postgres) yes yes, if the database has its own auth.users table no
Clerk no yes, each with a new one-time password no
Resend no no no (sending domains and broadcasts, exported to a file)

From Supabase

Terminal
scribase-migrate supabase \
  --to <org>/<project> --create-project \
  --source-ref <project-ref> \
  --source-url "postgres://postgres:<password>@db.<project-ref>.supabase.co:5432/postgres" \
  --source-service-key "<service_role key>" \
  --verify-login-email you@example.com

Moves Postgres, auth.users with password hashes intact (existing passwords keep working) and every storage bucket and object, in one request to POST /v1/imports. --verify-login-email has Scribase check that the user can still sign in before the migration reports success. --no-storage skips buckets.

From Neon or any Postgres

Terminal
scribase-migrate neon \
  --to <org>/<project> \
  --source-url "postgres://<user>:<password>@ep-xxx.<region>.aws.neon.tech/neondb" \
  --migrate-auth-users \
  --verify-row-counts public.profiles

Needs pg_dump on your machine. Moves the app schema and data, then compares row counts for each table you name.

  • Row-level security is written for you. Scribase blocks a new public table that has no row-level security. For each table the tool looks for an owner column (a foreign key to auth.users, directly or one join away) and writes an owner policy. A table with no provable owner is locked to the service-role key until you write a policy. Nothing is opened to everyone.
  • Branches. Add --branch staging=<connection-string> (repeatable); each branch lands in its own branch_<name> schema.
  • Other schemas. Add --schema <name> (repeatable; default public).
  • Commit the folder it writes. The run writes supabase/migrations/ in the current directory, the same folder scribase migrate reads. Run the tool from your app repository and commit that folder: the next run needs it. If an environment already has migrations that are not in the folder, the tool stops with 409 migration_conflict and tells you to run from the folder that holds them or pick a new environment.

From Clerk

Terminal
scribase-migrate clerk --to <org>/<project> --secret-key <sk_live_...>

Creates each Clerk user on Scribase with a one-time password and marks them password_reset_required. Clerk's API does not return password hashes on any plan, so every migrated user needs a password reset; the result lists exactly who. --dry-run lists the users it would create and creates none.

The same import runs from the console: Organization → Imports → New import → Clerk. See POST /v1/imports for the API shape.

From Resend

Terminal
scribase-migrate resend --api-key <re_...> --out resend-export.json

Exports every sending domain (with its DNS records) and every broadcast to a JSON file. No Scribase account is needed. Scribase does not import this file automatically yet: use it to re-create the domains on Scribase Mail.

All flags

Terminal
scribase-migrate --help
Flag Meaning
--to <org>/<project>/<environment> Destination. The environment defaults to production.
--create-project Create the project and environment first if missing.
--region <region> Region for --create-project (default us-east).
--kind <kind> Environment kind for --create-project: preview, staging or production (default production).
--dry-run Plan only, write nothing.
--out <path> Also write the full JSON result to a file.
--json Print only the JSON result.

scribase-migrate project-info --to <org>/<project>/<environment> prints the destination's API URL and public key. Secrets stay hidden unless you pass --reveal-secrets.

What has been run for real

  • Neon / plain Postgres: run end to end against a live Scribase organization, including project creation, generated row-level security passing the migration lint, row-count checks, a password sign-in on the destination, --dry-run, and a second run that changed nothing.
  • Resend: reaches the real Resend API; a full export has only been checked against the documented API shape.
  • Supabase: the request reaches the real import API and bad input is rejected cleanly; a full import of a real Supabase project has not been run with this tool yet.
  • Clerk: reaches the real Clerk API and rejects a bad key cleanly; a full run against a real Clerk instance has not been done with this tool yet.

Source and issue tracker: rithub.dev/caelum0x/scribase-migrate.

Next