Postgres with Hyperdrive

Edge Kit keeps its own data in D1: accounts, sessions, subscriptions, and the records your features add. Some products also need data that already lives in PostgreSQL, such as a product database another service owns, records shared with a backend or a Core app, or a feature built on Postgres extensions like pgvector.

Cloudflare Hyperdrive connects your Worker to that database. In this recipe, you add a Hyperdrive binding, a Drizzle client for Postgres beside the existing D1 client, and a protected server function that reads customer data from it. D1 stays the application database, so authentication, billing, and the rest of the kit keep working unchanged.

The Postgres files below are new example files, not part of the kit. Finish local development setup first and have a Postgres connection string ready.

Data placement

Each database keeps the records it suits best:

Link Postgres records to customers with the Edge user ID from the session. The two databases cannot join tables or share a transaction, so a workflow that writes to both should define what happens when its second write fails.

postgres://USER:PASSWORD@HOST:5432/DATABASE

pnpm wrangler hyperdrive create my-app-postgres --connection-string="postgres://USER:PASSWORD@HOST:5432/DATABASE"

"hyperdrive": [
  {
    "binding": "HYPERDRIVE",
    "id": "<your-hyperdrive-id>"
  }
]

pnpm cf-typegen

When developing locally, you should use a local Postgres connection string to emulate Hyperdrive functionality.

CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://postgres:postgres@localhost:5432/my_app"

pnpm add pg
pnpm add -D @types/pg

import { pgTable, text, timestamp } from "drizzle-orm/pg-core";

export const report = pgTable("report", {
  id: text("id").primaryKey(),
  userId: text("user_id").notNull(),
  title: text("title").notNull(),
  createdAt: timestamp("created_at").notNull().defaultNow(),
});

import { env } from "cloudflare:workers";
import { drizzle } from "drizzle-orm/node-postgres";
import { Client } from "pg";

import * as schema from "./schema";

export async function connectPostgres() {
  const client = new Client({
    connectionString: env.HYPERDRIVE.connectionString,
  });
  await client.connect();

  return drizzle({ client, schema, casing: "snake_case" });
}

import { desc, eq } from "drizzle-orm";

import { connectPostgres } from "@/db/postgres";
import { report } from "@/db/postgres/schema";

export async function listReports(userId: string) {
  const postgres = await connectPostgres();

  return postgres
    .select({ id: report.id, title: report.title, createdAt: report.createdAt })
    .from(report)
    .where(eq(report.userId, userId))
    .orderBy(desc(report.createdAt))
    .limit(25);
}

import { createServerFn } from "@tanstack/react-start";

import { enforceAuth } from "@/lib/auth/middleware";

import { listReports } from "./reports.server";

export const listReportsFn = createServerFn({ method: "GET" })
  .middleware([enforceAuth])
  .handler(({ context }) => listReports(context.user.id));

SELECT DISTINCT usename, application_name
FROM pg_stat_activity
WHERE application_name = 'Cloudflare Hyperdrive';

Query caching

Deployed Workers cache read queries by default. Writes always reach the database, but Hyperdrive does not clear cached results when data changes. A matching read can return the earlier result for up to a minute, plus a short stale-while-revalidate window. Local development connects directly, so you will not see this behavior until you deploy.

Match the configuration to how fresh each read must be:

Queries that call functions such as NOW() or RANDOM() are never cached. When caching matters, compute the value in your code and pass it as a parameter. Cloudflare's query caching guide lists the rules and the adjustable cache lifetime.

For fresh reads, create a second configuration for the same database with caching turned off:

pnpm wrangler hyperdrive create my-app-postgres-fresh --connection-string="postgres://USER:PASSWORD@HOST:5432/DATABASE" --caching-disabled

Bind it beside the first one:

"hyperdrive": [
  { "binding": "HYPERDRIVE", "id": "<your-hyperdrive-id>" },
  { "binding": "HYPERDRIVE_FRESH", "id": "<your-fresh-hyperdrive-id>" }
]

Let the client helper accept a binding, keeping the cached one as its default:

