Netlify Database

Netlify Database is the managed Postgres product built into the Netlify platform. It is GA and is the default choice for any dynamic data in a Netlify project.

Install

@netlify/database

and Netlify auto-provisions a Postgres database for the site at deploy time. Each deploy preview gets its own isolated branch forked from production data. No Neon account, connection-string wiring, or claim flow — the database is a first-class Netlify primitive.

Database vs Blobs

Use Netlify Database for anything dynamic:

Any user-generated or app-generated records (posts, comments, orders, sessions, audit logs)
Structured data that will grow, be queried, or be joined
Key-value-style data read or written by application code at runtime

Use Netlify Blobs only for file and asset storage: images, documents, exports, uploads, cached binary artifacts. Do not use Blobs as a dynamic data store — reach for Database instead. See

netlify-blobs/SKILL.md

CRITICAL: Install Drizzle from the

@beta

dist-tag

The Netlify Database adapter for Drizzle ORM currently only exists on the

beta

release line of

drizzle-orm

. Install both

drizzle-orm

and

drizzle-kit

from the

@beta

dist-tag:

bash

npm install drizzle-orm@beta
npm install -D drizzle-kit@beta

The default

latest

versions do not include the

drizzle-orm/netlify-db

adapter and will fail. If

drizzle-kit generate

errors about being outdated, or the

drizzle-orm/netlify-db

import fails to resolve, the install is missing

@beta

The

@beta

tag only affects the installed version — imports are written as

drizzle-orm

drizzle-orm/pg-core

, and

drizzle-orm/netlify-db

without modification.

CRITICAL: Use the Netlify CLI for database operations

The CLI ships a complete database surface under

netlify database

(alias:

netlify db

) that replaces hand-rolled scripts and direct API/UI work. Reach for these commands first before writing custom tooling. Requires Netlify CLI 26.0.0+ — if a

netlify database

subcommand isn't recognized, run

npm install -g netlify-cli@latest

Full reference is in Netlify CLI commands below.

CRITICAL: Never apply migrations to a Netlify-hosted database

The only database you ever apply migrations to yourself is the local development DB. For any Netlify-hosted database — production or a deploy preview branch — Netlify applies migrations automatically during the deploy. Your job is to create migration files and commit them. The deploy does the rest.

This means:

Use

netlify database migrations apply

for the local DB. Do NOT run

drizzle-kit migrate

against

NETLIFY_DB_URL

in any context.

Do NOT run
```
drizzle-kit push
```
at all. Generate a migration and let the deploy apply it.
Do NOT run raw DDL (
```
CREATE
```
,
```
ALTER
```
,
```
DROP
```
,
```
TRUNCATE
```
) via
```
netlify database connect
```
,
```
psql
```
, or any other direct connection. Schema changes go through migration files; out-of-band DDL drifts the migration history from the actual schema.
Do NOT export
```
NETLIFY_DB_URL
```
from a preview or production context and run a client against it. Migrations drift the moment anything touches the schema out-of-band.

The one documented exception is a one-time data import during a provider switch — see

references/migration-from-extension.md

. Outside that specific flow, the rule is absolute: schema changes go through migration files, migration files get applied by the deploy.

Not the legacy "Netlify DB" extension

The older Netlify DB extension (Beta) is deprecated. It is a separate product and must not be confused with Netlify Database. Do not recommend or install it for new projects.

	Netlify Database (GA, recommended)	Netlify DB extension (deprecated Beta)
Package	`@netlify/database`	`@netlify/neon`
Env var	`NETLIFY_DB_URL`	`NETLIFY_DATABASE_URL`
Setup	`netlify database init` or install the package — auto-provisioned at deploy	Historically `netlify db init` on older CLI versions, with a claim into the user's Neon account; that flow is no longer reachable from the current CLI
Status	GA	Deprecated; new creation blocked as of April 2026

If an existing project is already using the

@netlify/neon

extension, keep it working and encourage the user to switch. See

references/legacy-extension.md

for recognition and coexistence, and

references/migration-from-extension.md

for the full switching process (also covers switching from other external Postgres providers).

Provisioning

The fastest path is

netlify database init

— an interactive setup that installs

@netlify/database

, lets the user pick Drizzle or raw SQL, writes

drizzle.config.ts

if needed, scaffolds a starter migration, applies it locally, and runs a sample query end-to-end:

bash

netlify database init           # interactive
netlify database init --yes     # accept defaults — for CI/agents

If you'd rather wire things up by hand, install the package directly:

bash

npm install @netlify/database

Either way, presence of

