Cloudflare Docs
Hyperdrive
Edit this page on GitHub
Set theme to dark (⇧+D)

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.

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:

DriverDocumentationMinimum Version RequiredNotes
node-postgres - pghttps://node-postgres.com/pg@8.11.08.11.4 introduced a bug with URL parsing and will not work. 8.11.5 fixes this.
Postgres.jshttps://github.com/porsager/postgrespostgres@3.43.1Must pass prepare: false when creating the client.
Drizzlehttps://orm.drizzle.team/0.26.2^
Kyselyhttps://kysely.dev/0.26.3^

^ 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) connection modes when connecting to your origin database:

ModeSupportedDetails
noneNoHyperdrive does not support insecure plain text connections.
preferNo (use require)Hyperdrive will always use TLS.
requireYes (default)TLS is required, but server certificates are not validated.
verify-caNot currently supported in betaVerifies the server’s TLS certificate is signed by a root CA on the client. This ensures the server has a certificate the client trusts.
verify-fullNot currently supported in betaIdentical to verify-ca, but also requires the database hostname must match a Subject Alternative Name (SAN) present on the certificate.

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

Install the node-postgres driver:

$ npm install pg

Ensure you have node_compat = true set in your wrangler.toml configuration file:

wrangler.toml
# other fields elided
node_compat = true # require for node-postgres to work

Create a new Client instance and pass the Hyperdrive parameters:

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, env, ctx): Promise<Response> {
// 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({
host: env.HYPERDRIVE.host,
user: env.HYPERDRIVE.user,
password: env.HYPERDRIVE.password,
port: env.HYPERDRIVE.port,
database: env.HYPERDRIVE.database
})
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: e.message }, { status: 500 });
}
},
} satisfies ExportedHandler<Env>;

​​ Postgres.js

The following Workers code shows you how to use Postgres.js with Hyperdrive.

Install the Postgres.js driver:

$ npm install postgres

Create a new sql instance and pass the Hyperdrive parameters:

src/index.ts
import postgres from "postgres";
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, env, ctx): Promise<Response> {
// Important: Set `prepare: false` as Postgres.js named prepared statements
// are not compatible with connection pooling systems like Hyperdrive
const sql = postgres(env.HYPERDRIVE.connectionString, { prepare: false })
try {
// A very simple test query
const result = await sql`select * from pg_tables`
// 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>;

​​ Transaction and statement support

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

Hyperdrive does not support the following PostgreSQL features:

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