--- description: Connect Hyperdrive to a Supabase Postgres database. title: Supabase image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/hyperdrive/llms.txt > Use this file to discover all available pages before exploring further. # Supabase Connect Hyperdrive to a Supabase Postgres database. Last updated Sep 17, 2026|Copy as Markdown| [View as Markdown](https://81fab744.previews.developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/index.md)| [Agent setup](https://81fab744.previews.developers.cloudflare.com/agent-setup/) This example shows you how to connect Hyperdrive to a [Supabase ↗](https://supabase.com/) Postgres database. ## 1. Allow Hyperdrive access You can connect Hyperdrive to any existing Supabase database as the Postgres user which is set up during project creation. Alternatively, to create a new user for Hyperdrive, run these commands in the [SQL Editor ↗](https://supabase.com/dashboard/project/_/sql/new). ```sql CREATE ROLE hyperdrive_user LOGIN PASSWORD 'sufficientlyRandomPassword'; -- Here, you are granting it the postgres role. In practice, you want to create a role with lesser privileges. GRANT postgres to hyperdrive_user; ``` The database endpoint can be found in the [database settings page ↗](https://supabase.com/dashboard/project/_/settings/database). With a database user, password, database endpoint (hostname and port) and database name (default: postgres), you can now set up Hyperdrive. Note When connecting to Supabase from Hyperdrive, you should use the **Direct connection** connection string rather than the pooled connection strings. Hyperdrive will perform pooling of connections to ensure optimal access from Workers. ## 2. Create a 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: ```txt 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 Cloudflare dashboard: 1. In the Cloudflare dashboard, go to the **Hyperdrive** page. [Go to **Hyperdrive** ↗](https://dash.cloudflare.com/?to=/:account/workers/hyperdrive) 2. Select **Create Configuration**. 3. Fill out the form, including the connection string. 4. Select **Create**. To create a Hyperdrive configuration with the [Wrangler CLI](https://81fab744.previews.developers.cloudflare.com/workers/wrangler/install-and-update/): 1. Open your terminal and run the following command. Replace `` 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: ```sh npx wrangler hyperdrive create --connection-string="postgres://user:password@HOSTNAME_OR_IP_ADDRESS:PORT/database_name" ``` 2. This command outputs a binding for the [Wrangler configuration file](https://81fab744.previews.developers.cloudflare.com/workers/wrangler/configuration/): ```jsonc { "$schema": "./node_modules/wrangler/config-schema.json", "name": "hyperdrive-example", "main": "src/index.ts", // Set this to today's date "compatibility_date": "2026-09-17", "compatibility_flags": [ "nodejs_compat" ], // Pasted from the output of `wrangler hyperdrive create --connection-string=[...]` above. "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "" } ] } ``` ```toml "$schema" = "./node_modules/wrangler/config-schema.json" name = "hyperdrive-example" main = "src/index.ts" # Set this to today's date compatibility_date = "2026-09-17" compatibility_flags = [ "nodejs_compat" ] [[hyperdrive]] binding = "HYPERDRIVE" id = "" ``` Note Hyperdrive will attempt to connect to your database with the provided credentials to verify they are correct before creating a configuration. If you encounter an error when attempting to connect, refer to Hyperdrive's [troubleshooting documentation](https://81fab744.previews.developers.cloudflare.com/hyperdrive/observability/troubleshooting/) to debug possible causes. ## 3. Use Hyperdrive from your Worker Install the `node-postgres` driver: npmyarnpnpmbun ``` npm i pg@>8.16.3 ``` ``` yarn add pg@>8.16.3 ``` ``` pnpm add pg@>8.16.3 ``` ``` bun add pg@>8.16.3 ``` Note The minimum version of `node-postgres` required for Hyperdrive is `8.16.3`. If using TypeScript, install the types package: npmyarnpnpmbun ``` npm i -D @types/pg ``` ``` yarn add -D @types/pg ``` ``` pnpm add -D @types/pg ``` ``` bun add -d @types/pg ``` Add the required Node.js compatibility flags and Hyperdrive binding to your `wrangler.jsonc` file: ```jsonc { // required for database drivers to function "compatibility_flags": [ "nodejs_compat" ], // Set this to today's date "compatibility_date": "2026-09-17", "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "" } ] } ``` ```toml compatibility_flags = [ "nodejs_compat" ] # Set this to today's date compatibility_date = "2026-09-17" [[hyperdrive]] binding = "HYPERDRIVE" id = "" ``` Create a new `Client` instance and pass the Hyperdrive `connectionString`: ```ts // filepath: src/index.ts import { Client } from "pg"; export default { async fetch( request: Request, env: Env, ctx: ExecutionContext, ): Promise { // Create a new client instance for each request. Hyperdrive maintains the // underlying database connection pool, so creating a new client is fast. const client = new Client({ connectionString: env.HYPERDRIVE.connectionString, }); try { // Connect to the database await client.connect(); // Perform a simple query const result = await client.query("SELECT * FROM pg_tables"); return Response.json({ success: true, result: result.rows, }); } catch (error: any) { console.error("Database error:", error.message); return new Response("Internal error occurred", { status: 500 }); } }, }; ``` Note When connecting to a Supabase database with Hyperdrive, you should use a driver like [node-postgres (pg)](https://81fab744.previews.developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/node-postgres/) or [Postgres.js](https://81fab744.previews.developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-drivers-and-libraries/postgres-js/) to connect directly to the underlying database instead of the [Supabase JavaScript client ↗](https://github.com/supabase/supabase-js). Hyperdrive is optimized for database access for Workers and will perform global connection pooling and fast query routing by connecting directly to your database. ## Next steps - Learn more about [How Hyperdrive Works](https://81fab744.previews.developers.cloudflare.com/hyperdrive/concepts/how-hyperdrive-works/). - Refer to the [troubleshooting guide](https://81fab744.previews.developers.cloudflare.com/hyperdrive/observability/troubleshooting/) to debug common issues. - Understand more about other [storage options](https://81fab744.previews.developers.cloudflare.com/workers/platform/storage-options/) available to Cloudflare Workers. Was this helpful? YesNo ## On this page [![](https://81fab744.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://81fab744.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/#page","headline":"Supabase · Cloudflare Hyperdrive docs","description":"Connect Hyperdrive to a Supabase Postgres database.","url":"https://developers.cloudflare.com/hyperdrive/examples/connect-to-postgres/postgres-database-providers/supabase/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-09-17","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```