Wrangler commands

D1 Wrangler commands use REST APIs to interact with the control plane. This page lists the Wrangler commands for D1.

create

Creates a new D1 database, and provides the binding and UUID that you will put in your wrangler.toml file.

wrangler d1 create <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the new D1 database.
• --location string optional
  • Provide an optional location hint for your database leader.
  • Available options include weur (Western Europe), eeur (Eastern Europe), apac (Asia Pacific), oc (Oceania), wnam (Western North America), and enam (Eastern North America).

info

Get information about a D1 database, including the current database size and state.

wrangler d1 info <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database to get information about.
• --json boolean optional
  • Return output as JSON rather than a table.

list

List all D1 databases in your account.

wrangler d1 list [OPTIONS]

• --json boolean optional
  • Return output as JSON rather than a table.

delete

Delete a D1 database.

wrangler d1 delete <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database to delete.
• -y, --skip-confirmation boolean optional
  • Skip deletion confirmation prompt.

execute

Execute a query on a D1 database.

wrangler d1 execute <DATABASE_NAME> [OPTIONS]

Note

You must provide either --command or --file for this command to run successfully.

• DATABASE_NAME string required
  • The name of the D1 database to execute a query on.
• --command string optional
  • The SQL query you wish to execute.
• --file string optional
  • Path to the SQL file you wish to execute.
• -y, --yes boolean optional
  • Answer yes to any prompts.
• --local boolean (default: true) optional
  • Execute commands/files against a local database for use with wrangler dev.
• --remote boolean (default: false) optional
  • Execute commands/files against a remote D1 database for use with wrangler dev --remote.
• --persist-to string optional
  • Specify directory to use for local persistence (for use in combination with --local).
• --json boolean optional
  • Return output as JSON rather than a table.
• --preview boolean optional
  • Execute commands/files against a preview D1 database (as defined by preview_database_id in Wrangler.toml).
• --batch-size number optional
  • Number of queries to send in a single batch.

export

Export a D1 database or table's schema and/or content to a .sql file.

wrangler d1 export <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database to export.
• --remote boolean (default: false) optional
  • Execute commands/files against a remote D1 database for use with wrangler dev --remote.
• --output string optional
  • Path to the SQL file for your export.
• --table string optional
  • The name of the table within a D1 database to export.
• --no-data boolean (default: false) optional
  • Controls whether export SQL file contains database data. Note that --no-data=true is not recommended due to a known wrangler limitation that intreprets the value as false.
• --no-schema boolean (default: false) optional
  • Controls whether export SQL file contains database schema. Note that --no-schema=true is not recommended due to a known wrangler limitation that intreprets the value as false.

time-travel restore

Restore a database to a specific point-in-time using Time Travel.

wrangler d1 time-travel restore <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database to execute a query on.
• --bookmark string optional
  • A D1 bookmark representing the state of a database at a specific point in time.
• --timestamp string optional
  • A UNIX timestamp or JavaScript date-time string within the last 30 days.
• --json boolean optional
  • Return output as JSON rather than a table.

time-travel info

Inspect the current state of a database for a specific point-in-time using Time Travel.

wrangler d1 time-travel info <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database to execute a query on.
• --timestamp string optional
  • A UNIX timestamp or JavaScript date-time string within the last 30 days.
• --json bboolean optional
  • Return output as JSON rather than a table.

backup create

Warning

This command only works on databases created during D1's alpha period. You can check which version your database uses with wrangler d1 info <DATABASE_NAME>.

This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to Time Travel in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period.

Initiate a D1 backup.

wrangler d1 backup create <DATABASE_NAME>

• DATABASE_NAME string required
  • The name of the D1 database to backup.

backup list

Warning

This command only works on databases created during D1's alpha period. You can check which version your database uses with wrangler d1 info <DATABASE_NAME>.

This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to Time Travel in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period.

List all available backups.

wrangler d1 backup list <DATABASE_NAME>

• DATABASE_NAME string required
  • The name of the D1 database to list the backups of.

