add hyperdrive wrangler dev support for remote db's (#26545)

thomasgauvin · web-flow · commit cb2af36c14d0 · 2025-12-04T10:44:22.000-05:00
* add hyperdrive wrangler dev support for remote db's

* update date on wrangler dev with remote databases
diff --git a/src/content/changelog/hyperdrive/2025-12-04-hyperdrive-remote-database-local-dev.mdx b/src/content/changelog/hyperdrive/2025-12-04-hyperdrive-remote-database-local-dev.mdx
@@ -0,0 +1,26 @@
+---
+title: Connect to remote databases during local development with wrangler dev
+description: You can now connect directly to remote databases from wrangler dev using localConnectionString, with TLS support enabling secure connections while keeping your Worker code running locally
+products:
+  - hyperdrive
+date: 2025-12-04
+---
+
+You can now connect directly to remote databases and databases requiring TLS with `wrangler dev`.
+This lets you run your Worker code locally while connecting to remote databases, without needing to use `wrangler dev --remote`.
+
+The `localConnectionString` field and `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environment variable can be used to configure the connection string used by `wrangler dev`.
+
+```jsonc
+{
+  "hyperdrive": [
+    {
+      "binding": "HYPERDRIVE",
+      "id": "your-hyperdrive-id",
+      "localConnectionString": "postgres://user:password@remote-host.example.com:5432/database?sslmode=require"
+    }
+  ]
+}
+```
+
+Learn more about [local development with Hyperdrive](/hyperdrive/configuration/local-development/).
diff --git a/src/content/docs/hyperdrive/configuration/local-development.mdx b/src/content/docs/hyperdrive/configuration/local-development.mdx
@@ -7,87 +7,109 @@ sidebar:
 
 import { WranglerConfig } from "~/components";
 
-Hyperdrive can be used when developing and testing your Workers locally by connecting to a local database instance running on your machine directly, or a remote database instance. Local development uses [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, to manage local development sessions and state.
+Hyperdrive can be used when developing and testing your Workers locally. [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Workers, provides two options for local development:
 
-:::note[Note]
+- **`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.
 
-You can connect to a local database for local development using the local connection string configurations for Wrangler, as detailed below. This allows you to connect to a local database instance running on your machine directly.
+## 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.
 
-You can also connect to a remote database for remote development using the `npx wrangler dev --remote` command, which will use the remote database configured for your Hyperdrive configuration.
+:::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 local development
+### Configure with environment variable
+
+The recommended approach is to use an environment variable to avoid committing credentials to source control:
 
-To specify a database to connect to when developing locally, you can:
+```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
+```
 
-- **Recommended:** Create a `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` [environmental variable](/workers/configuration/environment-variables/) with the connection string of your database. `<BINDING_NAME>` is the name of the binding assigned to your Hyperdrive in your [Wrangler configuration file](/workers/wrangler/configuration/) or Pages configuration. This allows you to avoid committing potentially sensitive credentials to source control in your Wrangler configuration file, if your test/development database is not ephemeral. If you have configured multiple Hyperdrive bindings, replace `<BINDING_NAME>` with the unique binding name for each.
-- Set `localConnectionString` in the Wrangler configuration file.
+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](/workers/wrangler/configuration/).
 
-If both the `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` [environmental variable](/workers/configuration/environment-variables/) and `localConnectionString` in the Wrangler configuration file are set, `wrangler dev` will use the environmental variable instead. Use `unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` to unset any existing environmental variables.
+To unset an environment variable: `unset CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>`
 
-For example, to use the environmental variable, export the environmental variable before running `wrangler dev`:
+For example, to set the connection string for a local database:
 
 ```sh
-# Your configured Hyperdrive binding is "TEST_DB"
-export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB="postgres://user:password@localhost:5432/databasename"
-# Start a local development session referencing this local instance
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/databasename"
 npx wrangler dev
 ```
 
