Connect to Nile
Connect Hyperdrive to a Nile database instance.
This example shows you how to connect Hyperdrive to a Nile ↗ PostgreSQL database instance.
Nile is PostgreSQL re-engineered for multi-tenant applications. Nile's virtual tenant databases provide you with isolation, placement, insight, and other features for your tenant's data and embedding. Refer to Nile documentation ↗ to learn more.
You can connect Cloudflare Hyperdrive to any Nile database in your workspace using its connection string - either with a new set of credentials, or using an existing set.
To get a connection string from Nile console:
- Log in to Nile console ↗, then select a database.
- On the left hand menu, click Settings (the bottom-most icon) and then select Connection.
- Select the PostgreSQL logo to show the connection string.
- Select "Generate credentials" to generate new credentials.
- Copy the connection string (without the "psql" part).
You will have obtained a connection string similar to the following:
postgres://0191c898-...:4d7d8b45-...@eu-central-1.db.thenile.dev:5432/my_database
With the connection string, you can now create a Hyperdrive database configuration.
To configure Hyperdrive, you will need:
- The IP address (or hostname) and port of your database.
- The database username (for example,
hyperdrive-demo
) you configured in a previous step. - The password associated with that username.
- The name of the database you want Hyperdrive to connect to. For example,
postgres
.
Hyperdrive accepts the combination of these parameters in the common connection string format used by database drivers:
postgres://USERNAME:PASSWORD@HOSTNAME_OR_IP_ADDRESS:PORT/database_name
Most database providers will provide a connection string you can directly copy-and-paste directly into Hyperdrive.
To create a Hyperdrive configuration with the Wrangler CLI, open your terminal and run the following command. Replace <NAME_OF_HYPERDRIVE_CONFIG> with a name for your Hyperdrive configuration and paste the connection string provided from your database host, or replace user
, password
, HOSTNAME_OR_IP_ADDRESS
, port
, and database_name
placeholders with those specific to your database:
npx wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name"
This command outputs a binding for the Wrangler configuration file:
{ "name": "hyperdrive-example", "main": "src/index.ts", "compatibility_date": "2024-08-21", "compatibility_flags": [ "nodejs_compat" ], "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>" } ]}
name = "hyperdrive-example"main = "src/index.ts"compatibility_date = "2024-08-21"compatibility_flags = ["nodejs_compat"]
# Pasted from the output of `wrangler hyperdrive create <NAME_OF_HYPERDRIVE_CONFIG> --connection-string=[...]` above.[[hyperdrive]]binding = "HYPERDRIVE"id = "<ID OF THE CREATED HYPERDRIVE CONFIGURATION>"
Install the driver:
npm install postgres
Copy the below Worker code, which passes the connection string generated from env.HYPERDRIVE.connectionString
directly to the driver.
import postgres from "postgres";
export interface Env { // If you set another name in the Wrangler config 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> { // Create a database client that connects to our 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 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 { // Test query const result = await sql`SELECT * FROM pg_tables;`;
// Returns result rows as JSON return Response.json({ result: result }); } catch (e: any) { console.log(e); return Response.json({ error: e.message }, { status: 500 }); } },} satisfies ExportedHandler<Env>;
- Learn more about How Hyperdrive Works.
- Refer to the troubleshooting guide to debug common issues.
- Understand more about other storage options available to Cloudflare Workers.