Cloudflare Docs
Hyperdrive
Visit Hyperdrive on GitHub
Set theme to dark (⇧+D)

Connect to Postgres

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

​​ Create a Hyperdrive

To quickly create a Hyperdrive that connects to an existing PostgreSQL database, you can use the wrangler CLI or use 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
$ wrangler hyperdrive create my-first-hyperdrive --connection-string="postgres://user:[email protected]:5432/databasenamehere"

This will output the ID of your Hyperdrive, which you will need to set in the wrangler.toml configuration file for your Workers project:


[[hyperdrive]]
name = "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. See the code examples on this page for 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:

DriverDocsMinimum Version Required
node-postgres - pghttps://node-postgres.com/[email protected]
Postgres.jshttps://github.com/porsager/postgres3.4.0
Drizzlehttps://orm.drizzle.team/0.26.2^
Kyselyhttps://kysely.dev/0.26.3^

^ The marked libraries use node-postgres or Postgres.js 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 Workers code shows examples for both node-postgres and Postgres.js:


$ npm install pg

$ npm install postgres

The following Workers examples show you how to:

  1. Create a database client in each driver.
  2. Pass the Hyperdrive connection string and connect to the database.
  3. Write a query.
src/worker.ts
import { Client } from 'pg'
interface Env {
HYPERDRIVE: Hyperdrive;
}
export default async fetch(req: Request, env: Env, ctx: ExecutionContext) {
// The node-postgres client accepts a 'connectionString' parameter
const client = new Client({
connectionString: env.HYPERDRIVE.connectionString,
});
await client.connect()
const results = await client.query("SELECT * FROM users LIMIT 10")
return Response.json(results)
}
src/worker.ts
import postgres from 'postgres'
interface Env {
HYPERDRIVE: Hyperdrive;
}
export default async fetch(req: Request, env: Env, ctx: ExecutionContext) {
// The Postgres.js library accepts a connection string directly
const sql = postgres(env.HYPERDRIVE.connectionString)
const results = await sql`SELECT * FROM users LIMIT 10`
return Response.json(results)
}

​​ Transaction and statement support

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

When using Hyperdrive, the following PostgreSQL features are unsupported:

In cases where you need to issue these unsupported statements from your application, Cloudflare 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.
  • You can 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