backup restore

Warning

This command only works on databases created during D1's alpha period. You can check which version your database uses with wrangler d1 info <DATABASE_NAME>.

This command will not work on databases that are created during the beta period, or after general availability (GA). Refer to Time Travel in the D1 documentation for more information on D1's approach to backup and restores for databases created during the beta/GA period.

Restore a backup into a D1 database.

wrangler d1 backup restore <DATABASE_NAME> <BACKUP_ID>

• DATABASE_NAME string required
  • The name of the D1 database to restore the backup into.
• BACKUP_ID string required
  • The ID of the backup you wish to restore.

backup download

Warning

This command only works on databases created during D1's alpha period. You can check which version your database uses with wrangler d1 info <DATABASE_NAME>.

This command will not work on databases that are created during the beta period, or after general availability (GA). To download existing data of a beta/GA database to your local machine refer to the wrangler d1 export command. Refer to Time Travel in the D1 documentation for more information on D1's approach to backups for databases created during the beta/GA period.

Download existing data to your local machine.

wrangler d1 backup download <DATABASE_NAME> <BACKUP_ID>

• DATABASE_NAME string required
  • The name of the D1 database you wish to download the backup of.
• BACKUP_ID string required
  • The ID of the backup you wish to download.
• --output string optional
  • The .sqlite3 file to write to (defaults to '<DB_NAME>.<SHORT_BACKUP_ID>.sqlite3').

migrations create

Create a new migration.

This will generate a new versioned file inside the migrations folder. Name your migration file as a description of your change. This will make it easier for you to find your migration in the migrations folder. An example filename looks like:

0000_create_user_table.sql

The filename will include a version number and the migration name you specify below.

wrangler d1 migrations create <DATABASE_NAME> <MIGRATION_NAME>

• DATABASE_NAME string required
  • The name of the D1 database you wish to create a migration for.
• MIGRATION_NAME string required
  • A descriptive name for the migration you wish to create.

migrations list

View a list of unapplied migration files.

wrangler d1 migrations list <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database you wish to list unapplied migrations for.
• --local boolean optional
  • Show the list of unapplied migration files on your locally persisted D1 database.
• --remote boolean (default: false) optional
  • Show the list of unapplied migration files on your remote D1 database.
• --persist-to string optional
  • Specify directory to use for local persistence (for use in combination with --local).
• --preview boolean optional
  • Show the list of unapplied migration files on your preview D1 database (as defined by preview_database_id in wrangler.toml).

migrations apply

Apply any unapplied migrations.

This command will prompt you to confirm the migrations you are about to apply. Confirm that you would like to proceed. After, a backup will be captured.

The progress of each migration will be printed in the console.

When running the apply command in a CI/CD environment or another non-interactive command line, the confirmation step will be skipped, but the backup will still be captured.

If applying a migration results in an error, this migration will be rolled back, and the previous successful migration will remain applied.

wrangler d1 migrations apply <DATABASE_NAME> [OPTIONS]

• DATABASE_NAME string required
  • The name of the D1 database you wish to apply your migrations on.
• --env string optional
  • Specify which environment configuration to use for D1 binding
• --local boolean (default: true) optional
  • Execute any unapplied migrations on your locally persisted D1 database.
• --remote boolean (default: false) optional
  • Execute any unapplied migrations on your remote D1 database.
• --persist-to string optional
  • Specify directory to use for local persistence (for use in combination with --local).
• --preview boolean optional
  • Execute any unapplied migrations on your preview D1 database (as defined by preview_database_id in wrangler.toml).
• --batch-size number optional
  • Number of queries to send in a single batch.

Global commands

The following global flags work on every command:

• --help boolean
  • Show help.
• --version boolean
  • Show version number.
• --config string (not supported by Pages)
  • Path to .toml configuration file.

Experimental commands

insights

Returns statistics about your queries.

npx wrangler d1 insights <database_name> --<option>

For more information, see Query insights.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!