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
| 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. |