Cloudflare Docs
D1
Cloudflare Docs
D1
GitHub icon
Visit D1 on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. D1
  3. Learning
  4. Local development

Develop locally

D1 has fully-featured support for local development, running the same version of D1 as Cloudflare runs globally. Local development uses Wrangler, the command-line interface for Workers, to manage local development sessions and state.

​​ Start a local development session

Local development sessions create a standalone, local-only environment that mirrors the production environment D1 runs in so that you can test your Worker and D1 before you deploy to production.

An existing D1 binding of DB would be available to your Worker when running locally.

To start a local development session:

# Confirm we are using wrangler v3.0+

$ wrangler --version
⛅️ wrangler 3.0.0


# Start a local dev session:

$ wrangler dev



# Outputs:
------------------
wrangler dev now uses local mode by default, powered by 🔥 Miniflare and 👷 workerd.
To run an edge preview session for your Worker, use wrangler dev --remote
Your worker has access to the following bindings:
- D1 Databases:
  - DB: test-db (c020574a-5623-407b-be0c-cd192bab9545)
⎔ Starting local server...


[mf:inf] Ready on http://127.0.0.1:8787/
[b] open a browser, [d] open Devtools, [l] turn off local mode, [c] clear console, [x] to exit                                                                                 │

In this example, the Worker has access to local-only D1 database. The corresponding D1 binding in your wrangler.toml configuration file would resemble the following:

wrangler.toml
[[d1_databases]]

binding = "DB"

database_name = "test-db"

database_id = "c020574a-5623-407b-be0c-cd192bab9545"

Note that wrangler dev separates local and production (remote) data. A local session does not have access to your production data by default. To access your production (remote) database, pass the --remote flag when calling wrangler dev. Any changes you make when running in --remote mode cannot be undone.

Refer to the wrangler dev documentation to learn more about how to configure a local development session.

​​ Persist data

By default, in wrangler 3.0.0 and above, data is persisted across each run of wrangler dev. If your local development and testing requires or assumes an empty database, you should start with a DROP TABLE <tablename> statement to delete existing tables before using CREATE TABLE to re-create them.

Use wrangler dev --persist-to=/path/to/file to persist data to a specific location. This can be useful when working in a team (allowing you to share) the same copy, when deploying via CI/CD (to ensure the same starting state), or as a way to keep data when migrating across machines.

Users of wrangler 2.x must use the --persist flag: previous versions of wrangler did not persist data by default.