# 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:

```bash
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](https://console.scribase.com/signup?utm_source=docs&utm_medium=docs&utm_campaign=scribase-migrate).
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](https://docs.scribase.com/docs/api/tokens.md)).

```bash
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:

```bash
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.

```bash
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

```bash
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`](https://docs.scribase.com/docs/api/imports.md). `--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

```bash
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`](https://docs.scribase.com/docs/cli/migrate.md)
  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

```bash
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`](https://docs.scribase.com/docs/api/imports.md) for the API shape.

## From Resend

```bash
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](https://docs.scribase.com/docs/concepts/mail.md).

## All flags

```bash
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](https://rithub.dev/caelum0x/scribase-migrate).

## Next

- [Hosted quickstart](https://docs.scribase.com/docs/hosted.md): the two values your app needs after the move
- [`scribase migrate`](https://docs.scribase.com/docs/cli/migrate.md): keep shipping migrations from the same folder
- [Imports API](https://docs.scribase.com/docs/api/imports.md): the endpoint behind the Supabase and Clerk sources
