Switch to Netlify Database

Switching to Netlify Database means adopting the workflow opinions that come with it — especially that migrations drive your schema and deploys drive your cutover. This guide describes the shape of the switch; the exact commands you run depend on your source database and your application stack.

This guide covers switching from any Postgres source — an external Neon account, Supabase, RDS, a self-managed instance, or the legacy Neon extension (@netlify/neon). Where the legacy extension differs, we call it out inline.

A simplified path

This guide trades a small data-loss risk for a much simpler cutover. The export-and-import step in Phase 3 takes a few minutes for most projects; any writes to the source during that window will not make it across. High-traffic applications that can’t tolerate that should plan a maintenance window or a dual-write strategy, both of which are outside the scope of this guide.

Why switch?

The new Netlify Database experience offers:

• Branches that mirror production, on demand. Every deploy preview gets its own database branch forked from production data — there’s no staging database to keep in sync.
• Schema and code ship together. Migrations apply at the right point in the deploy lifecycle, so the database never falls out of step with the application that depends on it.
• Safe collaboration by default. Production is shielded from previews and agent runs, so experimentation can’t corrupt live data.
• Native to the platform. Provisioning, connection strings, credentials, and branches are all part of your Netlify project — no separate dashboard or out-of-band keys.
• Built for AI agents. Branches provide isolated environments for previewing database changes before publishing to production. When you use Agent Runners to make database changes, only someone on your team with the right permissions can publish to production. When you work with Netlify Database locally this setup can still reduce the likelihood of an AI agent accessing your production database.

The approach

The switch follows the same opinions as the rest of Netlify Database:

• Migrations drive your schema. Even if your current database was managed outside of a migration workflow, you’re adopting one now.
• Preview branches rehearse production changes. You’ll prove the full cutover on a preview deploy before touching production.
• Deploys drive the cutover. Production moves when a deploy ships.
• Rollback is always a revert. Each phase is independently reversible.

The switch happens across three phases. Your source database keeps serving production traffic until the final phase, so you can abandon or roll back at any earlier point without user-visible impact.

Prerequisites

• A linked Netlify project currently serving from an existing Postgres database
• The latest version of Netlify CLI installed and authenticated
• pg_dump and pg_restore available locally, with versions that match your source server
• Recommended: install the netlify-database skill into your coding agent — see Netlify Skills

Phase 1 — Provision the new database

The goal of Phase 1 is to bring Netlify Database online alongside your source database, without changing any application code. When this phase is done, the new database exists and has your schema, but no traffic is hitting it yet.

Coming from the legacy Neon extension?

@netlify/database and @netlify/neon use different environment variables and will not conflict. Keep @netlify/neon installed and the extension configured throughout the switch — cleanup happens at the end.

On a new branch:

1. Run netlify database init to install @netlify/database and verify the database is reachable. When the command asks if you want to create sample data, decline — you’ll create your own baseline migration in the next step instead:

   netlify database init

2. Create an empty baseline migration with netlify database migrations new:

   netlify database migrations new -d baseline

3. Populate the new migration’s migration.sql file with the current shape of your source database. The fastest way is a schema-only export:

   pg_dump --schema-only --no-owner --no-privileges "$SOURCE_DATABASE_URL"

   What matters is that running this migration against an empty database leaves it with the right shape. If you already have Drizzle migrations, skip the migrations new step, point drizzle-kit at netlify/database/migrations/ (see Tooling), and move your existing migrations in instead.

4. Push the branch. Netlify detects @netlify/database, provisions a preview database branch, and applies your baseline migration. The preview goes live still serving from the source database — your app code hasn’t changed yet.

5. Confirm the baseline applied cleanly on the preview branch:

   netlify database status --branch <preview-branch>

6. Merge the branch. Netlify provisions the production database branch and applies the baseline migration there too. Production still serves from the source.

If the baseline migration fails on the preview, the deploy preview fails and production is unaffected. Iterate on the migration until a clean preview deploy confirms your schema is reproducible from nothing.

Phase 2 — Swap the code and rehearse on a preview

The goal of Phase 2 is to have the new production code working against Netlify Database, proven against a real preview deploy with real data.

On a new branch:

1. Update your application code to read and write through @netlify/database. Wire Drizzle to the native Netlify Database adapter:

   db/index.ts

   import { drizzle } from "drizzle-orm/netlify-db";
   import * as schema from "./schema";
   
   export const db = drizzle({ schema });

   Coming from the legacy Neon extension?

   Replace import { neon } from "@netlify/neon" and any direct calls to neon() with the Drizzle adapter above. The NETLIFY_DATABASE_URL environment variable from the legacy extension is no longer used.

   Not using Drizzle?

   The same flow works with any Postgres-compatible driver — see Tooling for examples using pg or postgres with getConnectionString().

2. Push the branch. Netlify creates a preview deploy with its own preview database branch, forked from the (empty) production Netlify Database.

3. Get the preview branch’s connection string with credentials:

   netlify database status --branch <preview-branch> --show-credentials

4. Copy a snapshot of data from your source database into the preview branch. The schema is already in place from Phase 1, so dump and restore data only:

   pg_dump -Fc --data-only "$SOURCE_DATABASE_URL" | pg_restore --no-owner --no-acl --dbname="$PREVIEW_DATABASE_URL"

5. Exercise the preview URL. Click through reads and writes. Validate the critical flows of your application end-to-end.

6. If something’s off, iterate on the branch and push again. Each push gets a fresh preview branch, so you can re-rehearse until the path is clean.

The rehearsal is the core of this flow. By the time the preview looks right, you’ve proven both the code swap and the data move against a real deployed environment. The production cutover is a re-run of a path you’ve already validated.

Phase 3 — Cut over production

When the rehearsal is clean, cut production over.

Brief data-loss window

Any writes to the source database between the export and the production deploy will not make it across. For most projects this window is a few minutes; high-traffic applications should plan accordingly.

1. Get the production database connection string with credentials:

   netlify database status --show-credentials

2. Export data from the source and import into the production Netlify Database:

   pg_dump -Fc --data-only "$SOURCE_DATABASE_URL" | pg_restore --no-owner --no-acl --dbname="$PRODUCTION_DATABASE_URL"

3. Merge the Phase 2 branch to trigger a production deploy. Once it completes, your app reads and writes through Netlify Database.

4. Confirm reads and writes against the new production database.

Rolling back

Each phase is independently reversible. Your source database keeps serving production traffic until the Phase 2 merge, so any rollback before that has no user-visible impact.

• Before merging Phase 2 — abandon the Phase 2 branch. Phase 1 left an empty Netlify Database behind a baseline migration; that’s harmless.
• After merging Phase 2 — revert the merge in the Netlify UI. The app redeploys with the previous code, which still reads from the source database. Keep the source running and its credentials live until you’ve had production on Netlify Database long enough to trust the switch.

Cleanup

Once production has been stable on Netlify Database for long enough to trust the switch:

1. Remove the source database client from your dependencies and any source connection strings from your Netlify environment variables.
2. Decommission the source database in its hosting provider.

Coming from the legacy Neon extension?

Run npm uninstall @netlify/neon, remove the Neon extension from your site under Extensions in the Netlify UI, and drop any remaining NETLIFY_DATABASE_URL references from your code and environment. Deploy once more to finalize the removal.

Next steps

• Migrations — deeper reference on the migration workflow
• Local development — develop against the embedded Postgres
• CLI reference — full list of netlify database commands