1# API Reference
2 
3See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
4 
5## Binding Interface
6 
7```typescript
8interface Hyperdrive {
9  connectionString: string;  // PostgreSQL
10  // MySQL properties:
11  host: string;
12  port: number;
13  user: string;
14  password: string;
15  database: string;
16}
17 
18interface Env {
19  HYPERDRIVE: Hyperdrive;
20}
21```
22 
23**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
24 
25## PostgreSQL (node-postgres) - RECOMMENDED
26 
27```typescript
28import { Client } from "pg";  // pg@^8.17.2
29 
30export default {
31  async fetch(req: Request, env: Env): Promise<Response> {
32    const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
33    try {
34      await client.connect();
35      const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
36      return Response.json(result.rows);
37    } finally {
38      await client.end();
39    }
40  },
41};
42```
43 
44**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
45 
46## PostgreSQL (postgres.js)
47 
48```typescript
49import postgres from "postgres";  // postgres@^3.4.8
50 
51const sql = postgres(env.HYPERDRIVE.connectionString, {
52  max: 5,             // Limit per Worker (Workers max: 6)
53  prepare: true,      // Enabled by default, required for caching
54  fetch_types: false, // Reduce latency if not using arrays
55});
56 
57const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`;
58```
59 
60**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
61 
62## MySQL (mysql2)
63 
64```typescript
65import { createConnection } from "mysql2/promise";  // mysql2@^3.16.2
66 
67const conn = await createConnection({
68  host: env.HYPERDRIVE.host,
69  user: env.HYPERDRIVE.user,
70  password: env.HYPERDRIVE.password,
71  database: env.HYPERDRIVE.database,
72  port: env.HYPERDRIVE.port,
73  disableEval: true,  // ⚠️ REQUIRED for Workers
74});
75 
76const [results] = await conn.query("SELECT * FROM users WHERE active = ? LIMIT ?", [true, 10]);
77ctx.waitUntil(conn.end());
78```
79 
80**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
81 
82## Query Caching
83 
84**Cacheable:**
85```sql
86SELECT * FROM posts WHERE published = true;
87SELECT COUNT(*) FROM users;
88```
89 
90**NOT cacheable:**
91```sql
92-- Writes
93INSERT/UPDATE/DELETE
94 
95-- Volatile functions
96SELECT NOW();
97SELECT random();
98SELECT LASTVAL();  -- PostgreSQL
99SELECT UUID();     -- MySQL
100```
101 
102**Cache config:**
103- Default: `max_age=60s`, `swr=15s`
104- Max `max_age`: 3600s
105- Disable: `--caching-disabled=true`
106 
107**Multiple configs pattern:**
108```typescript
109// Reads: cached
110const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString);
111const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`;
112 
113// Writes/time-sensitive: no cache
114const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString);
115const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`;
116```
117 
118## ORMs
119 
120**Drizzle:**
121```typescript
122import { drizzle } from "drizzle-orm/postgres-js";  // drizzle-orm@^0.45.1
123import postgres from "postgres";
124 
125const client = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
126const db = drizzle(client);
127const users = await db.select().from(users).where(eq(users.active, true)).limit(10);
128```
129 
130**Kysely:**
131```typescript
132import { Kysely, PostgresDialect } from "kysely";  // kysely@^0.27+
133import postgres from "postgres";
134 
135const db = new Kysely({
136  dialect: new PostgresDialect({
137    postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}),
138  }),
139});
140const users = await db.selectFrom("users").selectAll().where("active", "=", true).execute();
141```
142 
143See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.
144