Why does creating a Hyperdrive config for a PostgreSQL database with only a private network address fail with error 2009, and how do you connect it safely?
answer
- Hyperdrive dials from the public internet
- test connection at creation
- a tunnel out of the network
- VPC service or Access token
basics
~20 sHyperdrive connects to public addresses from Cloudflare's network, and error 2009 means the host is not public. Run Cloudflare Tunnel in the private network and point Hyperdrive at it through a Workers VPC service or an Access-protected tunnel hostname.
solid answer
~40 sWhen you create or update a config, Hyperdrive test-connects to the origin from Cloudflare's IP ranges. Error `2009` says the hostname does not resolve to a public IP; private addresses such as `10.x` are not reachable that way. The safe fix keeps the database private: run `cloudflared` in the network so the tunnel connects outward to Cloudflare. The recommended path (beta) is a Workers VPC service of type `tcp` pointing at the database, then `wrangler hyperdrive create --service-id <id>` with `--database`, `--user` and `--password`. The older path publishes the tunnel on a hostname, guards it with a Cloudflare Access application whose Service Auth policy accepts one service token, and creates the config with `--host`, `--access-client-id` and `--access-client-secret` but no port. Either way the database must still accept TLS.
code
bash · 2 linesnpx wrangler vpc service create catalog-db --type tcp --tcp-port 5432 --app-protocol postgresql --tunnel-id <TUNNEL_ID> --ipv4 10.1.5.20
npx wrangler hyperdrive create catalog --service-id <VPC_SERVICE_ID> --database catalog --user app_user --password <PASSWORD> --scheme postgresqlgo deeper
Remember that Hyperdrive reaches databases from the public internet, so a private one needs a tunnel.
Explain the 2009 test-connection failure and the two private paths: a Workers VPC service or a tunnel guarded by an Access service token.
Review the setup from the defender's side: no public listener, a token-only Access policy, least-privilege database user and TLS still on.
Decide which private path the organisation standardises on, weighing the recommended but beta VPC route against the Access-based one.
## Why the config fails Hyperdrive opens its pooled connections from **Cloudflare's network**, using Cloudflare's published IP ranges. When you run `wrangler hyperdrive create` or `update`, it first makes a **test connection** and sends an empty query. If the test fails, you get a configuration error code instead of a config: | Code | Meaning | | --- | --- | | `2008` | the hostname could not be resolved | | `2009` | the hostname does not resolve to a public IP, or the address is not public | | `2010` | the host and port could not be reached | | `2011` | connection refused, usually a firewall or access list | | `2012` | the database does not support TLS | A database with only an address such as `10.1.5.20` inside a private network gives `2009`: Hyperdrive cannot route to private addresses directly. Making the database public just to get past this is the wrong instinct. ## The options 1. **Workers VPC service (recommended, beta).** Run a **Cloudflare Tunnel** (`cloudflared`) in the private network; it makes an outbound connection to Cloudflare, so no inbound port is opened. Create a TCP **VPC service** that points through the tunnel to the database host and port, for example `wrangler vpc service create catalog-db --type tcp --tcp-port 5432 --app-protocol postgresql --tunnel-id <tunnel id> --ipv4 10.1.5.20`. Then create the config against that service: `wrangler hyperdrive create catalog --service-id <service id> --database catalog --user app_user --password <password> --scheme postgresql`. No Access application or service token is involved, and the same VPC service can be reused by other configs. 2. **Tunnel plus Cloudflare Access.** Publish the tunnel on a hostname in your zone with a TCP service pointing at the database, protect that hostname with an **Access application** whose policy uses the **Service Auth** action and accepts one **service token**, and create the config with `--host <tunnel hostname>`, `--database`, `--user`, `--password`, `--access-client-id` and `--access-client-secret`. Leave out `--port`; Wrangler rejects `--origin-port` together with the Access flags, because the tunnel's own service settings decide the database port. The dashboard can create the Access application and token for you. 3. **Public endpoint with an allow-list.** Keep the database public but accept connections only from Cloudflare's IP ranges. These ranges are shared by every Hyperdrive config and other Cloudflare products, so the allow-list narrows exposure without proving that only your config can connect; the database credentials remain the real gate. ## Choosing between the private paths | Concern | Workers VPC service | Tunnel plus Access | | --- | --- | --- | | Pieces to manage | tunnel and a TCP VPC service | tunnel, public hostname, Access application, service token | | What the config names | `--service-id` | `--host`, `--access-client-id`, `--access-client-secret` | | Reuse | one service for many configs, and bindable to Workers | each config carries the service token's ID and secret | | Status on 2026-10-10 | recommended, beta | documented, beta | Neither path opens an inbound port into the database's network, because the tunnel connects outward; the Access path does publish a hostname, which its Access policy guards. The VPC path has fewer secrets to rotate, since there is no service token whose client secret must be stored in the config. ## What stays the same - **TLS is still required.** Hyperdrive never connects in plain text, through a tunnel or not; a private database must still be configured with TLS or creation fails with `2012`. - **The Worker side does not change.** The binding, `env.HYPERDRIVE.connectionString` and the per-request client look exactly as they do for a public database. - **Pooling and caching work as usual**, with the same origin connection limits. ## Reviewing such a setup safely When you review a private-database configuration, check: - the database has no public listener at all, and the tunnel runs inside the network with outbound access only; - with the Access path, the Access policy accepts only the Hyperdrive service token, identity providers are turned off for the application, and the token's client secret is stored only in the Hyperdrive config (Access displays it once); - the database user Hyperdrive logs in as has the permissions the application needs and no more; - the team knows the VPC path is in beta and which path the configs use. The tunnel's own creation and routing rules, and Access policies in general, are covered in the material on Cloudflare Tunnel and on Access; here the point is how Hyperdrive is pointed at them.
- Why does Wrangler refuse `--port` together with `--access-client-id`?In the Access path Hyperdrive routes to the tunnel's public hostname, and the tunnel's service configuration already names the database's address and port. Wrangler marks `--origin-port` as conflicting with the Access flags, so you give the hostname, database name and credentials only.
- The tunnel is up but creation fails with `2012`. What is wrong?The database is not offering TLS. Hyperdrive requires TLS to the origin even when the traffic arrives through a tunnel, so enable TLS on the database server; with a private certificate authority you can upload its certificate and use `--ca-certificate-id` with `--sslmode verify-ca` or `verify-full`.
- Hyperdrive can connect directly to a 10.x address if you give the right port.
- Fix error 2009 by opening the database to the internet without restrictions.
- Allow-listing Cloudflare's IP ranges proves only your Hyperdrive config can reach the database.
- Traffic through a tunnel is already encrypted, so the database can skip TLS.
- With the Access path you must give the database port alongside the tunnel hostname.
Assumes the platform as of 2026-10-10, where connecting Hyperdrive through a Workers VPC service (available since April 2026, still beta) is the recommended private-database path over Tunnel plus Access.