@netlify/database

in the dependency tree triggers provisioning on the next deploy. A database can also be created manually from the Netlify UI before first deploy.

Drizzle ORM (recommended path)

Drizzle is the recommended way to work with Netlify Database. Prefer Drizzle over writing raw SQL or hand-editing migration files — manual migrations are an edge case (see

references/migrations.md

Install

bash

npm install @netlify/database drizzle-orm@beta
npm install -D drizzle-kit@beta

Schema file

Create

db/schema.ts

. Define all tables here using Drizzle's schema builder.

typescript

// db/schema.ts
import { boolean, pgTable, serial, text, timestamp, varchar } from "drizzle-orm/pg-core";

export const items = pgTable("items", {
  id: serial().primaryKey(),
  title: varchar({ length: 255 }).notNull(),
  description: text(),
  isActive: boolean("is_active").notNull().default(true),
  createdAt: timestamp("created_at").defaultNow(),
  updatedAt: timestamp("updated_at").defaultNow(),
});

export type Item = typeof items.$inferSelect;
export type NewItem = typeof items.$inferInsert;

Use snake_case strings for column names (

"is_active"

"created_at"

) to match Postgres conventions. Drizzle variable names can be camelCase.

Drizzle client

Create

db/index.ts

. The adapter on

drizzle-orm/netlify-db

picks the right driver for the runtime automatically.

typescript

// db/index.ts
import { drizzle } from "drizzle-orm/netlify-db";
import * as schema from "./schema";

export const db = drizzle({ schema });

The connection is configured automatically — no connection string needed. If your project uses native ESM with

.js

extensions on relative imports (

from "./schema.js"

), keep that style consistent here.

Drizzle Kit config

Create

drizzle.config.ts

at the project root. Set

out

netlify/database/migrations

— that's the directory the deploy applies migrations from:

typescript

// drizzle.config.ts
import { defineConfig } from "drizzle-kit";

export default defineConfig({
  dialect: "postgresql",
  schema: "./db/schema.ts",
  out: "netlify/database/migrations",
  migrations: { prefix: "timestamp" },
});

Default to
migrations: { prefix: "timestamp" }
. Drizzle Kit's default sequential indices (

0000_

0001_

, …) collide whenever two pieces of work generate migrations in parallel — this happens to teams and to solo developers iterating on multiple branches. Timestamp prefixes keep filenames unique and order stable. If a project is already established on sequential prefixes, leave it alone, but expect collisions when working in parallel.

Package scripts

json

{
  "scripts": {
    "db:generate": "drizzle-kit generate",
    "db:migrate": "netlify database migrations apply"
  }
}

```
db:generate
```
writes a new migration file under
```
netlify/database/migrations/
```
from the current schema.
```
db:migrate
```
applies pending migrations to the local development database only, via the CLI. Hosted migrations (preview branches, production) are applied by the deploy — never by this script.

Schema-change workflow

Edit
```
db/schema.ts
```
.

npm run db:generate

— writes a new file into

netlify/database/migrations/

Review the SQL.
```
npm run db:migrate
```
— applies it to the local development DB for testing.
Commit the schema change and migration file together and push. The deploy applies the migration to the preview branch, then to production on publish.

Query patterns

typescript

import { db } from "./db";
import { items } from "./db/schema";
import { eq, desc } from "drizzle-orm";

// Select all
const all = await db.select().from(items);

// Select with condition
const [one] = await db.select().from(items).where(eq(items.id, id)).limit(1);

// Ordering and limit
const recent = await db.select().from(items).orderBy(desc(items.createdAt)).limit(10);

// Insert
const [created] = await db.insert(items).values({ title: "New" }).returning();

// Update
const [updated] = await db.update(items).set({ title: "Updated" }).where(eq(items.id, id)).returning();

// Delete
await db.delete(items).where(eq(items.id, id));

Full migration workflow, expand-and-contract for breaking schema changes, and production DML migrations are in

references/migrations.md