export async function connectPostgres() { 
export async function connectPostgres(hyperdrive = env.HYPERDRIVE) { 
  const client = new Client({
    connectionString: env.HYPERDRIVE.connectionString, 
    connectionString: hyperdrive.connectionString, 
  });

Then call connectPostgres(env.HYPERDRIVE_FRESH) in operations that need the latest data. Run pnpm cf-typegen again, and add CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_FRESH to .env.local, since each binding needs its own local connection string. Both configurations open connections to the same database, so plan for their combined connection count.

Hyperdrive's cache works alongside the kit's other cache layers. KV caching stores values your code chooses, and client query freshness controls refetching in the browser.

Schema and migrations

Drizzle Kit needs a separate configuration for Postgres. The existing drizzle.config.ts generates SQLite migrations for D1, and Wrangler applies everything in the drizzle/ folder to D1.

Create drizzle.postgres.config.ts in the repository root:

import { defineConfig } from "drizzle-kit";

export default defineConfig({
  out: "./drizzle-postgres",
  schema: "./src/db/postgres/schema.ts",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.POSTGRES_URL ?? "",
  },
});

Drizzle Kit runs on your machine or in CI, not in the Worker, so POSTGRES_URL is a direct connection string rather than the Hyperdrive binding. Set your development value in .env.local.

When another service owns the schema, that service ships schema changes and your Edge file mirrors the tables it reads. To start from the existing database, introspect it with Drizzle Kit pull and copy the tables you need into src/db/postgres/schema.ts:

pnpm with-env drizzle-kit pull --config drizzle.postgres.config.ts

Release in a compatible order: add a column before the Edge release that reads it, and stop reading a column before the owner removes it.

When this app owns the tables, generate and apply migrations from your schema file:

pnpm with-env drizzle-kit generate --config drizzle.postgres.config.ts
pnpm with-env drizzle-kit migrate --config drizzle.postgres.config.ts

Review the generated SQL in drizzle-postgres/ before applying it.

Previews and staging

Cloudflare's preview builds do not inherit production bindings. Add the binding to the same previews block as your other preview resources, pointed at a staging database through its own Hyperdrive configuration:

"previews": {
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<your-staging-hyperdrive-id>" }
  ]
}

Previews that share a configuration share its database. When a branch needs isolated data, give it a separate configuration that points at a separate database or schema. Cloudflare's preview configuration explains which settings belong in the block.

Postgres as the main database

Edge Kit is designed around D1 as its application database. Moving authentication, billing, and the kit's own tables to Postgres is a migration project, not a configuration change. It affects:

• the Better Auth adapter, which uses the SQLite provider, and the auth schema it generates
• Drizzle Kit's dialect and the existing D1 migration history
• pnpm db:migrate and pnpm deploy, which apply migrations with Wrangler's D1 commands
• the development seed and Worker tests, which run against local D1
• the shared db export, which would need a request-scoped client for auth, billing, and background jobs

If you want PostgreSQL as the primary database from the start, Core uses PostgreSQL with Drizzle for auth, billing, and application data, and its Cloudflare deployment connects through Hyperdrive.

Common issues

The dev server asks for a connection string

The variable name must end with the exact binding name, such as CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE_FRESH for a second binding. Wrangler reads it from the environment, so keep it in .env.local or your shell even if your Worker secrets live in .dev.vars.

Queries fail after the first request

An error such as Cannot perform I/O on behalf of a different request means a client was created at module scope or shared between requests. Create it inside the operation with connectPostgres().

A saved change does not appear

The read probably came from Hyperdrive's cache. Use the cache-disabled binding for reads right after a write and for data that must be current.

Production cannot reach the database

Check the configuration's host, credentials, and TLS settings, and confirm that your database accepts connections from Hyperdrive. To store new credentials, for example after a password rotation, update the configuration:

pnpm wrangler hyperdrive update <your-hyperdrive-id> --connection-string="postgres://USER:PASSWORD@HOST:5432/DATABASE"

Cloudflare's Hyperdrive troubleshooting explains specific connection errors, and limits lists connection counts for each Workers plan.