Cloudflare 中文文档
D1
Cloudflare 中文文档
D1
编辑这个页面
跳转官方原文档
Set theme to dark (⇧+D)
  1. Products
  2. D1
  3. Build with D1
  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:

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:

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.

​​ Develop locally with Pages

You can only develop against a local D1 database when using Cloudflare Pages by creating a minimal wrangler.toml in the root of your Pages project. This can be useful when creating schemas, seeding data or otherwise managing a D1 database directly, without adding to your application logic.

Your wrangler.toml should resemble the following:

You can then execute queries and/or run migrations against a local database as part of your local development process by passing the --local flag to wrangler:

The preceding command would execute queries the local only version of your D1 database. Without the --local flag, the commands are executed against the remote version of your D1 database running on Cloudflare’s network.

​​ Persist data

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.

​​ Test programmatically

​​ Miniflare

Miniflare allows you to simulate a Workers and resources like D1 using the same underlying runtime and code as used in production.

You can use Miniflare’s support for D1 to create D1 databases you can use for testing:

You can then use the getD1Database() method to retrieve the simulated database and run queries against it as if it were your real production D1 database:

​​ unstable_dev

Wrangler exposes an unstable_dev() that allows you to run a local HTTP server for testing Workers and D1. Run migrations against a local database by setting a preview_database_id in your wrangler.toml configuration.

Given the below wrangler.toml configuration:

Migrations can be run locally as part of your CI/CD setup by passing the --local flag to wrangler:

​​ Usage example

The following example shows how to use Wrangler’s unstable_dev() API to:

  • Run migrations against your local test database, as defined by preview_database_id.
  • Make a request to an endpoint defined in your Worker. This example uses /api/users/?limit=2.
  • Validate the returned results match, including the Response.status and the JSON our API returns.

Review the unstable_dev() documentation for more details on how to use the API within your tests.