The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 135 lines 4.58 KB
Raw
1 ---
2 title: Credentials
3 description: PlanetScale credentials as Stack resources — Postgres roles, the default role and forceReset, MySQL passwords, TTLs, CIDR allowlists, and direct vs pooled connection origins.
4 ---
5
6 PlanetScale credentials are resources: Postgres branches use **roles**
7 (`PostgresRole`, `PostgresDefaultRole`), MySQL branches use
8 **passwords** (`MySQLPassword`). One rule shapes all three —
9 PlanetScale returns the plaintext exactly once, at create time.
10 Alchemy stores it `Redacted` in state, and any change it can't apply
11 in place mints a fresh credential whose new plaintext propagates to
12 downstream resources automatically.
13
14 ## Postgres roles
15
16 `PostgresRole` mints a Postgres user + password on a branch;
17 permissions come from `inheritedRoles`:
18
19 ```typescript
20 import * as Planetscale from "@alchemy.run/planetscale";
21
22 const reader = yield* Planetscale.PostgresRole("reader", {
23 database,
24 branch, // defaults to "main"
25 inheritedRoles: ["pg_read_all_data", "pg_read_all_settings"],
26 });
27 ```
28
29 Only `name` and `successor` (the role that inherits ownership when
30 this one is dropped) update in place — changing `ttl`,
31 `inheritedRoles`, `withReplication`, `database`, or `branch` replaces
32 the role with a new id, name, and password.
33
34 A logical-replication consumer (Electric, Debezium, a CDC pipeline)
35 needs the `REPLICATION` attribute, which Postgres never grants through
36 role membership. PlanetScale issues it only alongside `postgres`:
37
38 ```typescript
39 const replicator = yield* Planetscale.PostgresRole("replicator", {
40 database,
41 inheritedRoles: ["postgres"],
42 withReplication: true,
43 });
44 ```
45
46 ## The default role
47
48 Every Postgres branch ships with a built-in default role;
49 `PostgresDefaultRole` captures it as a resource:
50
51 ```typescript
52 const defaultRole = yield* Planetscale.PostgresDefaultRole("main-role", {
53 database,
54 forceReset: true,
55 });
56 ```
57
58 The default role cannot be adopted: if it already exists and your
59 Stack has no record of it, the deploy fails
60 (`Default role already exists ... Use forceReset: true to reset`)
61 rather than silently taking over. `forceReset: true` opts in by
62 resetting it — same role, **new password** — which invalidates any
63 credentials other systems were using. Destroying the resource also
64 resets rather than deletes (PlanetScale has no delete endpoint for
65 it). Prefer `PostgresRole` for application access.
66
67 ## MySQL passwords
68
69 `MySQLPassword` mints credentials scoped to one branch and one role —
70 `"reader"`, `"writer"`, `"admin"`, or `"readwriter"`:
71
72 ```typescript
73 const password = yield* Planetscale.MySQLPassword("app-password", {
74 database,
75 branch, // defaults to "main"
76 role: "reader",
77 });
78 ```
79
80 `name` and `cidrs` update in place (same id, no new plaintext);
81 changing `role`, `ttl`, `replica`, `database`, or `branch` replaces
82 the password and deletes the old one.
83
84 ## TTLs and CIDR allowlists
85
86 Both families take a `ttl` (seconds) for credentials that expire on
87 their own; `MySQLPassword` additionally takes `cidrs` to restrict
88 which IP ranges may connect:
89
90 ```typescript
91 const admin = yield* Planetscale.MySQLPassword("admin-password", {
92 database,
93 role: "admin",
94 ttl: 86400,
95 cidrs: ["203.0.113.0/24"],
96 });
97 ```
98
99 Changing `ttl` is a replacement on both roles and passwords (the
100 expiry is baked in at create time); editing `cidrs` on a MySQL
101 password syncs in place on the next deploy.
102
103 ## `origin` vs `pooledOrigin`
104
105 Credentials expose parsed connection components ready to feed into
106 consumers like [Cloudflare Hyperdrive](/cloudflare/data/hyperdrive).
107 `PostgresRole` has two: `origin` is the direct connection (port
108 5432), `pooledOrigin` goes through PSBouncer (port 6432):
109
110 ```typescript
111 import * as Cloudflare from "@alchemy.run/cloudflare";
112
113 const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
114 origin: role.origin, // direct — Hyperdrive pools at the edge
115 dev: role.pooledOrigin, // local dev bypasses Hyperdrive, so pool at PlanetScale
116 });
117 ```
118
119 `MySQLPassword` exposes a single `origin`, and `PostgresDefaultRole`
120 carries the same direct/pooled endpoints as `Redacted` URL strings
121 (`connectionUrl` / `connectionUrlPooled`), as does `PostgresRole`.
122
123 ## Where next
124
125 - [Postgres](/planetscale/data/postgres) — databases, branches, and roles
126 in context.
127 - [MySQL](/planetscale/data/mysql) — the Vitess side, end to end.
128 - [Hyperdrive](/cloudflare/data/hyperdrive) — edge-pooled connections from
129 Workers to your PlanetScale database.
130
131 Reference:
132
133 - [PostgresRole](/providers/planetscale/postgres/postgresrole) ·
134 [PostgresDefaultRole](/providers/planetscale/postgres/postgresdefaultrole) ·
135 [MySQLPassword](/providers/planetscale/mysql/mysqlpassword)