Connect to a private database using Tunnel

Connect to a private database using Tunnel

Last updated Oct 12, 2026 Hyperdrive can securely connect to your private databases using Cloudflare Tunnel and Cloudflare Access.

Note

You can also connect Hyperdrive to a private database using Workers VPC (Recommended), which does not require configuring Access applications or service tokens.

How it works

When your database is isolated within a private network (such as a virtual private cloud ↗︎ or an on-premise network), you must enable a secure connection from your network to Cloudflare.

Cloudflare Tunnel is used to establish the secure tunnel connection.
Cloudflare Access is used to restrict access to your tunnel such that only specific Hyperdrive configurations can access it.

A request from the Cloudflare Worker to the origin database goes through Hyperdrive, Cloudflare Access, and the Cloudflare Tunnel established by cloudflared. cloudflared must be running in the private network in which your database is accessible.

The Cloudflare Tunnel will establish an outbound bidirectional connection from your private network to Cloudflare. Cloudflare Access will secure your Cloudflare Tunnel to be only accessible by your Hyperdrive configuration.

Before you start

All of the tutorials assume you have already completed the Get started guide, which gets you set up with a Cloudflare Workers account, C3 ↗︎, and Wrangler.

Warning

If your organization also uses Super Bot Fight Mode, keep Definitely Automated set to Allow. Otherwise, tunnels might fail with a websocket: bad handshake error.

Prerequisites

A database in your private network, configured to use TLS/SSL.
A hostname on your Cloudflare account, which will be used to route requests to your database.

1. Create a tunnel in your private network

1.1. Create a tunnel

First, create a Cloudflare Tunnel in your private network to establish a secure connection between your network and Cloudflare. Your network must be configured such that the tunnel has permissions to egress to the Cloudflare network and access the database within your network.

Log in to the Cloudflare dashboard and go to Networking > Tunnels. Go to Tunnels ↗
Select Create a tunnel.
Enter a name for your tunnel. We suggest choosing a name that reflects the type of resources you want to connect through this tunnel (for example, enterprise-VPC-01).
Select Create Tunnel.
Choose your operating system, then copy the installation command and run it in a terminal on your origin server.
Wait for the tunnel to connect. Once the connection is established, select Continue.

1.2. Connect your database using a public hostname

Your tunnel must be configured to use a public hostname on Cloudflare so that Hyperdrive can route requests to it. If you don't have a hostname on Cloudflare yet, you will need to register a new hostname or add a zone to Cloudflare to proceed.

In the Published application routes tab, choose a Domain and specify any subdomain or path information. This will be used in your Hyperdrive configuration to route to this tunnel.
In the Service section, specify Type TCP and the URL and configured port of your database, such as localhost:5432 or my-database-host.database-provider.com:5432. This address will be used by the tunnel to route requests to your database.
Select Save tunnel.

Note

If you are setting up the tunnel through the CLI instead (locally-managed tunnel), you will have to complete these steps manually. Follow the Cloudflare Zero Trust documentation to add a public hostname to your tunnel and configure the public hostname to route to the address of your database.

2. Create and configure Hyperdrive to connect to the Cloudflare Tunnel

To restrict access to the Cloudflare Tunnel to Hyperdrive, a Cloudflare Access application must be configured with a Policy that requires requests to contain a valid Service Auth token.

The Cloudflare dashboard can automatically create and configure the underlying Cloudflare Access application, Service Auth token, and Policy on your behalf. Alternatively, you can manually create the Access application and configure the Policies.

Automatic creation

</summary>

2.1. (Automatic) Create a Hyperdrive configuration in the Cloudflare dashboard

Create a Hyperdrive configuration in the Cloudflare dashboard to automatically configure Hyperdrive to connect to your Cloudflare Tunnel.

