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