Cloudflare Workers

For production on Cloudflare Workers, use PostgreSQL through a Hyperdrive binding. Hyperdrive supplies the connection string consumed by Hookfish’s PostgreSQL adapter and manages the underlying connection pool.

Create the Worker

The Cloudflare scaffold configures the PostgreSQL adapter and generates a placeholder Hyperdrive binding:

pnpm dlx hookfish init my-broker --backend cloudflare
cd my-broker

Create a Hyperdrive configuration for your PostgreSQL database. Replace the placeholder ID in wrangler.jsonc with its configuration ID. The comments in that file include the remaining local setup and migration steps.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-broker",
  "main": "./src/index.ts",
  "compatibility_date": "2026-08-11",
  "compatibility_flags": ["nodejs_compat"],
  "observability": {
    "enabled": true
  },
  // Replace this placeholder before running or deploying the Worker.
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<hyperdrive-id>"
    }
  ]
}

Generated database binding

The generated src/index.ts resolves the Hyperdrive binding for each request:

import { HookfishServer } from '@hookfish/api'
import { postgres } from '@hookfish/database/postgres'
import {
  createMcpProvider,
  createSecretProvider,
} from '@hookfish/providers'

const db = postgres<Env>(
  (env) => env.HYPERDRIVE.connectionString,
  {
    cache: false,
    fetchTypes: false,
    max: 5,
    prepare: true,
  },
)
const frontendUrl = process.env.HOOKFISH_FRONTEND_URL ?? 'http://127.0.0.1:5173'

const hookfish = await HookfishServer.init<Env>({
  db,
  includeSwagger: false,
  returnTo: frontendUrl,
  trustedOrigins: [frontendUrl],
  providers: {
    mcp: createMcpProvider(),
    secret: createSecretProvider(),
  },
})

export default {
  fetch(request, env, context) {
    return hookfish.fetch(request, env, context)
  },
} satisfies ExportedHandler<Env>

cache: false prevents the adapter from retaining request-owned database clients in module state. Hyperdrive manages the underlying pool. max: 5 stays below the Worker request’s concurrent external-connection limit.

Configure local PostgreSQL

Set the local connection string for the HYPERDRIVE binding, then generate types and start Wrangler:

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:[email protected]:5432/hookfish"
pnpm typegen
pnpm dev

Keep the real connection string out of source control and shell history. Local Wrangler connects directly to PostgreSQL; Hyperdrive caching does not run in local mode.

Run migrations

Put a direct PostgreSQL connection string in the generated .env file. Run the generated migration command from CI or another trusted environment that can connect directly to the database:

# Set DATABASE_URL in .env, then run:
pnpm migrate

Do not run schema migrations through a user request or on every Worker startup.

Store secrets and deploy

Use Wrangler’s interactive secret prompts:

pnpm exec wrangler secret put OAUTH_ENCRYPTION_KEY
pnpm exec wrangler secret put HOOKFISH_API_KEY
pnpm typecheck
pnpm deploy

After deployment, set OAUTH_REDIRECT_BASE_URL to the Worker’s public HTTPS origin and register the callback URLs reported by Hookfish.

Get started

Store secrets

Integrate

Deploy

Secure and scale

Operate

Cloudflare Workers

Create the Worker

Generated database binding

Configure local PostgreSQL

Run migrations

Store secrets and deploy

​Create the Worker

​Generated database binding

​Configure local PostgreSQL

​Run migrations

​Store secrets and deploy

Create the Worker

Generated database binding

Configure local PostgreSQL

Run migrations

Store secrets and deploy