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:
Driver | Documentation | Minimum Version Required | Notes |
---|---|---|---|
Postgres.js (recommended) | https://github.com/porsager/postgres | postgres@3.4.4 | Supported in both Workers & Pages. |
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. Requires the legacy node_compat = true to be set, which is not supported in Pages. |
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, and server certificates are validated (based on WebPKI). |
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:
- Create a database client with a database driver.
- Pass the Hyperdrive connection string and connect to the database.
- 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:
$ npm install postgres
Create a new sql
instance and pass the Hyperdrive parameters:
src/index.tsimport 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: 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)
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>;
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.tsimport { 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> {
// NOTE: if `prepare: false` is passed when connecting, performance will // be slower but still correctly supported. const sql = postgres(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: 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 theapplication_name
in thepg_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.