Cloudflare Enablement
Hyperdrive
Testing
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Hyperdrive
  3. Configuration
  4. Connect to PostgreSQL

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:

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:

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:

Driver Documentation Minimum Version Required Notes
node-postgres - pg https://node-postgres.com/ pg@8.11.0 8.11.4 introduced a bug with URL parsing and will not work. 8.11.5 fixes this.
Postgres.js https://github.com/porsager/postgres postgres@3.43.1 Must pass prepare: false when creating the client.
Drizzle https://orm.drizzle.team/ 0.26.2^
Kysely https://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:

Mode Supported Details
none No Hyperdrive does not support insecure plain text connections.
prefer No (use require) Hyperdrive will always use TLS.
require Yes (default) TLS is required, but server certificates are not validated.
verify-ca Not currently supported in beta Verifies 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-full Not currently supported in beta Identical 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:

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

Create a new Client instance and pass the Hyperdrive parameters:

​​ Postgres.js

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

Install the Postgres.js driver:

Create a new sql instance and pass the Hyperdrive parameters:

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

  • Named prepared statements ( PostgreSQL docs ). 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 ).
  • 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