Connect to Postgres

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

​​ Create a Hyperdrive

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

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.toml configuration file for your Workers project:

node_compat = true # required for database drivers to function

[[hyperdrive]]
binding = "HYPERDRIVE"
id = "<your-hyperdrive-id-here>"

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.

​​ Supported TLS (SSL) modes

Hyperdrive supports the following PostgreSQL TLS (SSL) Open external link connection modes when connecting to your origin database:

​​ Driver examples

The following Workers code shows examples for node-postgres:

node-postgres
$ npm install pg

The following Workers 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. Write a query.

src/index.ts
import { Client } from 'pg';

export interface Env {
	// If you set another name in wrangler.toml 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) {
		// Create a database client that connects to your database via Hyperdrive
		// Hyperdrive generates a unique connection string you can pass to
		// supported drivers, including node-postgres, Postgres.js, and the many
		// ORMs and query builders that use these drivers.
		const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });

		try {
			// Connect to your database
			await client.connect();

			// A very simple test query
			const result = await client.query({ text: 'SELECT * FROM pg_tables' });

			// Return result rows as JSON
			return Response.json({ result: result });
		} catch (e) {
			console.log(e);
			return Response.json({ error: JSON.stringify(e) }, { status: 500 });
		}
	},
};

​​ Transaction and statement support

Hyperdrive’s connection pooling mode is equivalent to the transaction mode of connection poolers like PgBouncer Open external link and PgCat Open external link .

Hyperdrive does not support the following PostgreSQL features:

• Named prepared statements ( PostgreSQL docs Open external link ). These are distinct from the typical and common unnamed prepared statements used to safely provide values to a query.
• SET statements.
• Advisory locks ( PostgreSQL documentation Open external link ).
• LISTEN and NOTIFY.
• PREPARE and DEALLOCATE.

In cases where you need to issue these unsupported statements from your application, the Hyperdrive team recommends setting up a second, direct client without Hyperdrive.

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

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