undefined

**Save the `id` value** - you'll need it in the next step!

---

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2024-09-23",
  "compatibility_flags": ["nodejs_compat"],  // REQUIRED for database drivers
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",                     // Available as env.HYPERDRIVE
      "id": "a76a99bc-7901-48c9-9c15-c4b11b559606"  // From wrangler hyperdrive create
    }
  ]
}

undefined

---

import { Client } from "pg";

type Bindings = {
  HYPERDRIVE: Hyperdrive;
};

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString
    });

    await client.connect();

    try {
      const result = await client.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: result.rows });
    } finally {
      // Clean up connection AFTER response is sent
      ctx.waitUntil(client.end());
    }
  }
};

import { createConnection } from "mysql2/promise";

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const connection = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,
      disableEval: true  // REQUIRED for Workers (eval() not supported)
    });

    try {
      const [rows] = await connection.query('SELECT * FROM users LIMIT 10');
      return Response.json({ users: rows });
    } finally {
      ctx.waitUntil(connection.end());
    }
  }
};

npx wrangler deploy

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/db"
npx wrangler dev

// ❌ WRONG - IP address causes indefinite hang
const connection = "postgres://user:password@192.168.1.100:5432/db"

// ✅ CORRECT - Use hostname
const connection = "postgres://user:password@db.example.com:5432/db"

ALTER USER 'username'@'%' IDENTIFIED WITH caching_sha2_password BY 'password';

const url = env.isLocal ? env.DB_URL : env.HYPERDRIVE.connectionString;
const client = postgres(url, {
  fetch_types: false,
  max: 2,
});

// ❌ WRONG - SET won't persist across queries
await client.query('SET search_path TO myschema');
await client.query('SELECT * FROM mytable'); // Uses default search_path!

// ✅ CORRECT - SET within transaction
await client.query('BEGIN');
await client.query('SET search_path TO myschema');
await client.query('SELECT * FROM mytable'); // Now uses myschema
await client.query('COMMIT');

// ❌ WRONG - Global Prisma client reused across requests
const prisma = new PrismaClient({ adapter });

export default {
  async fetch(request: Request, env: Bindings) {
    // First request: works
    // Subsequent requests: hang indefinitely
    const users = await prisma.user.findMany();
    return Response.json({ users });
  }
};

// ✅ CORRECT - Create new client per request
export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const pool = new Pool({
      connectionString: env.HYPERDRIVE.connectionString,
      max: 5
    });
    const adapter = new PrismaPg(pool);
    const prisma = new PrismaClient({ adapter });

    try {
      const users = await prisma.user.findMany();
      return Response.json({ users });
    } finally {
      ctx.waitUntil(pool.end());
    }
  }
};

// ❌ WRONG - Neon serverless driver bypasses Hyperdrive
import { neon } from '@neondatabase/serverless';
const sql = neon(env.HYPERDRIVE.connectionString);
// This uses WebSockets, not TCP - Hyperdrive doesn't help

// ✅ CORRECT - Use traditional TCP driver with Hyperdrive
import postgres from 'postgres';
const sql = postgres(env.HYPERDRIVE.connectionString, {
  prepare: true,
  max: 5
});

undefined

**Reason**: Hyperdrive provides its own pooling; double-pooling causes issues and breaks caching

---

// ❌ WRONG - Nitro's useDatabase fails ~95% of the time
import { useDatabase } from 'db0';
import { drizzle } from 'db0/integrations/drizzle';

export default eventHandler(async () => {
  const db = useDatabase();
  const users = await drizzle(db).select().from(usersTable);
  // Fails ~95% of the time with 500 error
});

// ✅ CORRECT - Create Drizzle client directly
import postgres from 'postgres';
import { drizzle } from 'drizzle-orm/postgres-js';

export default eventHandler(async (event) => {
  const sql = postgres(event.context.cloudflare.env.HYPERDRIVE.connectionString, {
    max: 5,
    prepare: true
  });
  const db = drizzle(sql);
  const users = await db.select().from(usersTable);
  event.context.cloudflare.ctx.waitUntil(sql.end());
  return { users };
});

undefined

**Related**: May 2025 prepared statement caching improvements require minimum version 3.4.5

---

undefined

---

const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
await client.connect();
const result = await client.query('SELECT ...');
ctx.waitUntil(client.end());  // CRITICAL: Non-blocking cleanup

const pool = new Pool({
  connectionString: env.HYPERDRIVE.connectionString,
  max: 5  // CRITICAL: Workers limit is 6 connections (July 2025: configurable ~20 Free, ~100 Paid)
});
const [result1, result2] = await Promise.all([
  pool.query('SELECT ...'),
  pool.query('SELECT ...')
]);
ctx.waitUntil(pool.end());

import { drizzle } from "drizzle-orm/postgres-js";
import postgres from "postgres";

const sql = postgres(env.HYPERDRIVE.connectionString, { max: 5 });
const db = drizzle(sql);
const allUsers = await db.select().from(users);
ctx.waitUntil(sql.end());

import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "@prisma/client";
import { Pool } from "pg";

// ❌ WRONG - Global client causes hangs after first request
const prisma = new PrismaClient({ adapter });

export default {
  async fetch(request: Request, env: Bindings) {
    const users = await prisma.user.findMany(); // Hangs after first request
    return Response.json({ users });
  }
};

// ✅ CORRECT - Per-request client
export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext) {
    const pool = new Pool({ connectionString: env.HYPERDRIVE.connectionString, max: 5 });
    const adapter = new PrismaPg(pool);
    const prisma = new PrismaClient({ adapter });

    try {
      const users = await prisma.user.findMany();
      return Response.json({ users });
    } finally {
      ctx.waitUntil(pool.end());
    }
  }
};

const url = env.isLocal ? env.DB_URL : env.HYPERDRIVE.connectionString;
const client = postgres(url, {
  fetch_types: false,
  max: 2,
});

export CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE="postgres://user:password@localhost:5432/local_db"
npx wrangler dev

{ "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "prod-id", "localConnectionString": "postgres://..." }] }

npx wrangler dev --remote  # ⚠️ Uses PRODUCTION database

const sql = postgres(env.HYPERDRIVE.connectionString, {
  prepare: true  // REQUIRED for caching
});

response.headers.get('cf-cache-status');  // HIT, MISS, BYPASS, EXPIRED

npx wrangler cert upload certificate-authority --ca-cert root-ca.pem --name my-ca-cert
npx wrangler hyperdrive create my-db --connection-string="postgres://..." --ca-certificate-id <ID> --sslmode verify-full

npx wrangler cert upload mtls-certificate --cert client-cert.pem --key client-key.pem --name my-cert
npx wrangler hyperdrive create my-db --connection-string="postgres://..." --mtls-certificate-id <ID>

undefined

---

undefined

---

undefined

**Best practice**: Separate configs for staging/production.

---