In the <a href="https://dash.cloudflare.com/?to=/:account/workers/hyperdrive">Cloudflare dashboard ↗︎</a>, navigate to Storage & Databases > Hyperdrive and click Create configuration.
Select Private database.
In the Networking details section, select the tunnel you are connecting to.
In the Networking details section, select the hostname associated to the tunnel. If there is no hostname for your database, return to step <a href="https://developers.cloudflare.com/hyperdrive/configuration/connect-to-private-database/#12-connect-your-database-using-a-public-hostname">1.2. Connect your database using a public hostname</a>.
In the Access Service Authentication Token section, select Create new (automatic).
In the Access Application section, select Create new (automatic).
In the Database connection details section, enter the database name, user, and password.

</details>

Manual creation

</summary>

2.1. (Manual) Create a service token

The service token will be used to restrict requests to the tunnel, and is needed for the next step.

In the <a href="https://dash.cloudflare.com/">Cloudflare dashboard ↗︎</a>, go to Zero Trust > Access controls > Service credentials > Service Tokens.
Select Create Service Token.
Name the service token. The name allows you to easily identify events related to the token in the logs and to revoke the token individually.
Set a Service Token Duration of <code>Non-expiring</code>. This prevents the service token from expiring, ensuring it can be used throughout the life of the Hyperdrive configuration.
Select Generate token. You will see the generated Client ID and Client Secret for the service token, as well as their respective request headers.
Copy the Access Client ID and Access Client Secret. These will be used when creating the Hyperdrive configuration.

Caution

This is the only time Cloudflare Access will display the Client Secret. If you lose the Client Secret, you must regenerate the service token.

2.2. (Manual) Create an Access application to secure the tunnel

<a href="https://developers.cloudflare.com/cloudflare-one/access-controls/policies/">Cloudflare Access</a> will be used to verify that requests to the tunnel originate from Hyperdrive using the service token created above.

In the <a href="https://dash.cloudflare.com/">Cloudflare dashboard ↗︎</a>, go to Zero Trust > Access controls > Applications.
Select Create new application.
Select Self-hosted and private.
Select Add public hostname and enter the subdomain and domain that was previously set for the tunnel application.
Select Create new policy.
Enter a Policy name and set the Action to Service Auth.
Create an Include rule. Specify a Selector of Service Token and the Value of the service token you created in step <a href="#21-manual-create-a-service-token">2. Create a service token</a>.
Save the policy.
In Identity providers, turn off Accept all available identity providers and clear all identity providers.
In Session Duration, select <code>No duration, expires immediately</code>.
(Optional) Go to Additional settings. Turn off Show application in App Launcher.
Select Create.

2.3. (Manual) Create a Hyperdrive configuration

To create a Hyperdrive configuration for your private database, you'll need to specify the Access application and Cloudflare Tunnel information upon creation.

# wrangler v3.65 and above required
npx wrangler hyperdrive create <NAME-OF-HYPERDRIVE-CONFIGURATION-FOR-DB-VIA-TUNNEL> --host=<HOSTNAME-FOR-THE-TUNNEL> --user=<USERNAME-FOR-YOUR-DATABASE> --password=<PASSWORD-FOR-YOUR-DATABASE> --database=<DATABASE-TO-CONNECT-TO> --access-client-id=<YOUR-ACCESS-CLIENT-ID> --access-client-secret=<YOUR-SERVICE-TOKEN-CLIENT-SECRET>

resource "cloudflare_hyperdrive_config"  "<TERRAFORM_VARIABLE_NAME_FOR_CONFIGURATION>" {
  account_id = "<YOUR_ACCOUNT_ID>"
  name       = "<NAME_OF_HYPERDRIVE_CONFIGURATION>"
  origin     = {
    host     = "<HOSTNAME_OF_TUNNEL>"
    database = "<NAME_OF_DATABASE>"
    user     = "<NAME_OF_DATABASE_USER>"
    password = "<DATABASE_PASSWORD>"
    scheme   = "postgres"
    access_client_id     = "<ACCESS_CLIENT_ID>"
    access_client_secret = "<ACCESS_CLIENT_SECRET>"
  }
  caching = {
    disabled = false
  }
}