--- description: Develop and test Hyperdrive-connected Workers locally using Wrangler. title: Local development image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/hyperdrive/llms.txt > Use this file to discover all available pages before exploring further. # Local development Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/hyperdrive/configuration/local-development/index.md)|[Agent setup](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agent-setup/) Hyperdrive can be used when developing and testing your Workers locally. [Wrangler](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/workers/wrangler/install-and-update/), 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. Note When using `localConnectionString`, Hyperdrive's connection pooling and query caching do not take effect. Your Worker connects directly to the database without going through Hyperdrive. ### Configure with environment variable The recommended approach is to use an environment variable to avoid committing credentials to source control: ```sh # 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_`, where `` is the name of the binding assigned to your Hyperdrive in your [Wrangler configuration file](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/workers/wrangler/configuration/). To unset an environment variable: `unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_` For example, to set the connection string for a local database: ```sh export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/databasename" npx wrangler dev ``` ### Configure in Wrangler configuration file Alternatively, you can set `localConnectionString` in your [Wrangler configuration file](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/workers/wrangler/configuration/): ```jsonc { "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "c020574a-5623-407b-be0c-cd192bab9545", "localConnectionString": "postgres://user:password@localhost:5432/databasename" } ] } ``` ```toml [[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`: ```jsonc { "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "your-hyperdrive-id", }, ], } ``` ```toml [[hyperdrive]] binding = "HYPERDRIVE" id = "your-hyperdrive-id" ``` To start a remote development session: ```sh npx wrangler dev --remote ``` Note The `localConnectionString` field is not used with `wrangler dev --remote`. Instead, your Worker connects to the database configured in your deployed Hyperdrive configuration. Caution Use `wrangler dev --remote` with caution. Since your Worker runs in Cloudflare's production environment, any database writes or side effects will affect your production data. Refer to the [wrangler dev documentation](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/workers/wrangler/commands/general/#dev) to learn more about how to configure a local development session. ## Related resources * Use [wrangler dev](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/workers/wrangler/commands/general/#dev) to run your Worker and Hyperdrive locally and debug issues before deploying. * Learn [how Hyperdrive works](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/hyperdrive/concepts/how-hyperdrive-works/). * Understand how to [configure query caching in Hyperdrive](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/hyperdrive/concepts/query-caching/). Was this helpful? YesNo ## On this page [![](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/hyperdrive/configuration/local-development/#page","headline":"Local development ยท Cloudflare Hyperdrive docs","description":"Develop and test Hyperdrive-connected Workers locally using Wrangler.","url":"https://developers.cloudflare.com/hyperdrive/configuration/local-development/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```