@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 157 lines 3.69 KB
Raw
1 ---
2 title: Firestore
3 description: Create a Firestore database and read and write documents from Cloud Run with typed Read, Write, and ReadWrite bindings.
4 ---
5
6 Firestore is a document database with no instance to size and no
7 network to attach. Declare a database, bind it to your service, and
8 read and write documents as plain JavaScript objects.
9
10 ## Create a database
11
12 ```typescript
13 // src/resources.ts
14 import * as GCP from "@alchemy.run/gcp";
15
16 export const Links = GCP.Firestore.Database("Links", {
17 type: "FIRESTORE_NATIVE",
18 });
19 ```
20
21 Each Stack gets its own named database in Native mode, so it never
22 touches the project's `(default)` database.
23
24 ## Bind it to a service
25
26 Ask for the access you need: `ReadDatabase`, `WriteDatabase`, or
27 `ReadWriteDatabase`:
28
29 ```typescript
30 // src/Api.ts
31 import * as GCP from "@alchemy.run/gcp";
32 import * as Effect from "effect/Effect";
33 import * as HttpServerResponse from "effect/http/HttpServerResponse";
34 import { Links } from "./resources.ts";
35
36 export default class Api extends GCP.Function<Api>()(
37 "Api",
38 { main: import.meta.url, invokerIamDisabled: true },
39 Effect.gen(function* () {
40 const db = yield* GCP.Firestore.ReadWriteDatabase(Links);
41
42 return {
43 fetch: Effect.gen(function* () {
44 const doc = yield* db.get("links/home");
45 return yield* HttpServerResponse.json(doc?.fields ?? {});
46 }).pipe(Effect.orDie),
47 };
48 }).pipe(Effect.provide(GCP.Firestore.ReadWriteDatabaseHttp)),
49 ) {}
50 ```
51
52 `ReadWriteDatabase` grants `roles/datastore.user`, limited to this one
53 database. The service can't touch any other database in the project.
54
55 ## Read a document
56
57 `get` takes a path and returns `undefined` when the document is
58 missing:
59
60 ```typescript
61 const doc = yield* db.get("links/aB3xY7z");
62 const url = doc?.fields.url;
63 ```
64
65 Fields come back as JavaScript values: integers as `number`,
66 timestamps as `Date`.
67
68 ## Write a document
69
70 `set` creates or replaces a document:
71
72 ```typescript
73 yield* db.set("links/aB3xY7z", {
74 url: "https://alchemy.run",
75 clicks: 0,
76 createdAt: new Date(),
77 });
78 ```
79
80 ## Update some fields
81
82 `update` changes only the keys you pass and leaves the rest alone:
83
84 ```typescript
85 yield* db.update("links/aB3xY7z", { clicks: 1 });
86 ```
87
88 ## Create only if missing
89
90 `create` fails with `DocumentAlreadyExists` instead of overwriting:
91
92 ```typescript
93 const created = yield* db.create(`links/${code}`, { url }).pipe(
94 Effect.as(true),
95 Effect.catchTag("GCP.Firestore.DocumentAlreadyExists", () =>
96 Effect.succeed(false),
97 ),
98 );
99 ```
100
101 ## List a collection
102
103 ```typescript
104 const { documents, nextPageToken } = yield* db.list("links", {
105 pageSize: 50,
106 });
107 ```
108
109 ## Query
110
111 `query` runs a Firestore structured query. Filter values use
112 Firestore's value shape:
113
114 ```typescript
115 const admins = yield* db.query({
116 from: [{ collectionId: "users" }],
117 where: {
118 fieldFilter: {
119 field: { fieldPath: "role" },
120 op: "EQUAL",
121 value: { stringValue: "admin" },
122 },
123 },
124 });
125 ```
126
127 ## Delete
128
129 ```typescript
130 yield* db.delete("links/aB3xY7z");
131 ```
132
133 Deleting a missing document succeeds.
134
135 ## The first requests after a deploy
136
137 The grant is a conditional project IAM binding, and those take a few
138 minutes to reach Firestore. A brand-new service can see `Forbidden`
139 until then. Retry the first call in tests.
140
141 ## React to changes
142
143 Run code whenever a document is created with
144 [Eventarc](/gcp/messaging/eventarc).
145
146 ## Example
147
148 [`examples/gcp-cloud-run-api`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-cloud-run-api)
149 is a link shortener over Firestore, with its API key in Secret
150 Manager.
151
152 ## Where next
153
154 - [How bindings grant IAM](/gcp/security/iam) — how the database-only
155 grant works.
156 - [Firestore reference](/providers/gcp/firestore#database) — every
157 prop and attribute.