Skip to content
Cloudflare Docs

Local development

Hyperdrive can be used when developing and testing your Workers locally. Wrangler, the command-line interface for Workers, provides two options for local development:

  • wrangler dev (default): Runs your Worker code locally on your machine. You configure a localConnectionString to connect directly to a database (either local or remote). Hyperdrive query caching does not take effect in this mode.
  • wrangler dev --remote: Runs your Worker on Cloudflare's using your deployed Hyperdrive configuration. This is useful for testing with Hyperdrive's connection pooling and query caching enabled.

Use wrangler dev

By default, wrangler dev runs your Worker code locally on your machine. To connect to a database during local development, configure a localConnectionString that points directly to your database.

The localConnectionString works with both local and remote databases:

  • Local databases: Connect to a database instance running on your machine (for example, postgres://user:password@localhost:5432/database)
  • Remote databases: Connect directly to remote databases over TLS (for example, postgres://user:password@remote-host.example.com:5432/database?sslmode=require or mysql://user:password@remote-host.example.com:3306/database?sslMode=required). You must specify the SSL/TLS mode if required.

Configure with environment variable

The recommended approach is to use an environment variable to avoid committing credentials to source control:

Terminal window
# Your configured Hyperdrive binding is "HYPERDRIVE"
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"
npx wrangler dev

The environment variable format is CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>, where <BINDING_NAME> is the name of the binding assigned to your Hyperdrive in your Wrangler configuration file.

To unset an environment variable: unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>

For example, to set the connection string for a local database:

Terminal window
export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/databasename"
npx wrangler dev

Configure in wrangler.toml

Alternatively, you can set localConnectionString in your Wrangler configuration file:

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "c020574a-5623-407b-be0c-cd192bab9545",
      "localConnectionString": "postgres://user:password@localhost:5432/databasename"
    }
  ]
}

If both an environment variable and localConnectionString in the Wrangler configuration file are set, the environment variable takes precedence.

Use wrangler dev --remote

When you run wrangler dev --remote, your Worker runs in Cloudflare's network and uses your deployed Hyperdrive configuration. This means:

  • Your Worker code executes in Cloudflare's production environment, not locally
  • Hyperdrive's connection pooling and query caching are active
  • You connect to the database configured in your Hyperdrive configuration (created with wrangler hyperdrive create)
  • Changes made during the session interact with remote resources

This mode is useful for testing how your Worker behaves with Hyperdrive's features enabled before deploying.

Configure your Hyperdrive binding in wrangler.jsonc:

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "your-hyperdrive-id",
    },
  ],
}

To start a remote development session:

Terminal window
npx wrangler dev --remote

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