-To configure a `localConnectionString` in the [Wrangler configuration file](/workers/wrangler/configuration/), ensure your Hyperdrive bindings have a `localConnectionString` property set:
+### Configure in wrangler.toml
+
+Alternatively, you can set `localConnectionString` in your [Wrangler configuration file](/workers/wrangler/configuration/):
 
 <WranglerConfig>
 
 ```toml
 [[hyperdrive]]
-binding = "TEST_DB"
+binding = "HYPERDRIVE"
 id = "c020574a-5623-407b-be0c-cd192bab9545"
 localConnectionString = "postgres://user:password@localhost:5432/databasename"
 ```
 
 </WranglerConfig>
 
-## Use `wrangler dev`
+If both an environment variable and `localConnectionString` in the Wrangler configuration file are set, the environment variable takes precedence.
 
-The following example shows you how to check your wrangler version, set a `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB` [environmental variable](/workers/configuration/environment-variables/), and run a `wrangler dev` session:
+## Use `wrangler dev --remote`
 
-```sh
-# Confirm you are using wrangler v3.0+
-npx wrangler --version
-```
+When you run `wrangler dev --remote`, your Worker runs in Cloudflare's network and uses your deployed Hyperdrive configuration. This means:
 
-```sh output
-⛅️ wrangler 3.27.0
-```
+- 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
 
-```sh
-# Set your environmental variable: your configured Hyperdrive binding is "TEST_DB".
-export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB="postgres://user:password@localhost:5432/databasename"
+This mode is useful for testing how your Worker behaves with Hyperdrive's features enabled before deploying.
+
+Configure your Hyperdrive binding in `wrangler.jsonc`:
+
+<WranglerConfig>
+
+```jsonc
+{
+	"hyperdrive": [
+		{
+			"binding": "HYPERDRIVE",
+			"id": "your-hyperdrive-id",
+		},
+	],
+}
 ```
 
+</WranglerConfig>
+
+To start a remote development session:
+
 ```sh
-# Start a local dev session:
-npx wrangler dev
+npx wrangler dev --remote
 ```
 
-```sh output
-------------------
-Found a non-empty CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_TEST_DB variable. Hyperdrive will connect to this database
-during local development.
+:::note
 
-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:
-- Hyperdrive configs:
-  - TEST_DB: c020574a-5623-407b-be0c-cd192bab9545
-⎔ Starting local server...
+The `localConnectionString` field is not used with `wrangler dev --remote`. Instead, your Worker connects to the database configured in your deployed Hyperdrive configuration.
 
