Skip to content
Cloudflare Docs

Connect to PostgreSQL

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:

Terminal window
# 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:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23",
  "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
Postgres.js (recommended)Postgres.js documentation ↗postgres@3.4.4Supported in both Workers & Pages.
node-postgres - pgnode-postgres - pg documentation ↗pg@8.13.08.11.4 introduced a bug with URL parsing and will not work. 8.11.5 fixes this. Requires compatibility_flags = ["nodejs_compat"] and compatibility_date = "2024-09-23" - refer to Node.js compatibility. Requires wrangler 3.78.7 or later.
DrizzleDrizzle documentation ↗0.26.2^
KyselyKysely documentation ↗0.26.3^
rust-postgres ↗rust-postgres documentation ↗v0.19.8Use the query_typed ↗ method for best performance.

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

To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the nodejs_compat compatibility flag to your Wrangler configuration file, and set your compatibility date to September 23rd, 2024 or later. This will enable Node.js compatibility for your Workers project.

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23"
}

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, and server certificates are validated (based on WebPKI).
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.

Postgres.js

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

Install the Postgres.js driver:

Terminal window
npm install postgres

Create a new sql instance and pass the Hyperdrive parameters:

import postgres from "postgres";


export interface Env {
  // If you set another name in the Wrangler configuration file 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) {
    // NOTE: if `prepare: false` is passed when connecting, performance will
    // be slower but still correctly supported.
    const sql = postgres(
            env.HYPERDRIVE.connectionString,
            {
                // Workers limit the number of concurrent external connections, so be sure to limit
                // the size of the local connection pool that postgres.js may establish.
                max: 5,


                // If you are using array types in your Postgres schema, it is necessary to fetch
                // type information to correctly de/serialize them. However, if you are not using
                // those, disabling this will save you an extra round-trip every time you connect.
                fetch_types: false,
            },
        );


    try {
      // A very simple test query
      const result = await sql`select * from pg_tables LIMIT 10`;


      // Clean up the client, ensuring we don't kill the worker before that is
      // completed.
      ctx.waitUntil(sql.end());


      // 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>;

node-postgres / pg

Install the node-postgres driver:

Terminal window
npm install pg

Ensure you have compatibility_flags and compatibility_date set in your Wrangler configuration file as shown below:

{
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2024-09-23"
}

Create a new Client instance and pass the Hyperdrive parameters:

import { Client } from "pg";


export interface Env {
  // If you set another name in the Wrangler configuration file as the value for 'binding',
  // replace "HYPERDRIVE" with the variable name you defined.
  HYPERDRIVE: Hyperdrive;
}


export default {
  async fetch(request, env, ctx): Promise<Response> {
    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" });


      // Clean up the client, ensuring we don't kill the worker before that is
      // completed.
      ctx.waitUntil(client.end());


      // 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>;

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