Cloudflare.Hyperdrive reference

Connect

Source: packages/cloudflare/src/Hyperdrive/Connect.ts

A typed accessor for a Cloudflare Hyperdrive runtime binding inside a Worker. Provides the same shape as the raw Hyperdrive runtime object (connection string, host, port, user, password, database) plus a raw escape hatch for libraries that want direct access.

Connect: Examples

Bind Hyperdrive in a Worker

const hd = yield* Cloudflare.Hyperdrive.Connect(MyConnection);
const url = yield* hd.connectionString;

/ /** Bind a Connection (declared, or an existing configuration from Connection.lookup) to a Worker and obtain the Effect-native Hyperdrive client (connection string, host, port, …).

Connect is a single identifier that is simultaneously the binding’s Context tag, its type, and the callable — yield* Cloudflare.Hyperdrive.Connect(conn).

Using Hyperdrive inside a Worker

const hd = yield* Cloudflare.Hyperdrive.Connect(MyConnection);
const url = yield* hd.connectionString;

Connection

Source: packages/cloudflare/src/Hyperdrive/Connection.ts

A Cloudflare Hyperdrive configuration.

Hyperdrive accelerates and pools connections to existing PostgreSQL or MySQL databases, exposing them to Workers via a binding. Create a config as a resource, then bind it to a Worker to obtain a connection string.

Connection: Creating a Hyperdrive

const hd = yield* Cloudflare.Hyperdrive.Connection("my-pg", {
  origin: {
    scheme: "postgres",
    host: "db.example.com",
    port: 5432,
    database: "app",
    user: "app",
    password: yield* Config.Redacted("DB_PASSWORD"),
  },
});

Connection: Connecting to a private database

A database inside a private network (e.g. Aurora or RDS in an AWS VPC) is reached through Workers VPC: run cloudflared inside the network with the Tunnel’s token, expose the database as a TCP VPC Service, and point Hyperdrive at the service.

const tunnel = yield* Cloudflare.Tunnel.Tunnel("VpcTunnel");
const service = yield* Cloudflare.Connectivity.DirectoryService("Aurora", {
  type: "tcp",
  tcpPort: 5432,
  appProtocol: "postgresql",
  host: {
    hostname: "my-cluster.cluster-abc123.us-east-1.rds.amazonaws.com",
    resolverNetwork: { tunnelId: tunnel.tunnelId },
  },
});
const hd = yield* Cloudflare.Hyperdrive.Connection("Aurora", {
  origin: {
    scheme: "postgres",
    serviceId: service.serviceId,
    database: "app",
    user: "app",
    password: yield* Config.Redacted("DB_PASSWORD"),
  },
});

Connection: Binding to a Worker

const hd = yield* Cloudflare.Hyperdrive.Connect(MyConnection);
const url = yield* hd.connectionString;

Connection: Looking up an existing configuration

Connection.lookup binds a configuration Alchemy doesn’t manage (created in the dashboard or by another system), found by hyperdriveId or name. It is read during plan/deploy and never created, updated or deleted. The Worker binding is named after the id or name you look it up by, so inside an Effect Worker the props must evaluate the same at runtime as at deploy: derive a per-stage name from yield* Stage, never from process.env.

By name

const db = Cloudflare.Hyperdrive.Connection.lookup({ name: "shared-postgres" });
const hd = yield* Cloudflare.Hyperdrive.Connect(db);

A per-stage name

const db = Cloudflare.Hyperdrive.Connection.lookup({
  name: `postgres-${yield* Stage}`,
});
const hd = yield* Cloudflare.Hyperdrive.Connect(db);

By ID, in an async Worker’s env

const worker = yield* Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  env: {
    HD: Cloudflare.Hyperdrive.Connection.lookup({
      hyperdriveId: "a76a99bc342644deb02c38d66082262a",
    }),
  },
});

Dev origin for alchemy dev

const db = Cloudflare.Hyperdrive.Connection.lookup({
  name: "shared-postgres",
  dev: {
    scheme: "postgres",
    host: "localhost",
    port: 5432,
    database: "app",
    user: "postgres",
    password: yield* Config.redacted("DEV_DB_PASSWORD"),
  },
});