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 (or an existing configuration from 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;

lookup

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

Look up an existing Cloudflare Hyperdrive configuration (created in the dashboard or owned by another system) without managing its lifecycle — the data-source form (what Terraform calls a data source and Pulumi an invoke). The configuration is read by hyperdriveId or name during plan/deploy and is never created, updated or deleted: there is no state row, so destroy and nuke cannot touch it. Bind it to a Worker through env or Connect, exactly like a Connection.

The id names the binding inside the Worker, so it must be the same on every deploy; the name or hyperdriveId may differ per stage.

lookup: Looking up a configuration

By ID

const db = Cloudflare.Hyperdrive.lookup("SharedDb", {
  hyperdriveId: "a76a99bc342644deb02c38d66082262a",
});

By name

const db = Cloudflare.Hyperdrive.lookup("SharedDb", {
  name: "shared-postgres",
});

lookup: Binding to a Worker

Async Worker env

const worker = yield* Cloudflare.Worker("Worker", {
  main: "./src/worker.ts",
  env: {
    HD: Cloudflare.Hyperdrive.lookup("SharedDb", { name: "shared-postgres" }),
  },
});

Effect Worker

const hd = yield* Cloudflare.Hyperdrive.Connect(
  Cloudflare.Hyperdrive.lookup("SharedDb", { name: "shared-postgres" }),
);
const url = yield* hd.connectionString;

lookup: Local development

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