Storage
Hyperdrive
Use a Hyperdrive binding with OpenOrange. The Worker connects directly to your Postgres or MySQL database.
Runs on Direct connection to the database in the connection string
- Works
connectionString,host,port,user,password,database, andconnect(), with your Postgres or MySQL driver- Differs
- The Worker connects straight to the database, so
hostandportname the database, not a Hyperdrive endpoint - Missing
- Connection pooling and query caching
- Migration
- Not needed The database stays where it is. Orange connects to it directly.
- Configure
hyperdrive
A Hyperdrive binding on OpenOrange hands your Worker the connection string of your own Postgres or MySQL database. Your Worker code runs unchanged.
Quickstart
You need a Postgres or MySQL database, its connection string, and a driver
such as postgres in your Worker’s packages.
-
Bind the database
Add a
hyperdriveentry towrangler.jsonc, with your database’s connection string. Keep your Cloudflareid: Orange does not use it.{ "name": "hyperdrive", "main": "src/index.ts", "compatibility_date": "2026-09-03", "hyperdrive": [ { "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>", "localConnectionString": "postgres://user:password@localhost:5432/app" } ] }To keep the password out of the config, set
CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVEin.dev.varsinstead. For Neon, Supabase, PlanetScale, and Amazon RDS, see Connection strings. -
Query it from your Worker
Pass
env.HYPERDRIVE.connectionStringto your driver, as on Cloudflare.import postgres from "postgres"; interface Env { HYPERDRIVE: Hyperdrive; } export default { async fetch(request, env, ctx): Promise<Response> { const sql = postgres(env.HYPERDRIVE.connectionString); const rows = await sql`select now()`; ctx.waitUntil(sql.end()); return Response.json(rows); }, } satisfies ExportedHandler<Env>; -
Run it
orange devshows the binding as a direct connection.orange dev Binding Resource Runs on env.HYPERDRIVE Hyperdrive Direct connectioncurl localhost:8787returns the row fromselect now().
How it works
orange devreads the connection string when it starts, aswrangler devdoes.env.HYPERDRIVEgives your driver that string and its parts, and the driver connects straight to the database.- Orange has no connection pool, so every connection that your Worker opens
reaches the database. A provider’s pooler, such as Neon’s
-poolerhost or the Supabase pooler, takes more connections than the database itself.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
connectionString | Supported | The connection string, as new URL() writes it. |
host, port, user, password, and database | Supported | They name the database itself. On Cloudflare, host and port name a Hyperdrive endpoint. |
connect() | Supported | Opens a TCP socket to host:port. |
| PostgreSQL and MySQL | Supported | postgres://, postgresql://, and mysql:// connection strings. |
| Connection pooling | Not supported | Each connection that the Worker opens goes to the database. |
| Query caching | Not supported | Every query reaches the database. |
wrangler hyperdrive commands | Not supported | orange hyperdrive prints that the command is not implemented. |
Limits
| What | Limit | What happens over it |
|---|---|---|
| Open connections | Your database’s own limit. Orange adds no pool. | Your driver gets the database’s error. Use the provider’s pooler for more connections. |
Where the connection string comes from
orange dev finds the connection string the same way as wrangler dev:
- The
CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>variable. - The deprecated
WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING>variable.orange devprints the Wrangler warning:Using "WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>" environment variable. This is deprecated. Please use "CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME>" instead. localConnectionStringin the configuration.
- The variables can come from the shell,
.dev.vars, or.env. The shell wins, and an empty value counts as unset. idis not read. A Cloudflare Hyperdrive ID works as it is.- With no connection string,
orange devstops at startup with the Wrangler error:When developing locally, you should use a local Postgres connection string to emulate Hyperdrive functionality. Please setup Postgres locally and set the value of the 'CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE' variable or "HYPERDRIVE"'s "localConnectionString" to the Postgres connection string. - Orange checks the string with Miniflare’s rules: the
postgres,postgresql, ormysqlscheme, and a host, user, password, and database. A string that fails stops startup withHyperdrive binding <BINDING> has an invalid local connection string: <Miniflare's message>. For a string thatnew URL()cannot parse, the message isInvalid url. orange servereads the connection string the same way when it starts, from its own environment. No test covers a deployed Hyperdrive binding.
Fields
env.HYPERDRIVE has the same shape as the workerd Hyperdrive type:
| Property | Type | Value |
|---|---|---|
connectionString | string | The connection string. |
host | string | The database host. |
port | number | The URL port, else 5432 for postgres and postgresql, and 3306 for mysql. |
user | string | The URL-decoded user name. |
password | string | The URL-decoded password. |
database | string | The URL-decoded database name. |
connect() | Socket | A TCP socket to host:port. |
Connection strings
Any PostgreSQL or MySQL database works. Use its connection string as the local connection string:
| Provider | Connection string | Notes |
|---|---|---|
| PlanetScale Postgres | postgresql://<role>.<branch ID>:<password>@<host>.horizon.psdb.cloud:5432/<database>?sslmode=verify-full | Copy the host from the Connect page. |
| PlanetScale MySQL | mysql://<user>:<password>@<host>/<database> | Copy the host from the Connect page, with the Other format. |
| Amazon RDS | postgres://<user>:<password>@<instance>.<ID>.<region>.rds.amazonaws.com:5432/<database> | For MySQL, use mysql:// and port 3306. The instance must accept connections from the runner. |
| Neon | postgresql://<role>:<password>@ep-<compute ID>.<region>.aws.neon.tech/<database>?sslmode=require | A -pooler host, such as ep-<compute ID>-pooler, uses Neon’s connection pooler. |
| Supabase | postgresql://postgres:<password>@db.<project ref>.supabase.co:5432/postgres | The direct host uses IPv6 on the Free and Pro plans. On an IPv4-only network, use the session pooler: postgresql://postgres.<project ref>:<password>@<pooler host>:5432/postgres. |
| A database that you run | postgres://<user>:<password>@localhost:5432/<database> |
Deviations
- The Worker connects directly to the database. There is no connection pooling and no query caching.
hostandportname the database itself. On Cloudflare they name a Hyperdrive endpoint.- Orange also reads the connection string variables from
.dev.varsand.env, not only from the shell.
Conformance
tests/bindings/hyperdrive.test.tsruns a Worker on a realorange dev. It checks that the environment variable wins overlocalConnectionString, that the fields of a percent-encoded MySQL string decode as in Miniflare, the default ports, the binding table line, and the Wrangler error when no connection string is set.tests/cli/doctor.test.tschecks thatorange doctorloads a Hyperdrive binding without printing its password.- The feature matrix lists the binding as
binding-hyperdrive. No truth-table claim covers Hyperdrive, so this page has no recorded results.