-[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
-```
+:::
 
-`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) Hyperdrive configuration, pass the `--remote` flag when calling `wrangler dev`. Any changes you make when running in `--remote` mode cannot be undone.
+:::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](/workers/wrangler/commands/#dev) to learn more about how to configure a local development session.
 
diff --git a/src/content/docs/hyperdrive/get-started.mdx b/src/content/docs/hyperdrive/get-started.mdx
@@ -33,10 +33,7 @@ Before you begin, ensure you have completed the following:
 
 1. Sign up for a [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages) if you have not already.
 2. Install [`Node.js`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Use a Node version manager like [nvm](https://github.com/nvm-sh/nvm) or [Volta](https://volta.sh/) to avoid permission issues and change Node.js versions. [Wrangler](/workers/wrangler/install-and-update/) requires a Node version of `16.17.0` or later.
-3. Have PostgreSQL/MySQL (or compatible) database, accessible in one of the following ways:
-	* **Publicly Accessible**: Your database is directly reachable from the Internet.
-	* **Private Network**: Your database is in a private network (like a VPC) and can be securely connected using [Cloudflare Tunnel](/hyperdrive/configuration/connect-to-private-database/).
-
+3. Have a publicly accessible PostgreSQL or MySQL (or compatible) database. _If your database is in a private network (like a VPC)_, refer to [Connect to a private database](/hyperdrive/configuration/connect-to-private-database/) for instructions on using Cloudflare Tunnel with Hyperdrive.
 
 ## 1. Log in
 
@@ -111,7 +108,7 @@ Hyperdrive accepts the combination of these parameters in the common connection
 	<TabItem label="PostgreSQL">
 		```txt
 
-		postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name
+    	postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name
 
     	```
 
@@ -193,7 +190,11 @@ To install `pg`, ensure you are in the `hyperdrive-tutorial` directory. Open you
 
 If you are using TypeScript, you should also install the type definitions for `pg`:
 
-<PackageManagers pkg="@types/pg" dev comment="This should install v8.13.0 or later" />
+<PackageManagers
+	pkg="@types/pg"
+	dev
+	comment="This should install v8.13.0 or later"
+/>
 
 With the driver installed, you can now create a Worker script that queries your database.
 
@@ -236,10 +237,10 @@ export interface Env {
 export default {
 	async fetch(request, env, ctx): Promise<Response> {
 		// Create a client using the pg driver (or any supported driver, ORM or query builder)
-        // with the Hyperdrive credentials. These credentials are only accessible from your Worker.
-        const sql = new Client({
-          connectionString: env.HYPERDRIVE.connectionString,
-        });
+		// with the Hyperdrive credentials. These credentials are only accessible from your Worker.
+		const sql = new Client({
+			connectionString: env.HYPERDRIVE.connectionString,
+		});
 
 		try {
 			// Connect to the database
@@ -346,7 +347,45 @@ Upon receiving a request, the code above does the following:
 
 ### Run in development mode (optional)
 
-You can start your project in development mode. If you want to connect to the local database configured in your `wrangler.jsonc` with `localConnectionString` (e.g. `localhost:5432`), you can now run `wrangler dev`. This will connect directly to your database from your local Worker project emulation (Hyperdrive caching will not take effect, and the local database must not require SSL). To develop using a remote database, you can connect to your Hyperdrive configuration by running `wrangler dev --remote`.
+You can test your Worker locally before deploying by running `wrangler dev`. This runs your Worker code on your machine while connecting to your database.
+
+The `localConnectionString` field works with both local and remote databases and allows you to connect directly to your database from your Worker project running locally. You must specify the SSL/TLS mode if required (`sslmode=require` for Postgres, `sslMode=REQUIRED` for MySQL).
+
+To connect to a database during local development, configure `localConnectionString` in your `wrangler.jsonc`:
+
+```jsonc
+{
+	"hyperdrive": [
+		{
+			"binding": "HYPERDRIVE",
+			"id": "your-hyperdrive-id",
+			"localConnectionString": "postgres://user:password@your-database-host:5432/database",
+		},
+	],
+}
+```
+
+Or set an environment variable:
+
+```sh
+export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@your-database-host:5432/database"
+```
+
+Then start local development:
+
+```sh
+npx wrangler dev
+```
+
+:::note
+
+When using `wrangler dev` with `localConnectionString` or `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE`, Hyperdrive caching does not take effect locally.
+
+Alternatively, you can run `wrangler dev --remote` to test against your deployed Hyperdrive configuration with caching enabled, but this runs your entire Worker in Cloudflare's network instead of locally.
+
+Learn more about [local development with Hyperdrive](/hyperdrive/configuration/local-development/).
+
+:::
 
 ## 6. Deploy your Worker
 
@@ -369,4 +408,4 @@ By finishing this tutorial, you have created a Hyperdrive configuration, a Worke
 - How to [configure query caching](/hyperdrive/concepts/query-caching/).
 - [Troubleshooting common issues](/hyperdrive/observability/troubleshooting/) when connecting a database to Hyperdrive.
 
-If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).
+If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the [Cloudflare Developers community on Discord](https://discord.cloudflare.com).
diff --git a/src/content/release-notes/hyperdrive.yaml b/src/content/release-notes/hyperdrive.yaml
@@ -3,6 +3,14 @@ link: "/hyperdrive/platform/release-notes/"
 productName: Hyperdrive
 productLink: "/hyperdrive/"
 entries:
+  - publish_date: "2025-12-04"
+    title: Connect to remote databases during local development with wrangler dev
+    description: |-
+      The `localConnectionString` configuration field and `CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>` environment variable now support connecting to remote databases over TLS during local development with `wrangler dev`. 
+
+      When using a remote database connection string, your Worker code runs locally on your machine while connecting directly to the remote database. Hyperdrive caching does not take effect. 
+
+      Refer to [Local development](/hyperdrive/configuration/local-development/) for instructions on how to configure remote database connections for local development.
   - publish_date: "2025-07-03"
     title: Hyperdrive now supports configurable connection counts
     description: |-
