Connect to PostgreSQL

import { TabItem, Tabs, Render, WranglerConfig } from "~/components";

Hyperdrive supports PostgreSQL and PostgreSQL-compatible databases, popular drivers and Object Relational Mapper (ORM) libraries that use those drivers.

Create a Hyperdrive

:::note

New to Hyperdrive? Refer to the Get started guide to learn how to set up your first Hyperdrive.

:::

To create a Hyperdrive that connects to an existing PostgreSQL database, use the wrangler CLI or the Cloudflare dashboard.

When using wrangler, replace the placeholder value provided to --connection-string with the connection string for your database:

# wrangler v3.11 and above required
npx wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres://user:password@database.host.example.com:5432/databasenamehere"

The command above will output the ID of your Hyperdrive, which you will need to set in the Wrangler configuration file for your Workers project:

This will allow Hyperdrive to generate a dynamic connection string within your Worker that you can pass to your existing database driver. Refer to Driver examples to learn how to set up a database driver with Hyperdrive.

Refer to the Examples documentation for step-by-step guides on how to set up Hyperdrive with several popular database providers.

Supported drivers

Hyperdrive uses Workers TCP socket support to support TCP connections to databases. The following table lists the supported database drivers and the minimum version that works with Hyperdrive:

^ The marked libraries use node-postgres as a dependency.

Other drivers and ORMs not listed may also be supported: this list is not exhaustive.

Database drivers and Node.js compatibility

Node.js compatibility is required for database drivers, including Postgres.js, and needs to be configured for your Workers project.

Driver examples

The following examples show you how to:

1. Create a database client with a database driver.
2. Pass the Hyperdrive connection string and connect to the database.
3. Query your database via Hyperdrive.

node-postgres / pg

Postgres.js

Identify connections from Hyperdrive

To identify active connections to your Postgres database server from Hyperdrive:

• Hyperdrive's connections to your database will show up with Cloudflare Hyperdrive as the application_name in the pg_stat_activity table.
• Run SELECT DISTINCT usename, application_name FROM pg_stat_activity WHERE application_name = 'Cloudflare Hyperdrive' to show whether Hyperdrive is currently holding a connection (or connections) open to your database.

:::note

Hyperdrive only sets the application_name to Cloudflare Hyperdrive when your driver does not send its own. Some drivers set a default application_name — for example, Postgres.js sends postgres.js unless you override it. Hyperdrive forwards the driver-provided value to your database, so those connections appear under that name (for example, postgres.js) instead of Cloudflare Hyperdrive. This does not mean the connection is bypassing Hyperdrive.

To keep these connections identifiable as Hyperdrive, set the application_name explicitly in your driver. With Postgres.js:

const sql = postgres(env.HYPERDRIVE.connectionString, {
	max: 5,
	fetch_types: false,
	connection: {
		application_name: "Cloudflare Hyperdrive",
	},
});

:::

Next steps

• Refer to the list of supported database integrations to understand other ways to connect to existing databases.
• Learn more about how to use the Socket API in a Worker.
• Understand the protocols supported by Workers.