--- title: CockroachDB description: Connect Hyperdrive to a CockroachDB database. image: https://developers.cloudflare.com/dev-products-preview.png --- > 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. [Skip to content](#%5Ftop) # CockroachDB **Last reviewed:** over 2 years ago Connect Hyperdrive to a CockroachDB database. This example shows you how to connect Hyperdrive to a [CockroachDB ↗](https://www.cockroachlabs.com/) database cluster. CockroachDB is a PostgreSQL-compatible distributed SQL database with strong consistency guarantees. ## 1\. Allow Hyperdrive access To allow Hyperdrive to connect to your database, you will need to ensure that Hyperdrive has valid user credentials and network access. ### CockroachDB Console The steps below assume you have an [existing CockroachDB Cloud account ↗](https://www.cockroachlabs.com/docs/cockroachcloud/quickstart) and database cluster created. To create and/or fetch your database credentials: 1. Go to the [CockroachDB Cloud console ↗](https://cockroachlabs.cloud/clusters) and select the cluster you want Hyperdrive to connect to. 2. Select **SQL Users** from the sidebar on the left, and select **Add User**. 3. Enter a username (for example, \`hyperdrive-user), and select **Generate & Save Password**. 4. Note down the username and copy the password to a temporary location. To retrieve your database connection details: 1. Go to the [CockroachDB Cloud console ↗](https://cockroachlabs.cloud/clusters) and select the cluster you want Hyperdrive to connect to. 2. Select **Connect** in the top right. 3. Choose the user you created, for example,`hyperdrive-user`. 4. Select the database, for example `defaultdb`. 5. Select **General connection string** as the option. 6. In the text box below, select **Copy** to copy the connection string. By default, the CockroachDB cloud enables connections from the public Internet (`0.0.0.0/0`). If you have changed these settings on an existing cluster, you will need to allow connections from the public Internet for Hyperdrive to connect. ## 2\. Create a database configuration To configure Hyperdrive, you will need: * The IP address (or hostname) and port of your database. * The database username (for example, `hyperdrive-demo`) you configured in a previous step. * The password associated with that username. * The name of the database you want Hyperdrive to connect to. For example, `postgres`. Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers: ``` postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name ``` Most database providers will provide a connection string you can directly copy-and-paste directly into Hyperdrive. * [ Dashboard ](#tab-panel-6428) * [ Wrangler CLI ](#tab-panel-6429) To create a Hyperdrive configuration with the Cloudflare dashboard: 1. In the Cloudflare dashboard, go to the **Hyperdrive** page. [ Go to **Hyperdrive** ](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive) 2. Select **Create Configuration**. 3. Fill out the form, including the connection string. 4. Select **Create**. To create a Hyperdrive configuration with the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/): 1. Open your terminal and run the following command. Replace `` with a name for your Hyperdrive configuration and paste the connection string provided from your database host, or replace `user`, `password`, `HOSTNAME_OR_IP_ADDRESS`, `port`, and `database_name` placeholders with those specific to your database: Terminal window ``` npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" ``` 2. This command outputs a binding for the [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/): * [ wrangler.jsonc ](#tab-panel-6426) * [ wrangler.toml ](#tab-panel-6427) JSONC ``` { "$schema": "./node_modules/wrangler/config-schema.json", "name": "hyperdrive-example", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-05-08", "compatibility_flags": [ "nodejs_compat" ], // Pasted from the output of `wrangler hyperdrive create --connection-string=[...]` above. "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "" } ] } ``` TOML ``` "$schema" = "./node_modules/wrangler/config-schema.json" name = "hyperdrive-example" main = "src/index.ts" # Set this to today's date compatibility_date = "2026-05-08" compatibility_flags = [ "nodejs_compat" ] [[hyperdrive]] binding = "HYPERDRIVE" id = "" ``` Note Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](https://developers.cloudflare.com/hyperdrive/observability/troubleshooting/) to debug possible causes. ## 3\. Use Hyperdrive from your Worker Install the `node-postgres` driver: npm yarn pnpm bun ``` npm i pg@>8.16.3 ``` ``` yarn add pg@>8.16.3 ``` ``` pnpm add pg@>8.16.3 ``` ``` bun add pg@>8.16.3 ``` Note The minimum version of `node-postgres` required for Hyperdrive is `8.16.3`. If using TypeScript, install the types package: npm yarn pnpm bun ``` npm i -D @types/pg ``` ``` yarn add -D @types/pg ``` ``` pnpm add -D @types/pg ``` ``` bun add -d @types/pg ``` Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: * [ wrangler.jsonc ](#tab-panel-6430) * [ wrangler.toml ](#tab-panel-6431) JSONC ``` { // required for database drivers to function "compatibility_flags": [ "nodejs_compat" ], // Set this to today's date "compatibility_date": "2026-05-08", "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "" } ] } ``` TOML ``` compatibility_flags = [ "nodejs_compat" ] # Set this to today's date compatibility_date = "2026-05-08" [[hyperdrive]] binding = "HYPERDRIVE" id = "" ``` Create a new `Client` instance and pass the Hyperdrive `connectionString`: TypeScript ``` // filepath: src/index.ts import { Client } from "pg"; export default { async fetch( request: Request, env: Env, ctx: ExecutionContext, ): Promise { // Create a new client instance for each request. Hyperdrive maintains the // underlying database connection pool, so creating a new client is fast. const client = new Client({ connectionString: env.HYPERDRIVE.connectionString, }); try { // Connect to the database await client.connect(); // Perform a simple query const result = await client.query("SELECT * FROM pg_tables"); return Response.json({ success: true, result: result.rows, }); } catch (error: any) { console.error("Database error:", error.message); return new Response("Internal error occurred", { status: 500 }); } }, }; ``` ## Next steps * Learn more about [How Hyperdrive Works](https://developers.cloudflare.com/hyperdrive/concepts/how-hyperdrive-works/). * Refer to the [troubleshooting guide](https://developers.cloudflare.com/hyperdrive/observability/troubleshooting/) to debug common issues. * Understand more about other [storage options](https://developers.cloudflare.com/workers/platform/storage-options/) available to Cloudflare Workers. ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"item":{"@id":"/directory/","name":"Directory"}},{"@type":"ListItem","position":2,"item":{"@id":"/hyperdrive/","name":"Hyperdrive"}},{"@type":"ListItem","position":3,"item":{"@id":"/hyperdrive/examples/","name":"Examples"}},{"@type":"ListItem","position":4,"item":{"@id":"/hyperdrive/examples/connect-to-postgres/","name":"Connect to PostgreSQL"}},{"@type":"ListItem","position":5,"item":{"@id":"/hyperdrive/examples/connect-to-postgres/postgres-database-providers/","name":"Database Providers"}},{"@type":"ListItem","position":6,"item":{"@id":"/hyperdrive/examples/connect-to-postgres/postgres-database-providers/cockroachdb/","name":"CockroachDB"}}]} ```