@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, 06:00 UTC

main
mdx 185 lines 6.2 KB
Raw
1 ---
2 title: Preview branches per PR
3 description: Give every pull request its own PlanetScale branch — a long-lived database owned by a staging stage, referenced by ephemeral PR stages that fork, migrate, and tear down a branch each.
4 ---
5
6 PlanetScale's branch model maps directly onto alchemy stages: the
7 database is the expensive, long-lived tier; branches are cheap forks.
8 Split your stages the same way and every PR gets an isolated schema
9 and data set without provisioning a cluster per preview:
10
11 - **`staging-*` stages** own the long-lived database.
12 - **`pr-*` stages** reference that database and own only the
13 ephemeral pieces — a branch, a credential, and compute.
14
15 The pattern is identical for both engines; only the resource names
16 and the credential model differ. New here? [Set up
17 credentials](/planetscale/setup) first.
18
19 ## Read the active stage
20
21 The create-vs-reference decision keys off the stage being deployed,
22 which the `Stack` service exposes:
23
24 ```typescript
25 import * as Alchemy from "alchemy";
26
27 const { stage } = yield* Alchemy.Stack;
28 ```
29
30 `stage` is whatever was passed to `alchemy deploy --stage <name>` —
31 `dev_sam`, `staging-pr-42`, or `pr-42`.
32
33 ## Create or reference the database
34
35 PR stages reference the database with `PostgresDatabase.ref`; every
36 other stage creates it:
37
38 ```typescript
39 import * as Planetscale from "@alchemy.run/planetscale";
40
41 const database = stage.startsWith("pr-")
42 ? yield* Planetscale.PostgresDatabase.ref("app-db", {
43 stage: `staging-${stage}`,
44 })
45 : yield* Planetscale.PostgresDatabase("app-db", {
46 region: { slug: "us-east" },
47 clusterSize: "PS_10",
48 });
49 ```
50
51 `Resource.ref(id, { stage })` reads the deployed resource's
52 attributes from another stage's state at plan time — the lookup is
53 keyed by `{ stack, stage, id }`, so the logical ID `"app-db"` must
54 match what the owning stage created. `database` is typed
55 `Planetscale.PostgresDatabase` on both paths, and downstream
56 resources don't care which one ran. Note the ref targets
57 `staging-${stage}`, not a global `"staging"`: `pr-42` reads from a
58 parallel `staging-pr-42` stage, so each PR's data lives in its own
59 database. Prefer one database shared by every PR? Use
60 `stage: "staging"`.
61
62 ## A branch per stage
63
64 Below the database line, nothing is conditional. Every stage —
65 including each PR stage — forks its own branch:
66
67 ```typescript
68 const branch = yield* Planetscale.PostgresBranch("app-branch", {
69 database,
70 migrations: "./migrations",
71 });
72 ```
73
74 Branches fork from `main` by default and carry their own
75 `migrations`: pending `.sql` files are applied to the branch on
76 every deploy, so each preview migrates itself independently — see
77 [Migrations](/planetscale/data/migrations) for ordering, hashing, and the
78 tracking table. To fork data as well as schema, `seedData:
79 "last_successful_backup"` restores the last backup into the new
80 branch.
81
82 ## Mint a per-stage credential
83
84 The credential is scoped to the branch, so it's per-stage too:
85
86 ```typescript
87 const role = yield* Planetscale.PostgresRole("app-role", {
88 database,
89 branch,
90 inheritedRoles: ["postgres"],
91 });
92 ```
93
94 `role.origin` (direct) and `role.pooledOrigin` (PSBouncer) are what
95 you hand to the runtime consumer — see
96 [Postgres](/planetscale/data/postgres) for the role model and the
97 direct-vs-pooled distinction.
98
99 ## The MySQL variant
100
101 The MySQL (Vitess) family follows the same two tiers with its own
102 resource trio — `MySQLDatabase.ref`, a non-production `MySQLBranch`,
103 and a `MySQLPassword` in place of the Postgres role:
104
105 ```typescript
106 const database = stage.startsWith("pr-")
107 ? yield* Planetscale.MySQLDatabase.ref("app-db", {
108 stage: `staging-${stage}`,
109 })
110 : yield* Planetscale.MySQLDatabase("app-db", {
111 region: { slug: "us-east" },
112 clusterSize: "PS_10",
113 });
114
115 const branch = yield* Planetscale.MySQLBranch("app-branch", {
116 database,
117 isProduction: false,
118 migrations: "./migrations",
119 });
120
121 const password = yield* Planetscale.MySQLPassword("app-password", {
122 database,
123 branch,
124 role: "readwriter",
125 });
126 ```
127
128 Non-production branches run on the `PS_DEV` size, and the password's
129 `role` is a Vitess access level (`"reader"`, `"writer"`, `"admin"`,
130 `"readwriter"`) rather than inherited Postgres roles. Migrations
131 behave slightly differently on Vitess — DDL commits implicitly, so
132 prefer one schema change per file — see the engine differences in
133 [Migrations](/planetscale/data/migrations).
134
135 ## Deploy the owner first
136
137 A ref can only resolve against state that exists, so the owning
138 stage deploys before the PR stage that references it:
139
140 ```sh
141 alchemy deploy --stage staging-pr-42 # creates the database
142 alchemy deploy --stage pr-42 # references it, forks a branch
143 ```
144
145 Deploying `pr-42` first fails at plan time with
146 `InvalidReferenceError` — there's nothing under
147 `{ stack, stage: "staging-pr-42", id: "app-db" }` to read yet.
148
149 ## Tear down
150
151 ```sh
152 alchemy destroy --stage pr-42
153 ```
154
155 Destroy removes the per-stage resources — branch, credential,
156 compute — but leaves the referenced database untouched: the PR stage
157 doesn't own it, so it can't delete it.
158
159 ## Wire it into your runtime
160
161 The snippets above end at a credential. Connecting it to compute is
162 runtime-specific:
163
164 - [Shared database across stages](/cloudflare/data/shared-database)
165 — the general `Resource.ref` pattern, step by step.
166 - [Branch from a shared database](/cloudflare/data/branch-from-shared-database)
167 — the full walkthrough of this pattern with a Cloudflare Worker on
168 the other end.
169 - [Hyperdrive](/cloudflare/data/hyperdrive) — `role.origin` /
170 `password.origin` plug straight into a
171 `Cloudflare.Hyperdrive.Connection`.
172
173 Complete working projects:
174 [`cloudflare-planetscale-postgres-drizzle`](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-planetscale-postgres-drizzle)
175 and
176 [`cloudflare-planetscale-mysql-drizzle`](https://github.com/alchemy-run/alchemy/tree/main/examples/cloudflare-planetscale-mysql-drizzle).
177
178 ## Where next
179
180 - [Drizzle ORM with PlanetScale](/planetscale/guides/drizzle) —
181 generate the migrations each preview branch applies.
182 - [Migrations](/planetscale/data/migrations) — how migration files
183 are ordered, hashed, and tracked.
184 - [Postgres](/planetscale/data/postgres) and [MySQL](/planetscale/data/mysql)
185 — the two resource families used above.