# Migrate from Neon: a one-run import, or pg_dump and the serverless driver

> Move a Neon Postgres database to Scribase: one importer run for schema, data, RLS and verification, or pg_dump and scribase migrate by hand. Keep @neondatabase/serverless, add auth and storage.

Source: https://scribase.com/migrate/neon

One importer run copies the schema, data, RLS policies, grants, sequences and extensions from any Neon branch and proves the copy with a verification report — no pg_dump files to manage. Prefer doing it by hand instead? pg_dump the schema and data, apply the files as migrations, and point your driver at the new endpoint. Either way, branching, scale to zero and time travel come with you; auth, storage and realtime are added on the same Postgres.

## Before you start

- Your Neon connection string. For the import below, either the pooled or direct host works. For the manual pg_dump path, use the direct (non-pooled) host: pg_dump needs a session, not a transaction pooler. In the Neon console, turn off "Connection pooling" when you copy it for that path.
- A Scribase project. The console wizard needs nothing else; scripting the import with the SDK needs an API key (Account, API keys).
- pg_dump at the same major version as the source or newer (Scribase runs Postgres 17) — only needed for the manual path below.

## Option 1: the import wizard (recommended)

The Postgres importer is the generic counterpart to the Supabase one: paste your connection string into the console's import wizard and it moves schema, data, RLS policies, grants, sequences and extensions in one run, then proves the copy with the same fail-closed verification report every importer ends with (per-table row counts and checksums, policy parity). It runs server-side against the connection string you give it, so it works today even though public psql/pg_restore access into Scribase is still rolling out.

1. **Dry run** — Paste the connection string into the wizard and run the dry run. It reads the source only and writes nothing: the tables, rows and extensions that will move.

2. **Run it** — Confirm in the wizard. Extensions, schema, grants, data in resumable pages, foreign keys and triggers, then RLS policies, each step idempotent so a resumed run never duplicates a row.

3. **Point your code at Scribase** — Same as the manual path below: the environment answers GET /serverless with the connection URI and HTTP endpoint for @neondatabase/serverless.

## Option 2: pg_dump by hand

More manual, more control: dump the schema and data yourself and apply them as migrations. Useful for a schema-only move, or when you want to read and edit the SQL before it runs. Direct TCP connections into Scribase (pg_restore against a public host) are not open yet, so this path loads data through migrations instead; it suits databases up to a few gigabytes — for larger ones, use Option 1 above or contact us.

1. **Dump the schema** — Drop owners and grants: Scribase sets ownership itself, and the anon and authenticated roles get grants you choose.

```sh
export NEON_URL="postgresql://<user>:<password>@ep-<id>.<region>.aws.neon.tech/<db>?sslmode=require"
mkdir -p supabase/migrations
pg_dump "$NEON_URL" --schema-only --no-owner --no-privileges \
  --exclude-schema=neon_auth > supabase/migrations/0001_schema.sql
```

2. **Dump the data as INSERT batches** — The migration endpoint takes SQL statements, so use INSERT batches rather than COPY blocks.

```sh
pg_dump "$NEON_URL" --data-only --inserts --rows-per-insert=500 \
  --exclude-schema=neon_auth > supabase/migrations/0002_data.sql
```

3. **Check extensions** — List what the source uses and compare with the extensions directory. Add CREATE EXTENSION lines to the top of 001_schema.sql if pg_dump left them out.

```sql
select extname, extversion from pg_extension order by 1;
```

4. **Close every public table to API clients** — Neon databases rarely use row level security, but every Scribase project also serves its tables over REST, so the migration linter refuses a public table without RLS and at least one policy. Run this on Neon to write a migration that turns RLS on and adds a deny-all policy for API roles. Postgres does not apply RLS to the role that owns a table (unless FORCE ROW LEVEL SECURITY is set), so server code connecting as the owner is unaffected. Open tables to signed-in users later with real policies.

```sh
psql "$NEON_URL" -At > supabase/migrations/0003_rls.sql <<'SQL'
select format(
  'alter table public.%I enable row level security; '
  'create policy server_only on public.%I as restrictive for all '
  'to anon, authenticated using (false) with check (false);',
  tablename, tablename)
from pg_tables where schemaname = 'public' order by tablename;
SQL
```

5. **Lint, then apply** — With --dry-run the server lints and plans only; plain migrate applies. The linter also blocks grants to PUBLIC and SECURITY DEFINER functions; the --no-privileges dump above leaves grants out, and any SECURITY DEFINER function needs a rewrite or a review before it ships. Run this from the project folder, with the dumped files under supabase/migrations.

```sh
npx scribase migrate --dry-run
npx scribase migrate
```

6. **Point your code at Scribase** — The environment answers GET /serverless with the connection URI and HTTP endpoint for @neondatabase/serverless. Queries stay the same.

```ts
import { neon, neonConfig } from '@neondatabase/serverless'

neonConfig.fetchEndpoint = () => process.env.SCRIBASE_SQL_HTTP_ENDPOINT!
const sql = neon(process.env.DATABASE_URL!)
```

## If you used Neon Auth or the Data API

- Users sync: Scribase keeps neon_auth.users_sync in step with its own users table, so queries that join it keep working.
- Bring your own JWT: list your issuer and REST accepts its tokens; your RLS policies read the claims as before.
- Data API: postgrest-js with only a bearer token works unchanged against the project REST URL.

## Verify the copy

Run the same count on both sides for the tables that matter, or compare a checksum of each table.

```sql
select 'orders' as t, count(*) from orders
union all select 'customers', count(*) from customers;

-- order-independent checksum of a table
select md5(string_agg(md5(o::text), '' order by md5(o::text))) from orders o;
```

## FAQ

**Do I need pg_dump at all, or can one command do it?**

Yes, the console's import wizard does it in one run: paste your Neon connection string and it moves schema, data, RLS policies, grants, sequences and extensions, plus a verification report. It runs server-side, so it does not need public psql/pg_restore access into Scribase. Use the manual pg_dump path below only if you want a schema-only move or to read the SQL before it runs.

**Can I use pg_restore with a custom-format dump?**

Not yet for a self-service pg_restore: public TCP access to Scribase databases is still being rolled out. The import wizard moves real data today without needing it (see above); for a hand-edited dump, plain SQL files applied as migrations work.

**Will branching work the same way?**

Branches are copy-on-write with their own URL and keys, can start from a past point in time, can mask columns, and can expire. The CLI commands differ: see the Postgres branching page.

**What happens to my Neon project?**

Both migration paths only read from Neon. Keep the Neon project running until your app has run on Scribase and the verification report or your own counts match.

## Related

- [Postgres migration guide](https://scribase.com/migrate/postgres)
- [Neon alternative](https://scribase.com/neon-alternative)
- [How Postgres branching works](https://scribase.com/postgres-branching)
- [Neon branch limit exceeded](https://scribase.com/neon-branch-limit-exceeded)
- [Scribase vs Supabase vs Neon](https://scribase.com/scribase-vs-supabase-vs-neon)
- [Postgres extensions available](https://scribase.com/extensions)
- [Migrate from Supabase](https://scribase.com/migrate/supabase)
- [Pricing](https://scribase.com/pricing)