Native driver (when Drizzle isn't a fit)

When a project wants raw SQL, uses a different query builder (Kysely, etc.), or has a library that needs a

pg.Pool

, use the native driver exposed by

@netlify/database

bash

npm install @netlify/database

typescript

import { getDatabase } from "@netlify/database";

const db = getDatabase();

// Tagged template — parameters are safely bound, not interpolated
const users = await db.sql`SELECT * FROM users WHERE active = ${true}`;

// Insert with RETURNING
const [user] = await db.sql`
  INSERT INTO users (name, email)
  VALUES (${name}, ${email})
  RETURNING *
`;

// Bulk insert
const rows = db.sql.values([
  ["Ada", "ada@example.com"],
  ["Bob", "bob@example.com"],
]);
await db.sql`INSERT INTO users (name, email) VALUES ${rows}`;

Transactions go through

db.pool

BEGIN

, the queries, and

COMMIT

ROLLBACK

all run on the same connection:

typescript

import { getDatabase } from "@netlify/database";

const db = getDatabase();
const client = await db.pool.connect();
try {
  await client.query("BEGIN");
  await client.query("INSERT INTO users (name, email) VALUES ($1, $2)", [name, email]);
  await client.query("INSERT INTO posts (author_id, title) VALUES ($1, $2)", [id, title]);
  await client.query("COMMIT");
} catch (e) {
  await client.query("ROLLBACK");
  throw e;
} finally {
  client.release();
}

For third-party tools that need a raw connection string, import

getConnectionString

from

@netlify/database

— but prefer

getDatabase()

for application code.

Manual migrations

With the native driver, scaffold migration files via the CLI:

bash

netlify database migrations new -d "create users table"

This creates

netlify/database/migrations/<prefix>_<slug>/migration.sql

and prompts for the numbering scheme if it can't be detected from existing files. Open the file and write the SQL. The CLI auto-detects an existing scheme; for new projects it'll ask — choose

timestamp

unless you have a reason not to.

You can also write the file by hand if you prefer. Two layouts are supported:

Flat:

netlify/database/migrations/<prefix>_<slug>.sql

Subdirectory:

netlify/database/migrations/<prefix>_<slug>/migration.sql

(what

migrations new

produces)

In both,

<prefix>

is digits (timestamp like

20260417143022

or sequential like

) and

<slug>

is lowercase letters, numbers, hyphens, or underscores. Files apply in lexicographic order. See

references/migrations.md

Once a migration has been applied to any database, never modify it — roll forward with a new migration instead.

Connection — don't reach for the env var

NETLIFY_DB_URL

is set automatically across builds, functions, edge functions, and local dev. Use the

getDatabase()

getConnectionString()

helpers above rather than reading it directly — only reach for the raw env var for third-party tools that demand a bare string.

NETLIFY_DB_URL

is intentionally different from the legacy extension's

NETLIFY_DATABASE_URL

. The two coexist so a project mid-migration doesn't break. Don't rename between them.

Preview branching

Each deploy preview runs against its own database branch forked from production data. Schema and data changes in a preview do not affect production until the branch is merged and published. This means:

Migrations run against the preview branch first — failures fail the preview, not production.
Ad-hoc edits in a preview (via the Netlify UI data browser or a direct client) do not propagate to production. Always express production changes as migrations.

Production data changes — write a DML migration

When a user asks for data changes that should land in production (seed data, backfills, one-off cleanups, CSV imports), do not connect to the production database and run queries. Generate a DML migration in

netlify/database/migrations/

(SQL

INSERT

UPDATE

DELETE

, or a Drizzle-generated equivalent). Tell the user you created a data migration and that merging to production will apply it. Let them verify in the preview branch first.

If the request is ambiguous ("update this record"), confirm that the user wants a production migration rather than a preview-only edit. See

references/migrations.md

Netlify CLI commands for Netlify Database

The CLI ships a complete database surface under

netlify database

(alias:

netlify db

). Requires CLI 26.0.0+. Most commands accept

--json

for machine-readable output — useful when scripting or reading results from an agent.

netlify database init

Interactive bootstrap: installs

@netlify/database

(and Drizzle if chosen), writes

drizzle.config.ts

, scaffolds and applies a starter migration, and runs a sample query. Use

--yes

for non-interactive mode.

netlify database status

Reports whether the database is enabled, whether

@netlify/database

is installed, the connection string for the active branch, and the applied/pending/missing/out-of-order migrations. Defaults to the local development database — pass

--branch <name>

to target a remote preview or production branch.

bash

netlify database status                          # local
netlify database status --branch my-feature      # remote branch
netlify database status --json
netlify database status --show-credentials       # include username/password in connection string

netlify database connect

Connects to the database. Defaults to an interactive REPL — for agent and script use, always pass

--query

for one-shot execution:

bash

# List tables
netlify database connect --query "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'"

# Inspect columns
netlify database connect --query "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = 'items'"

# JSON output
netlify database connect --query "SELECT * FROM items LIMIT 10" --json

# Get connection details only (no query)
netlify database connect --json

Never run DDL (
CREATE
,
ALTER
,
DROP
,
TRUNCATE
) through
netlify database connect
,
psql
, or any other direct connection. Schema changes go through migration files — out-of-band DDL drifts the migration history from the actual schema.

netlify database migrations new

Scaffolds a new migration file as

netlify/database/migrations/<prefix>_<slug>/migration.sql

. Auto-detects the numbering scheme from existing files; prompts when undetermined.

bash

netlify database migrations new -d "add users table"
netlify database migrations new -d "add users table" --scheme timestamp

netlify database migrations apply

Applies pending migrations to the local development database. The CLI does not apply migrations to the local DB automatically when

netlify dev

starts — you run this command yourself when you're ready. Hosted databases (preview branches, production) are handled by the deploy.

bash

netlify database migrations apply
netlify database migrations apply --to <name>   # apply up to a specific migration

netlify database migrations pull

Downloads migration files from a remote branch (defaults to

production

) and overwrites local files. Useful when local migration history has drifted from production — for example, after another contributor shipped a migration you don't have locally.

bash

netlify database migrations pull                  # from production
netlify database migrations pull --branch staging # from a specific branch
netlify database migrations pull --branch         # from your current local git branch
netlify database migrations pull --force          # skip the overwrite confirmation

netlify database migrations reset

Deletes local migration files that have not yet been applied to the target database. Applied migrations and their data are left alone — the command can't undo something already applied.

Typical use: you generated a migration, realized it was wrong, and want to start over. Run

reset

, update

db/schema.ts

, then

npm run db:generate

produces a fresh migration.

bash

netlify database migrations reset                  # against local dev DB
netlify database migrations reset --branch <name>  # against a remote branch

netlify database reset

Wipes the local development database — drops all schemas and tables. Only affects the local DB; never touches preview branches or production. Use this when you want to replay all migrations from scratch.

bash

netlify database reset

Iterating on migrations

When a migration you generated needs to change, what you do depends on whether it's been applied anywhere yet:

Already applied to any database (local dev DB, a preview branch, or production) → treat as immutable. Roll forward with a new migration that applies the correction.
Only on disk (not yet applied anywhere) → don't edit the SQL or snapshot files by hand. Run
```
netlify database migrations reset
```
, update
```
db/schema.ts
```
, then re-run
```
npm run db:generate
```
. Hand-editing desyncs Drizzle Kit's internal state and tends to produce broken migrations on the next generate.

Local development

netlify dev

runs the project against a local Postgres-compatible database — no remote connection, no risk of touching production. Use

netlify database migrations apply

to apply pending migrations locally,

netlify database connect

to query, and

netlify database reset

to wipe and replay. See

references/local-dev.md

Common mistakes

Forgetting the
@beta
dist-tag.
```
drizzle-orm
```
and
```
drizzle-kit
```
must be installed as
```
@beta
```
. The
```
latest
```
releases lack the
```
drizzle-orm/netlify-db
```
adapter.
Wrong migration output directory. Drizzle Kit defaults to
```
drizzle/
```
. Set
```
out: "netlify/database/migrations"
```
in
```
drizzle.config.ts
```
— migrations outside that directory are not applied by the deploy.
Writing raw
CREATE TABLE
when using Drizzle. The schema file is the source of truth. Define tables in
```
db/schema.ts
```
and generate migrations.
Running
drizzle-kit migrate
or
push
against a hosted DB. Never. The deploy applies migrations. For local, use
```
netlify database migrations apply
```
instead.
Using
netlify database connect
to change schema. Schema changes go through migration files — never DDL through
```
connect
```
or any direct connection.
Misunderstanding
netlify database migrations reset
. It only deletes unapplied files. It cannot undo an applied migration — for that, roll forward with a new migration.
Assuming
netlify dev
applies migrations automatically. It doesn't — only the deploy does. Run
```
netlify database migrations apply
```
locally yourself.

netlify-database

NPX Install

Tags

SKILL.md Content

Netlify Database

Database vs Blobs

CRITICAL: Install Drizzle from the
`@beta`
dist-tag

CRITICAL: Use the Netlify CLI for database operations

CRITICAL: Never apply migrations to a Netlify-hosted database

Not the legacy "Netlify DB" extension

Provisioning

Drizzle ORM (recommended path)

Install

Schema file

Drizzle client

Drizzle Kit config

Package scripts

Schema-change workflow

Query patterns

Native driver (when Drizzle isn't a fit)

Manual migrations

Connection — don't reach for the env var

Preview branching

Production data changes — write a DML migration

Netlify CLI commands for Netlify Database