@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
mdx 133 lines 4.19 KB
Raw
1 ---
2 title: D1
3 description: SQL.D1 wraps a bound D1 database in an @effect/sql-d1 client — tagged-template queries with typed errors over the native binding.
4 ---
5
6 import PackageManagers from "../../../../components/PackageManagers.astro";
7
8 export const deps = `@effect/sql-d1`;
9
10 `SQL.D1` opens an `@effect/sql-d1` client over a Cloudflare D1
11 binding. Queries are Effects: they carry `SqlError` in the error
12 channel, participate in interruption, and trace like everything else
13 in your program.
14
15 Install the driver:
16
17 <PackageManagers add={deps} />
18
19 ## Connect
20
21 Declare the database, bind it with
22 `Cloudflare.D1.QueryDatabase`, and hand the client to `SQL.D1`:
23
24 ```typescript
25 // src/db.ts
26 import * as Cloudflare from "@alchemy.run/cloudflare";
27
28 export const Database = Cloudflare.D1.Database("Database");
29 ```
30
31 ```typescript
32 // src/api.ts
33 import * as Cloudflare from "@alchemy.run/cloudflare";
34 import * as SQL from "@alchemy.run/cloudflare/D1/SQL";
35 import * as Effect from "effect/Effect";
36 import * as HttpServerResponse from "effect/http/HttpServerResponse";
37 import { Database } from "./db.ts";
38
39 export default class Api extends Cloudflare.Worker<Api>()(
40 "Api",
41 { main: import.meta.url },
42 Effect.gen(function* () {
43 const d1 = yield* Cloudflare.D1.QueryDatabase(Database);
44 const sql = yield* SQL.D1(d1);
45
46 return {
47 fetch: Effect.gen(function* () {
48 const users = yield* sql`SELECT * FROM users`;
49 return yield* HttpServerResponse.json({ users });
50 }),
51 };
52 }).pipe(Effect.provide(Cloudflare.D1.QueryDatabaseBinding)),
53 ) {}
54 ```
55
56 The client (and its prepared-statement cache) is built lazily on the
57 first query of an execution and torn down when the event settles —
58 see [Connection lifecycle](/sql/effect-sql/lifecycle).
59
60 ## Queries
61
62 Interpolated values are parameters, never string concatenation:
63
64 ```typescript
65 const user = yield* sql`SELECT * FROM users WHERE id = ${id}`;
66
67 yield* sql`INSERT INTO users ${sql.insert({ name, email })}`;
68
69 const rows = yield* sql`
70 SELECT * FROM users WHERE id IN ${sql.in(ids)}
71 `;
72 ```
73
74 Rows come back as plain objects typed by your annotation:
75 `sql<{ id: number; name: string }>\`...\``.
76
77 ## Errors
78
79 Failures surface as `SqlError` in the typed error channel:
80
81 ```typescript
82 const users = yield* sql`SELECT * FROM users`.pipe(
83 Effect.catchTag("SqlError", (e) =>
84 Effect.succeed([]).pipe(Effect.tap(() => Effect.logWarning(e))),
85 ),
86 );
87 ```
88
89 ## Batches instead of transactions
90
91 D1 has no session transactions, so `sql.withTransaction` and
92 streaming queries are unavailable on this driver. For atomic
93 multi-statement writes, use the native binding's `batch` through the
94 same `QueryDatabase` client — statements execute sequentially in one
95 round trip and roll back together on failure:
96
97 ```typescript
98 yield* d1.batch([
99 d1.prepare("UPDATE accounts SET balance = balance - ?1 WHERE id = ?2").bind(amount, from),
100 d1.prepare("UPDATE accounts SET balance = balance + ?1 WHERE id = ?2").bind(amount, to),
101 ]);
102 ```
103
104 ## Provide as a service
105
106 For services that shouldn't know which database they run on, depend
107 on the generic `SqlClient` tag and provide the database with
108 `SQL.D1Layer`:
109
110 ```typescript
111 import * as SqlClient from "effect/sql/SqlClient";
112
113 const makeUsers = Effect.gen(function* () {
114 const sql = yield* SqlClient.SqlClient;
115 return {
116 find: (id: number) => sql<User>`SELECT * FROM users WHERE id = ${id}`,
117 };
118 });
119
120 const users = yield* makeUsers.pipe(Effect.provide(SQL.D1Layer(d1)));
121 ```
122
123 The layer provides `SqlClient.SqlClient` and `@effect/sql-d1`'s `D1Client` from one per-execution client. Other drivers can satisfy the generic service, but changing engines still requires compatible SQL and transaction semantics.
124
125 ## Local dev
126
127 `alchemy dev` runs the same Worker against a local D1 database via
128 miniflare — `SQL.D1` works unchanged because it resolves whatever
129 `D1Database` binding the runtime provides.
130
131 ## Where next
132
133 [Cloudflare setup](/cloudflare/setup) and [D1](/cloudflare/data/d1) cover deployment and database behavior; [SQL databases](/sql/databases) compares D1 with other engines. Read [Migrations](/sql/effect-sql/migrations) for committed SQL application, [Connection lifecycle](/sql/effect-sql/lifecycle) for cleanup, or [Drizzle on D1](/sql/drizzle/d1) for typed schemas.