Connect to a private database using Tunnel

Hyperdrive can securely connect to your private databases using Cloudflare Tunnel and Cloudflare Access.

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.

1. Log in to Zero Trust ↗ and go to Networks > Tunnels.

2. Select Create a tunnel.

3. Choose Cloudflared for the connector type and select Next.

4. 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).

5. Select Save tunnel.

6. Next, you will need to install cloudflared and run it. To do so, check that the environment under Choose an environment reflects the operating system on your machine, then copy the command in the box below and paste it into a terminal window. Run the command.

7. Once the command has finished running, your connector will appear in Zero Trust.

   

8. Select Next.

1.2. Connect your database using a public hostname

Your tunnel must be configured to use a public hostname 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.

1. In the Public Hostnames tab, choose a Domain and specify any subdomain or path information. This will be used in your Hyperdrive configuration to route to this tunnel.

2. 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.

3. 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

2.1 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.

1. In the Cloudflare dashboard ↗, navigate to Storage & Databases > Hyperdrive and click Create configuration.
2. Select Private database.
3. In the Networking details section, select the tunnel you are connecting to.
4. In the Networking details section, select the hostname associated to the tunnel. If there is no hostname for your database, return to step 1.2. Connect your database using a public hostname.
5. In the Access Service Authentication Token section, select Create new (automatic).
6. In the Access Application section, select Create new (automatic).
7. In the Database connection details section, enter the database name, user, and password.

Manual creation

2.1 Create a service token

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

1. In Zero Trust ↗, go to Access > Service auth > Service Tokens.

2. Select Create Service Token.

3. 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.

4. Set a Service Token Duration of Non-expiring. This prevents the service token from expiring, ensuring it can be used throughout the life of the Hyperdrive configuration.

5. Select Generate token. You will see the generated Client ID and Client Secret for the service token, as well as their respective request headers.

6. Copy the Access Client ID and Access Client Secret. These will be used when creating the Hyperdrive configuration.

   Warning

   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 Create an Access application to secure the tunnel

Cloudflare Access will be used to verify that requests to the tunnel originate from Hyperdrive using the service token created above.

1. In Zero Trust ↗, go to Access > Applications.

2. Select Add an application.

3. Select Self-hosted.

4. Enter any name for the application.

5. In Session Duration, select No duration, expires immediately.

6. Select Add public hostname. and enter the subdomain and domain that was previously set for the tunnel application.

7. Select Create new policy.

8. Enter a Policy name and set the Action to Service Auth.

9. Create an Include rule. Specify a Selector of Service Token and the Value of the service token you created in step 2. Create a service token.

10. Save the policy.

11. Go back to the application configuration and add the newly created Access policy.

12. In Login methods, turn off Accept all available identity providers and clear all identity providers.

13. Select Next.

14. In Application Appearance, turn off Show application in App Launcher.

15. Select Next.

16. Select Next.

17. Save the application.

2.3 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

# 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>

Terraform

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
  }
}

This will create a Hyperdrive configuration using the usual database information (database name, database host, database user, and database password).

In addition, it will also set the Access Client ID and the Access Client Secret of the Service Token. When Hyperdrive makes requests to the tunnel, requests will be intercepted by Access and validated using the credentials of the Service Token.

Note

When creating the Hyperdrive configuration for the private database, you must enter the access-client-id and the access-client-id, and omit the port. Hyperdrive will route database messages to the public hostname of the tunnel, and the tunnel will rely on its service configuration (as configured in 1.2. Connect your database using a public hostname) to route requests to the database within your private network.

3. Query your Hyperdrive configuration from a Worker (optional)

To test your Hyperdrive configuration to the database using Cloudflare Tunnel and Access, use the Hyperdrive configuration ID in your Worker and deploy it.

Create a Hyperdrive binding

You must create a binding for your Worker to connect to your Hyperdrive configuration. Bindings allow your Workers to access resources, like D1, on the Cloudflare developer platform. You create bindings by updating your Wrangler file.

To bind your Hyperdrive configuration to your Worker, add the following to the end of your Wrangler file:

wrangler.toml

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<YOUR_DATABASE_ID>" # the ID associated with the Hyperdrive you just created

wrangler.json

{
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<YOUR_DATABASE_ID>"
    }
  ]
}

Specifically:

• The value (string) you set for the name (binding name) will be used to reference this database in your Worker. In this tutorial, name your binding HYPERDRIVE.
• The binding must be a valid JavaScript variable name ↗. For example, binding = "hyperdrive" or binding = "productionDB" would both be valid names for the binding.
• Your binding is available in your Worker at env.<BINDING_NAME>.

Query your database using Postgres.js

Use Postgres.js to send a test query to validate that the connection has been successful.

Install the Postgres.js driver:

npm install postgres

Create a new sql instance and pass the Hyperdrive parameters:

import postgres from "postgres";

export interface Env {
  // If you set another name in the `wrangler.toml / wrangler.json` file as the value for 'binding',
  // replace "HYPERDRIVE" with the variable name you defined.
  HYPERDRIVE: Hyperdrive;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // NOTE: if `prepare: false` is passed when connecting, performance will
    // be slower but still correctly supported.
    const sql = postgres(env.HYPERDRIVE.connectionString);

    try {
      // A very simple test query
      const result = await sql`select * from pg_tables LIMIT 10`;

      // Clean up the client, ensuring we don't kill the worker before that is
      // completed.
      ctx.waitUntil(sql.end());

      // Return result rows as JSON
      return Response.json({ result: result });
    } catch (e) {
      console.log(e);
      return Response.json({ error: e.message }, { status: 500 });
    }
  },
} satisfies ExportedHandler<Env>;

Now, deploy your Worker:

npx wrangler deploy

If you successfully receive the list of pg_tables from your database when you access your deployed Worker, your Hyperdrive has now been configured to securely connect to a private database using Cloudflare Tunnel and Cloudflare Access.

Troubleshooting

If you encounter issues when setting up your Hyperdrive configuration with tunnels to a private database, consider these common solutions, in addition to general troubleshooting steps for Hyperdrive:

• Ensure your database is configured to use TLS (SSL). Hyperdrive requires TLS (SSL) to connect.

Was this helpful?

What did you like?

Accurate

Easy to understand

Solved my problem

Helped me decide to use the product

Other

What went wrong?

Hard to understand

Incorrect information

Missing the information

Other

Thank you for helping improve Cloudflare's documentation!