CLI reference

The Netlify CLI provides a set of commands under netlify database for inspecting, connecting to, and managing your Netlify Database.

Prerequisites

To use the netlify database commands, you need:

• Node.js 20.12.2 or later
• Netlify CLI 26.0.0 or later

Installation

Install the Netlify CLI globally from npm:

npm install -g netlify-cli

If you already have an older version installed, update to the latest release with the same command. To verify your installed version:

netlify --version

For more installation options, including local installs for CI environments, see the Netlify CLI installation guide.

Commands

The following commands let you interact with your local database.

netlify database connect

Opens an interactive SQL session against the local development database, or executes a single query and exits.

With no arguments, the command starts an interactive REPL where you can run SQL statements and a subset of psql meta-commands (such as \? and \q).

With --query, the command runs a single SQL statement, prints the result, and exits.

Options

• -q, --query <sql>: execute a single query and exit
• --json: output query results as JSON. When used without --query, prints the connection details as JSON instead.

Examples

netlify database connect
netlify database connect --query "SELECT * FROM users"
netlify database connect --json --query "SELECT * FROM users"
netlify database connect --json

netlify database init

Sets up Netlify Database in the current project. The command runs an interactive setup that installs the @netlify/database package, scaffolds a starter migration, and verifies that the database is reachable.

Pass --yes to skip all prompts and accept the defaults — useful for CI environments and AI tools.

Options

• -y, --yes: non-interactive mode; accept the defaults for every prompt

Examples

netlify database init
netlify database init --yes

netlify database migrations apply

Applies pending migrations to the local development database.

On deploy, Netlify applies migrations automatically as part of the deploy lifecycle. Use this command locally to verify that your migrations run correctly before opening a pull request, or to bring your local database in sync after pulling new migrations from a remote branch.

Options

• --to <name>: target migration name or prefix to apply up to (applies all pending migrations if omitted)
• --json: output result as JSON

netlify database migrations new

Creates a new migration in the migrations directory.

If you omit --description, the command prompts for one interactively. If you omit --scheme, the command detects the existing numbering scheme in the migrations directory and uses it, or prompts you to choose if it cannot be detected.

The command creates a subdirectory named <prefix>_<slug> containing an empty migration.sql file, which you then populate with your SQL.

Options

• -d, --description <description>: purpose of the migration, used to generate the file name
• -s, --scheme <scheme>: numbering scheme for the migration prefix. One of sequential (0001, 0002, …) or timestamp (e.g. 20260423143000).
• --json: output result as JSON

Examples

netlify database migrations new
netlify database migrations new --description "add users table" --scheme sequential

netlify database migrations pull

Downloads the migrations from a remote branch and overwrites the local migration files with them.

This is useful when you want to sync your local migrations directory with the state of a specific branch — for example, after another contributor has added a new migration on production.

The command prompts for confirmation before overwriting any files. Pass --force to skip the prompt.

Options

• -b, --branch [branch]: pull migrations for a specific branch. Defaults to production. Passing --branch with no value uses your local git branch.
• --force: skip the confirmation prompt
• --json: output result as JSON

Examples

netlify database migrations pull
netlify database migrations pull --branch staging
netlify database migrations pull --branch
netlify database migrations pull --force

netlify database migrations reset

Deletes local migration files that have not yet been applied to the target database. Migrations that have already been applied are left untouched on disk.

By default, this targets the local development database. Use --branch to compare against a remote branch instead, which is helpful for discarding local-only migrations that shouldn’t ship.

Options

• -b, --branch <branch>: target a remote preview branch instead of the local development database
• --json: output result as JSON

Examples

netlify database migrations reset
netlify database migrations reset --branch my-feature-branch

netlify database reset

Resets the local development database, removing all data and tables. Use this when you want to start from a clean slate — for example, to replay all migrations from scratch.

This command only affects the local development database; it never touches production or deploy preview branches.

Options

• --json: output result as JSON

netlify database status

Reports the current state of the database for the linked project, including whether Netlify Database is enabled, whether the @netlify/database package is installed in your project, the connection string for the active branch, and the list of applied and pending migrations.

By default, the command targets the local development database. Use --branch to target a remote database branch instead.

Options

• -b, --branch <branch>: Netlify branch name to query; defaults to the local development database
• --show-credentials: include the full connection string (including username and password) in the output
• --json: output result as JSON

Examples

netlify database status
netlify database status --show-credentials
netlify database status --json
netlify database status --branch my-feature-branch