mirror of
https://github.com/ksyasuda/dotfiles.git
synced 2026-03-21 06:11:27 -07:00
144 lines
3.8 KiB
Markdown
144 lines
3.8 KiB
Markdown
# API Reference
|
|
|
|
See [README.md](./README.md) for overview, [configuration.md](./configuration.md) for setup.
|
|
|
|
## Binding Interface
|
|
|
|
```typescript
|
|
interface Hyperdrive {
|
|
connectionString: string; // PostgreSQL
|
|
// MySQL properties:
|
|
host: string;
|
|
port: number;
|
|
user: string;
|
|
password: string;
|
|
database: string;
|
|
}
|
|
|
|
interface Env {
|
|
HYPERDRIVE: Hyperdrive;
|
|
}
|
|
```
|
|
|
|
**Generate types:** `npx wrangler types` (auto-creates worker-configuration.d.ts from wrangler.jsonc)
|
|
|
|
## PostgreSQL (node-postgres) - RECOMMENDED
|
|
|
|
```typescript
|
|
import { Client } from "pg"; // pg@^8.17.2
|
|
|
|
export default {
|
|
async fetch(req: Request, env: Env): Promise<Response> {
|
|
const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
|
|
try {
|
|
await client.connect();
|
|
const result = await client.query("SELECT * FROM users WHERE id = $1", [123]);
|
|
return Response.json(result.rows);
|
|
} finally {
|
|
await client.end();
|
|
}
|
|
},
|
|
};
|
|
```
|
|
|
|
**⚠️ Workers connection limit: 6 per Worker invocation** - use connection pooling wisely.
|
|
|
|
## PostgreSQL (postgres.js)
|
|
|
|
```typescript
|
|
import postgres from "postgres"; // postgres@^3.4.8
|
|
|
|
const sql = postgres(env.HYPERDRIVE.connectionString, {
|
|
max: 5, // Limit per Worker (Workers max: 6)
|
|
prepare: true, // Enabled by default, required for caching
|
|
fetch_types: false, // Reduce latency if not using arrays
|
|
});
|
|
|
|
const users = await sql`SELECT * FROM users WHERE active = ${true} LIMIT 10`;
|
|
```
|
|
|
|
**⚠️ `prepare: true` is enabled by default and required for Hyperdrive caching.** Setting to `false` disables prepared statements + cache.
|
|
|
|
## MySQL (mysql2)
|
|
|
|
```typescript
|
|
import { createConnection } from "mysql2/promise"; // mysql2@^3.16.2
|
|
|
|
const conn = 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
|
|
});
|
|
|
|
const [results] = await conn.query("SELECT * FROM users WHERE active = ? LIMIT ?", [true, 10]);
|
|
ctx.waitUntil(conn.end());
|
|
```
|
|
|
|
**⚠️ MySQL support is less mature than PostgreSQL** - expect fewer optimizations and potential edge cases.
|
|
|
|
## Query Caching
|
|
|
|
**Cacheable:**
|
|
```sql
|
|
SELECT * FROM posts WHERE published = true;
|
|
SELECT COUNT(*) FROM users;
|
|
```
|
|
|
|
**NOT cacheable:**
|
|
```sql
|
|
-- Writes
|
|
INSERT/UPDATE/DELETE
|
|
|
|
-- Volatile functions
|
|
SELECT NOW();
|
|
SELECT random();
|
|
SELECT LASTVAL(); -- PostgreSQL
|
|
SELECT UUID(); -- MySQL
|
|
```
|
|
|
|
**Cache config:**
|
|
- Default: `max_age=60s`, `swr=15s`
|
|
- Max `max_age`: 3600s
|
|
- Disable: `--caching-disabled=true`
|
|
|
|
**Multiple configs pattern:**
|
|
```typescript
|
|
// Reads: cached
|
|
const sqlCached = postgres(env.HYPERDRIVE_CACHED.connectionString);
|
|
const posts = await sqlCached`SELECT * FROM posts ORDER BY views DESC LIMIT 10`;
|
|
|
|
// Writes/time-sensitive: no cache
|
|
const sqlNoCache = postgres(env.HYPERDRIVE_NO_CACHE.connectionString);
|
|
const orders = await sqlNoCache`SELECT * FROM orders WHERE created_at > NOW() - INTERVAL 5 MINUTE`;
|
|
```
|
|
|
|
## ORMs
|
|
|
|
**Drizzle:**
|
|
```typescript
|
|
import { drizzle } from "drizzle-orm/postgres-js"; // drizzle-orm@^0.45.1
|
|
import postgres from "postgres";
|
|
|
|
const client = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
|
|
const db = drizzle(client);
|
|
const users = await db.select().from(users).where(eq(users.active, true)).limit(10);
|
|
```
|
|
|
|
**Kysely:**
|
|
```typescript
|
|
import { Kysely, PostgresDialect } from "kysely"; // kysely@^0.27+
|
|
import postgres from "postgres";
|
|
|
|
const db = new Kysely({
|
|
dialect: new PostgresDialect({
|
|
postgres: postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true}),
|
|
}),
|
|
});
|
|
const users = await db.selectFrom("users").selectAll().where("active", "=", true).execute();
|
|
```
|
|
|
|
See [patterns.md](./patterns.md) for use cases, [gotchas.md](./gotchas.md) for limits.
|