@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 199 lines 6.94 KB
Raw
1 ---
2 title: Postgres
3 description: PlanetScale Postgres as Stack resources — databases, branches, roles with least-privilege inherited roles, and direct vs pooled connection origins.
4 ---
5
6 PlanetScale Postgres is managed PostgreSQL with database branching. In
7 alchemy the database, its branches, and the roles that connect to them
8 are resources in the same Stack as your compute — a branch forks per
9 preview stage and tears down with it, and a role's credentials flow
10 into whatever consumes them (Cloudflare Hyperdrive, a Worker, a
11 Lambda) as typed outputs.
12
13 New here? [Set up credentials](/planetscale/setup) first. For the
14 MySQL (Vitess) family, see [MySQL](/planetscale/data/mysql).
15
16 ## Create a database
17
18 `PostgresDatabase` owns the long-lived cluster. `clusterSize` is
19 required.
20
21 Network-attached (NAS) sizes like `"PS_10"` are expanded to the full
22 SKU using the target region and architecture:
23
24 ```typescript
25 import * as Planetscale from "@alchemy.run/planetscale";
26
27 const database = yield* Planetscale.PostgresDatabase("app-db", {
28 region: { slug: "us-east" },
29 clusterSize: "PS_10",
30 });
31 ```
32
33 [PlanetScale Metal](https://planetscale.com/docs/metal) is supported
34 too. Metal uses locally-attached NVMe, so the API needs the **full
35 SKU** — CPU series, compute size, provider, architecture, and drive
36 size — not a short `"M-10"` name. Copy a SKU from
37 [Postgres pricing](https://planetscale.com/docs/postgres/pricing) or
38 your org's `list_cluster_size_skus` response; hyphens from the docs
39 are normalized to underscores:
40
41 ```typescript
42 const metal = yield* Planetscale.PostgresDatabase("app-db-metal", {
43 region: { slug: "us-east" },
44 clusterSize: "M1_10_AWS_ARM_D_METAL_10",
45 arch: "arm",
46 });
47 ```
48
49 No name required — alchemy generates a unique one from the app,
50 stage, and logical ID. Pass `name` to control it.
51
52 Changing `clusterSize` resizes the cluster in place through
53 PlanetScale's change-request API (alchemy queues the change and waits
54 for it to complete). Changing `region`, `replicas`, or `arch`
55 replaces the database.
56
57 ## Branch the database
58
59 `PostgresBranch` is a cheap fork. Pass the database resource (or a
60 plain string name) and, optionally, a parent branch:
61
62 ```typescript
63 const branch = yield* Planetscale.PostgresBranch("app-branch", {
64 database,
65 parentBranch: "main",
66 });
67 ```
68
69 `parentBranch` defaults to `"main"` and also accepts another
70 `PostgresBranch`, so branches can chain. Branches take the same
71 `migrations` / `importFiles` props as the database — see
72 [Migrations](/planetscale/data/migrations) for how SQL files are hashed
73 and applied, and the
74 [branch from a shared database](/cloudflare/data/branch-from-shared-database)
75 guide for the branch-per-PR pattern.
76
77 ## Roles
78
79 `PostgresRole` materializes a Postgres user + password on a branch.
80 Permissions come from `inheritedRoles` — built-in roles like
81 `postgres` or the `pg_*` family:
82
83 ```typescript
84 const role = yield* Planetscale.PostgresRole("app-role", {
85 database,
86 branch,
87 inheritedRoles: ["postgres"],
88 });
89 ```
90
91 Scope roles down to what each consumer needs:
92
93 ```typescript
94 const reader = yield* Planetscale.PostgresRole("reader", {
95 database,
96 branch,
97 inheritedRoles: ["pg_read_all_data", "pg_read_all_settings"],
98 });
99 ```
100
101 Pass `ttl` (seconds) for short-lived credentials. PlanetScale returns
102 the password exactly once at create time, so almost every prop change
103 — `ttl`, `database`, `branch`, `inheritedRoles` — replaces the role
104 with a fresh one whose new credentials propagate to downstream
105 resources automatically. Only the role's `name` and its `successor`
106 (the role that inherits ownership when this one is dropped) update in
107 place.
108
109 ## The default role
110
111 Every branch comes with a built-in default role. `PostgresDefaultRole`
112 captures it as a resource:
113
114 ```typescript
115 const defaultRole = yield* Planetscale.PostgresDefaultRole("main-role", {
116 database,
117 forceReset: true,
118 });
119 ```
120
121 Two caveats, both consequences of the password being returned only at
122 create time:
123
124 - **No adoption.** If the branch's default role already exists and
125 your Stack has no record of it, the deploy fails rather than
126 silently taking over. Opt in with `forceReset: true`, which resets
127 the role — same role, **new password** — invalidating any existing
128 credentials.
129 - **Destroy resets, not deletes.** There is no delete endpoint for
130 the default role, so destroying the resource resets it to
131 invalidate the credentials your Stack was holding.
132
133 Prefer `PostgresRole` for application access; reach for the default
134 role when a tool specifically needs it.
135
136 ## `origin` vs `pooledOrigin`
137
138 Both role resources expose parsed connection components ready to feed
139 into consumers like [Cloudflare Hyperdrive](/cloudflare/data/hyperdrive):
140
141 - `role.origin` — the **direct** connection (port 5432). Use it where
142 the consumer does its own pooling, e.g. as a Hyperdrive origin.
143 - `role.pooledOrigin` — the **pooled** connection via PSBouncer
144 (port 6432). Use it where each request would otherwise open a fresh
145 direct connection, e.g. Hyperdrive's local-dev origin.
146
147 ```typescript
148 import * as Cloudflare from "@alchemy.run/cloudflare";
149
150 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
151 origin: role.origin, // direct — Hyperdrive pools at the edge
152 dev: role.pooledOrigin, // local dev bypasses Hyperdrive, so pool at PlanetScale
153 });
154 ```
155
156 If you need a URL instead of components, `connectionUrl` and
157 `connectionUrlPooled` carry the same direct/pooled endpoints as
158 `Redacted` connection strings (`sslmode=verify-full`).
159
160 ## Connect privately with AWS PrivateLink
161
162 Postgres roles expose the branch's provider-neutral private connection
163 details. For AWS PrivateLink, pass `privateConnectionServiceName` to
164 an Interface VPC endpoint. With private DNS enabled, use
165 `privateHost` for workloads in that VPC:
166
167 ```typescript
168 import * as AWS from "@alchemy.run/aws";
169
170 const endpoint = yield* AWS.EC2.VpcEndpoint("postgres-private-link", {
171 vpcId: vpc.vpcId,
172 serviceName: role.privateConnectionServiceName,
173 vpcEndpointType: "Interface",
174 subnetIds: [privateSubnet.subnetId],
175 securityGroupIds: [databaseSecurityGroup.groupId],
176 privateDnsEnabled: true,
177 });
178 ```
179
180 For GCP Private Service Connect, `privateHost` is the private DNS zone;
181 prepend the endpoint name configured in GCP before connecting.
182 `PostgresDefaultRole` exposes the same details, though `PostgresRole`
183 remains the safer choice for applications.
184
185 ## Where next
186
187 - [Migrations](/planetscale/data/migrations) — `migrations` and
188 `importFiles` on databases and branches.
189 - [Hyperdrive](/cloudflare/data/hyperdrive) — edge-pooled connections from
190 Workers to your PlanetScale database.
191 - [Drizzle guide](/cloudflare/data/drizzle) — generate migration SQL
192 from a Drizzle schema and apply it on deploy.
193
194 Reference:
195
196 - [PostgresDatabase](/providers/planetscale/postgres/postgresdatabase) ·
197 [PostgresBranch](/providers/planetscale/postgres/postgresbranch) ·
198 [PostgresRole](/providers/planetscale/postgres/postgresrole) ·
199 [PostgresDefaultRole](/providers/planetscale/postgres/postgresdefaultrole)