The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { |
| 2 | diffMigrations, |
| 3 | migrationsAttrs, |
| 4 | migrationsInputOf, |
| 5 | stampedOf, |
| 6 | type MigrationsInput, |
| 7 | } from "@alchemy.run/sql/Migrations"; |
| 8 | import { hashImports } from "@alchemy.run/sql/SqlFile"; |
| 9 | import { |
| 10 | createProjectBranch, |
| 11 | createProjectEndpoint, |
| 12 | deleteProjectEndpoint, |
| 13 | getProject, |
| 14 | listProjectBranchEndpoints, |
| 15 | updateProjectEndpoint, |
| 16 | deleteProjectBranch, |
| 17 | getConnectionURI, |
| 18 | getProjectBranch, |
| 19 | listProjectBranchDatabases, |
| 20 | listProjectBranches, |
| 21 | type ListProjectBranchesResponse, |
| 22 | listProjects, |
| 23 | type ListProjectsResponse, |
| 24 | updateProjectBranch, |
| 25 | } from "@distilled.cloud/neon"; |
| 26 | import { OwnedBySomeoneElse, Unowned } from "alchemy/AdoptPolicy"; |
| 27 | import { isResolved } from "alchemy/Diff"; |
| 28 | import { createPhysicalName } from "alchemy/PhysicalName"; |
| 29 | import * as Provider from "alchemy/Provider"; |
| 30 | import { Resource } from "alchemy/Resource"; |
| 31 | import { recordsEqual } from "alchemy/Util/equal"; |
| 32 | import * as Data from "effect/Data"; |
| 33 | import * as Effect from "effect/Effect"; |
| 34 | import * as Redacted from "effect/Redacted"; |
| 35 | import * as Schedule from "effect/Schedule"; |
| 36 | import { runImports, runPgMigrations } from "./Migrations.ts"; |
| 37 | import { parsePostgresOrigin, type PostgresOrigin } from "./PostgresOrigin.ts"; |
| 38 | import { DeletionPending, type Project, waitForOperations } from "./Project.ts"; |
| 39 | import type { Providers } from "./Providers.ts"; |
| 40 | |
| 41 | export type BranchSource = Project | { projectId: string }; |
| 42 | |
| 43 | export type ParentBranchSource = Branch | { branchId: string } | { name: string }; |
| 44 | |
| 45 | export type BranchEndpointConfig = { |
| 46 | /** Endpoint access mode. A branch has exactly one read-write endpoint. */ |
| 47 | type: "read_only" | "read_write"; |
| 48 | /** Minimum compute units. Removing this setting restores the project default. */ |
| 49 | autoscalingLimitMinCu?: number; |
| 50 | /** Maximum compute units. Removing this setting restores the project default. */ |
| 51 | autoscalingLimitMaxCu?: number; |
| 52 | /** Idle timeout in seconds; 0 selects the plan default and -1 disables suspension. */ |
| 53 | suspendTimeoutSeconds?: number; |
| 54 | }; |
| 55 | |
| 56 | export type BranchProps = { |
| 57 | /** |
| 58 | * The Neon project (or `{ projectId }`) to create the branch in. |
| 59 | */ |
| 60 | project: BranchSource; |
| 61 | /** |
| 62 | * Branch name. If omitted, a unique name is generated from |
| 63 | * `${app}-${stage}-${id}`. |
| 64 | */ |
| 65 | name?: string; |
| 66 | /** |
| 67 | * The parent branch to fork from. Accepts a `Branch`, a |
| 68 | * `{ branchId }`, or `{ name }` to look up by name. Defaults to the |
| 69 | * project's default branch. |
| 70 | */ |
| 71 | parentBranch?: ParentBranchSource; |
| 72 | /** |
| 73 | * A Log Sequence Number on the parent branch. The new branch is created |
| 74 | * with parent data as of this LSN. |
| 75 | */ |
| 76 | parentLsn?: string; |
| 77 | /** |
| 78 | * An ISO-8601 timestamp identifying a point in time on the parent branch |
| 79 | * to fork from. |
| 80 | */ |
| 81 | parentTimestamp?: string; |
| 82 | /** |
| 83 | * Whether the branch is protected from deletion / mutation. |
| 84 | * |
| 85 | * @default false |
| 86 | */ |
| 87 | protected?: boolean; |
| 88 | /** |
| 89 | * Initialization source. |
| 90 | * |
| 91 | * - `parent-data` (default) — copy schema and data from the parent. |
| 92 | * - `schema-only` — copy only the schema. |
| 93 | */ |
| 94 | initSource?: "schema-only" | "parent-data"; |
| 95 | /** |
| 96 | * RFC-3339 timestamp at which Neon should auto-delete the branch. |
| 97 | * Useful for ephemeral preview branches. |
| 98 | */ |
| 99 | expiresAt?: string; |
| 100 | /** |
| 101 | * Compute endpoints owned by this branch. Exactly one `read_write` endpoint |
| 102 | * is required for the connection outputs. Settings update in place; removing |
| 103 | * a setting restores the project default and removing an endpoint deletes it. |
| 104 | * Do not independently manage endpoints on a branch managed by this resource. |
| 105 | * |
| 106 | * @default [{ type: "read_write" }] |
| 107 | */ |
| 108 | endpoints?: BranchEndpointConfig[]; |
| 109 | /** |
| 110 | * SQL migrations to apply against the branch. Accepts a directory path, a |
| 111 | * `Drizzle.Schema` resource, or `{ dir, table? }`. |
| 112 | * |
| 113 | * Bookkeeping always lives in Alchemy's `__alchemy_migrations` table. A |
| 114 | * database previously migrated by drizzle-kit or Prisma is adopted by a |
| 115 | * one-way conversion on first deploy: the old tool's applied history is |
| 116 | * copied into Alchemy's table and the old table is left frozen. No |
| 117 | * baselining required. |
| 118 | */ |
| 119 | migrations?: MigrationsInput; |
| 120 | /** |
| 121 | * Paths to additional `.sql` files to apply after migrations. |
| 122 | */ |
| 123 | importFiles?: string[]; |
| 124 | }; |
| 125 | |
| 126 | export type Branch = Resource< |
| 127 | "Neon.Branch", |
| 128 | BranchProps, |
| 129 | { |
| 130 | /** Neon branch identifier. */ |
| 131 | branchId: string; |
| 132 | /** Observed branch name. */ |
| 133 | branchName: string; |
| 134 | /** Owning project identifier. */ |
| 135 | projectId: string; |
| 136 | /** Parent branch identifier, when present. */ |
| 137 | parentBranchId: string | undefined; |
| 138 | /** Parent log sequence number used for the fork. */ |
| 139 | parentLsn: string | undefined; |
| 140 | /** Parent timestamp used for the fork. */ |
| 141 | parentTimestamp: string | undefined; |
| 142 | /** Whether the fork copied data or only schema. */ |
| 143 | initSource: "schema-only" | "parent-data" | undefined; |
| 144 | /** Whether deletion and mutation protection is enabled. */ |
| 145 | protected: boolean; |
| 146 | /** Whether this is the project's current default branch. */ |
| 147 | default: boolean; |
| 148 | /** Automatic expiration timestamp, when configured. */ |
| 149 | expiresAt: string | undefined; |
| 150 | /** Database selected for connection outputs and migrations. */ |
| 151 | databaseName: string; |
| 152 | /** Observed owner of the selected database. */ |
| 153 | roleName: string; |
| 154 | /** Postgres connection URI for the branch's primary database. */ |
| 155 | connectionUri: string; |
| 156 | /** Pooled connection URI (uses pgbouncer). */ |
| 157 | pooledConnectionUri: string; |
| 158 | /** |
| 159 | * Parsed connection components ready to feed into a Postgres origin |
| 160 | * — e.g. `Cloudflare.Hyperdrive`'s `origin` prop. Points at the |
| 161 | * direct (non-pooled) endpoint, which is the recommended target |
| 162 | * when fronting Neon with another pooler like Hyperdrive. |
| 163 | */ |
| 164 | origin: PostgresOrigin; |
| 165 | /** |
| 166 | * Parsed pooled connection components. Useful as a Hyperdrive `dev` |
| 167 | * origin when local workers bypass Hyperdrive and connect directly. |
| 168 | */ |
| 169 | pooledOrigin: PostgresOrigin; |
| 170 | /** Directory of the applied SQL migrations. */ |
| 171 | migrationsDir: string | undefined; |
| 172 | /** Migration bookkeeping table. */ |
| 173 | migrationsTable: string | undefined; |
| 174 | /** Applied migration content hashes. */ |
| 175 | migrationsHashes: Record<string, string>; |
| 176 | /** Applied SQL import content hashes. */ |
| 177 | importHashes: Record<string, string>; |
| 178 | }, |
| 179 | never, |
| 180 | Providers |
| 181 | >; |
| 182 | |
| 183 | /** |
| 184 | * A branch of a Neon project. |
| 185 | * |
| 186 | * Branches are first-class, copy-on-write copies of a parent branch — they |
| 187 | * share storage with the parent until the new branch starts diverging. |
| 188 | * ### Branching from a project's default branch |
| 189 | * **Example:** Basic branch |
| 190 | * ```typescript |
| 191 | * const project = yield* Neon.Project("my-project"); |
| 192 | * const dev = yield* Neon.Branch("dev-branch", { project }); |
| 193 | * ``` |
| 194 | * |
| 195 | * ### Branching from another branch |
| 196 | * **Example:** Branch off another branch |
| 197 | * ```typescript |
| 198 | * const dev = yield* Neon.Branch("dev", { project }); |
| 199 | * const featureBranch = yield* Neon.Branch("feature", { |
| 200 | * project, |
| 201 | * parentBranch: dev, |
| 202 | * }); |
| 203 | * ``` |
| 204 | * |
| 205 | * ### Point-in-time branches |
| 206 | * **Example:** Branch from a parent at a specific LSN |
| 207 | * ```typescript |
| 208 | * const branch = yield* Neon.Branch("at-lsn", { |
| 209 | * project, |
| 210 | * parentLsn: "0/3FA01B0", |
| 211 | * }); |
| 212 | * ``` |
| 213 | * |
| 214 | * ### Configuring the default branch |
| 215 | * Adopt the project's default branch to manage its compute. Destroying the |
| 216 | * stack leaves the branch to be removed with its project, since Neon does |
| 217 | * not delete a project's root or default branch on its own. |
| 218 | * |
| 219 | * **Example:** Adopt the default branch |
| 220 | * ```typescript |
| 221 | * const project = yield* Neon.Project("my-project"); |
| 222 | * const main = yield* Neon.Branch("main", { |
| 223 | * project, |
| 224 | * name: "main", |
| 225 | * endpoints: [{ type: "read_write", autoscalingLimitMaxCu: 1 }], |
| 226 | * }).pipe(adopt(true)); |
| 227 | * ``` |
| 228 | * |
| 229 | * ### Migrations on a branch |
| 230 | * **Example:** Apply migrations on the branch only |
| 231 | * ```typescript |
| 232 | * const featureBranch = yield* Neon.Branch("feature", { |
| 233 | * project, |
| 234 | * migrations: "./migrations", |
| 235 | * }); |
| 236 | * ``` |
| 237 | * |
| 238 | * @see https://neon.tech/docs/manage/branches/ |
| 239 | * |
| 240 | * @resource |
| 241 | * @product Branch |
| 242 | */ |
| 243 | export const Branch = Resource<Branch>("Neon.Branch"); |
| 244 | |
| 245 | export const BranchProvider = () => |
| 246 | Provider.succeed(Branch, { |
| 247 | stables: ["branchId", "projectId"], |
| 248 | diff: Effect.fn(function* ({ id, olds, news, output }) { |
| 249 | // Normally we short-circuit on `isResolved(news)` at the beginning. |
| 250 | // However, this wouldn't detect an upstream project change, causing an update when what we really want is a replace. |
| 251 | // So, we check the project first before short-circuiting. `projectId` is a stable attribute of `Project`, so the |
| 252 | // planning engine resolves `news.project` to a plain object carrying that stable id (even when the project is being |
| 253 | // updated in place). An unchanged project therefore resolves to the same string; a changed/replaced project resolves |
| 254 | // to either a different string or an unresolved output, so `oldProjectId !== newProjectId` evaluates correctly. |
| 255 | // An Output-valued `project` doesn't survive a `creating`-state |
| 256 | // round-trip (it deserializes as `undefined`) — when the old project is |
| 257 | // unknown, fall through to the create/update recovery path rather than |
| 258 | // force a replacement. |
| 259 | const oldProjectId = |
| 260 | output?.projectId ?? |
| 261 | (olds.project !== undefined |
| 262 | ? maybeResolveProjectId(olds.project as BranchSource) |
| 263 | : undefined); |
| 264 | const newProjectId = |
| 265 | "project" in news ? maybeResolveProjectId(news.project as BranchSource) : undefined; |
| 266 | if (oldProjectId !== undefined && oldProjectId !== newProjectId) { |
| 267 | return { action: "replace" } as const; |
| 268 | } |
| 269 | const pending = news as Partial<BranchProps>; |
| 270 | const replacement = { |
| 271 | action: "replace", |
| 272 | deleteFirst: |
| 273 | pending.name !== undefined && |
| 274 | pending.name === (output?.branchName ?? olds.name) && |
| 275 | oldProjectId === newProjectId, |
| 276 | } as const; |
| 277 | // A fork point only known at apply time cannot be proven unchanged, and |
| 278 | // `reconcile` never re-forks an existing branch, so an update would |
| 279 | // silently keep the old data. |
| 280 | if ( |
| 281 | output && |
| 282 | !isResolved([ |
| 283 | pending.parentBranch, |
| 284 | pending.parentLsn, |
| 285 | pending.parentTimestamp, |
| 286 | pending.initSource, |
| 287 | ]) |
| 288 | ) { |
| 289 | return replacement; |
| 290 | } |
| 291 | if (!isResolved(news)) return undefined; |
| 292 | if ( |
| 293 | olds.parentLsn !== news.parentLsn || |
| 294 | olds.parentTimestamp !== news.parentTimestamp || |
| 295 | (olds.initSource ?? "parent-data") !== (news.initSource ?? "parent-data") |
| 296 | ) { |
| 297 | return replacement; |
| 298 | } |
| 299 | if (output && news.parentBranch) { |
| 300 | const parent = yield* resolveParentBranchId( |
| 301 | news.parentBranch as ParentBranchSource, |
| 302 | output.projectId, |
| 303 | ); |
| 304 | // Schema-only branches are roots; the source is a creation input, |
| 305 | // not an observed parent relationship. |
| 306 | const previousParent = |
| 307 | news.initSource === "schema-only" |
| 308 | ? yield* resolveParentBranchId( |
| 309 | olds.parentBranch as ParentBranchSource | undefined, |
| 310 | output.projectId, |
| 311 | ) |
| 312 | : output.parentBranchId; |
| 313 | if (parent !== previousParent) return replacement; |
| 314 | } else if (output && olds.parentBranch && !news.parentBranch) { |
| 315 | return replacement; |
| 316 | } |
| 317 | const oldName = output?.branchName ?? (yield* createBranchName(id, olds.name)); |
| 318 | // Auto-generated names are engine-owned: the deployed name stays |
| 319 | // authoritative even if the generator would name this id differently |
| 320 | // today. Only an explicit user-provided name can force a rename. |
| 321 | const newName = news.name ?? oldName; |
| 322 | if ( |
| 323 | newName !== oldName || |
| 324 | (news.protected ?? false) !== (output?.protected ?? false) || |
| 325 | (news.expiresAt ?? undefined) !== (output?.expiresAt ?? undefined) |
| 326 | ) { |
| 327 | return { action: "update" } as const; |
| 328 | } |
| 329 | if (yield* diffMigrations({ news, output })) { |
| 330 | return { action: "update" } as const; |
| 331 | } |
| 332 | if (news.importFiles?.length) { |
| 333 | const newHashes = yield* hashImports(news.importFiles, yield* rootDir); |
| 334 | if (!recordsEqual(newHashes, output?.importHashes ?? {})) { |
| 335 | return { action: "update" } as const; |
| 336 | } |
| 337 | } |
| 338 | return undefined; |
| 339 | }), |
| 340 | read: Effect.fn(function* ({ id, output, olds, previous }) { |
| 341 | if (output?.branchId) { |
| 342 | return yield* getProjectBranch({ |
| 343 | project_id: output.projectId, |
| 344 | branch_id: output.branchId, |
| 345 | }).pipe( |
| 346 | Effect.flatMap(({ branch }) => hydrateBranch(output.projectId, branch, output)), |
| 347 | Effect.catchTag("NotFound", () => Effect.undefined), |
| 348 | ); |
| 349 | } |
| 350 | if (!olds?.project) return undefined; |
| 351 | const projectId = maybeResolveProjectId(olds.project as BranchSource); |
| 352 | if (projectId === undefined) { |
| 353 | // The project reference survived as an object but its Output-valued |
| 354 | // `projectId` did not — there is nothing to look the branch up in. |
| 355 | return undefined; |
| 356 | } |
| 357 | const name = yield* createBranchName(id, olds.name); |
| 358 | // The whole project may already be gone (out-of-band deletion); the |
| 359 | // branch is gone with it, so recovery observes an absent branch. |
| 360 | const matches = yield* findBranchByName(projectId, name).pipe( |
| 361 | Effect.catchTag("NotFound", () => Effect.succeed([])), |
| 362 | ); |
| 363 | if (matches.length > 1) |
| 364 | return yield* new BranchStateError({ reason: "Ambiguous branch name" }); |
| 365 | const match = matches[0]; |
| 366 | if (!match) return undefined; |
| 367 | const attrs = yield* hydrateBranch(projectId, match); |
| 368 | // The generation a replacement is replacing is ours. |
| 369 | if (attrs && attrs.branchId === previous?.branchId) return attrs; |
| 370 | return attrs && Unowned(attrs); |
| 371 | }), |
| 372 | reconcile: Effect.fn(function* ({ id, news, output }) { |
| 373 | const projectId = yield* resolveProjectId(news.project as BranchSource); |
| 374 | const newName = news.name ?? output?.branchName ?? (yield* createBranchName(id, undefined)); |
| 375 | const endpoints = news.endpoints ?? [{ type: "read_write" as const }]; |
| 376 | if (endpoints.filter((endpoint) => endpoint.type === "read_write").length !== 1) { |
| 377 | return yield* new BranchStateError({ |
| 378 | reason: "Branch requires exactly one read_write endpoint for its connection outputs", |
| 379 | }); |
| 380 | } |
| 381 | // Approval of a cached branch never authorizes a different same-name ID. |
| 382 | const authorize = ( |
| 383 | branch: ListProjectBranchesResponse["branches"][number], |
| 384 | ): Effect.Effect<ListProjectBranchesResponse["branches"][number], OwnedBySomeoneElse> => |
| 385 | projectId === output?.projectId && branch.id === output.branchId |
| 386 | ? Effect.succeed(branch) |
| 387 | : Effect.fail( |
| 388 | new OwnedBySomeoneElse({ |
| 389 | message: `Neon branch "${newName}" requires explicit adoption`, |
| 390 | resourceType: "Neon.Branch", |
| 391 | logicalId: id, |
| 392 | physicalName: branch.id, |
| 393 | }), |
| 394 | ); |
| 395 | let observed = |
| 396 | output?.branchId && output.projectId === projectId |
| 397 | ? yield* getProjectBranch({ |
| 398 | project_id: projectId, |
| 399 | branch_id: output.branchId, |
| 400 | }).pipe( |
| 401 | Effect.map(({ branch }) => branch), |
| 402 | Effect.catchTag("NotFound", () => Effect.undefined), |
| 403 | ) |
| 404 | : undefined; |
| 405 | if (!observed) { |
| 406 | const matches = yield* findBranchByName(projectId, newName); |
| 407 | if (matches.length > 1) |
| 408 | return yield* new BranchStateError({ |
| 409 | reason: "Ambiguous branch name", |
| 410 | }); |
| 411 | observed = matches[0] ? yield* authorize(matches[0]) : undefined; |
| 412 | } |
| 413 | if (!observed) { |
| 414 | const parentBranchId = yield* resolveParentBranchId( |
| 415 | news.parentBranch as ParentBranchSource | undefined, |
| 416 | projectId, |
| 417 | ); |
| 418 | const created = yield* createProjectBranch({ |
| 419 | project_id: projectId, |
| 420 | branch: { |
| 421 | name: newName, |
| 422 | parent_id: parentBranchId, |
| 423 | parent_lsn: news.parentLsn, |
| 424 | parent_timestamp: news.parentTimestamp, |
| 425 | init_source: news.initSource, |
| 426 | protected: news.protected, |
| 427 | expires_at: news.expiresAt, |
| 428 | }, |
| 429 | endpoints: buildEndpoints(endpoints), |
| 430 | }).pipe( |
| 431 | Effect.catchTag("Conflict", (error) => |
| 432 | findBranchByName(projectId, newName).pipe( |
| 433 | Effect.flatMap( |
| 434 | Effect.fn(function* (matches) { |
| 435 | if (matches.length !== 1) return yield* error; |
| 436 | const branch = yield* authorize(matches[0]!); |
| 437 | return { branch, operations: [] }; |
| 438 | }), |
| 439 | ), |
| 440 | ), |
| 441 | ), |
| 442 | ); |
| 443 | yield* waitForOperations(created.operations); |
| 444 | observed = created.branch; |
| 445 | } |
| 446 | if ( |
| 447 | observed.name !== newName || |
| 448 | observed.protected !== (news.protected ?? false) || |
| 449 | observed.expires_at !== news.expiresAt |
| 450 | ) { |
| 451 | const updated = yield* updateProjectBranch({ |
| 452 | project_id: projectId, |
| 453 | branch_id: observed.id, |
| 454 | branch: { |
| 455 | name: observed.name !== newName ? newName : undefined, |
| 456 | protected: |
| 457 | observed.protected !== (news.protected ?? false) |
| 458 | ? (news.protected ?? false) |
| 459 | : undefined, |
| 460 | expires_at: |
| 461 | observed.expires_at !== news.expiresAt ? (news.expiresAt ?? null) : undefined, |
| 462 | }, |
| 463 | }); |
| 464 | yield* waitForOperations(updated.operations); |
| 465 | } |
| 466 | yield* syncEndpoints(projectId, observed.id, endpoints); |
| 467 | const current = yield* getProjectBranch({ |
| 468 | project_id: projectId, |
| 469 | branch_id: observed.id, |
| 470 | }); |
| 471 | const branchInfo = yield* hydrateBranch( |
| 472 | projectId, |
| 473 | current.branch, |
| 474 | output?.branchId === observed.id ? output : undefined, |
| 475 | ); |
| 476 | if (!branchInfo) |
| 477 | return yield* new BranchStateError({ |
| 478 | reason: "Branch has no database or connection endpoint", |
| 479 | }); |
| 480 | const previous = branchInfo.branchId === output?.branchId ? output : undefined; |
| 481 | |
| 482 | const connectionUri = Redacted.make(branchInfo.connectionUri); |
| 483 | const migrationsInput = migrationsInputOf(news); |
| 484 | const migrations = migrationsInput |
| 485 | ? yield* runPgMigrations({ |
| 486 | connectionUri, |
| 487 | input: migrationsInput, |
| 488 | stamped: stampedOf(previous), |
| 489 | }) |
| 490 | : undefined; |
| 491 | const importHashes = news.importFiles?.length |
| 492 | ? yield* runImports( |
| 493 | connectionUri, |
| 494 | news.importFiles, |
| 495 | yield* rootDir, |
| 496 | previous?.importHashes ?? {}, |
| 497 | ) |
| 498 | : {}; |
| 499 | |
| 500 | return { |
| 501 | ...branchInfo, |
| 502 | ...migrationsAttrs({ |
| 503 | input: migrationsInput, |
| 504 | run: migrations, |
| 505 | output: previous, |
| 506 | }), |
| 507 | importHashes, |
| 508 | }; |
| 509 | }), |
| 510 | delete: Effect.fn(function* ({ output }) { |
| 511 | const retained = yield* Effect.gen(function* () { |
| 512 | const { branch } = yield* getProjectBranch({ |
| 513 | project_id: output.projectId, |
| 514 | branch_id: output.branchId, |
| 515 | }); |
| 516 | // Neon refuses to delete a project's root or default branch (an |
| 517 | // adopted `main`, say); it is removed together with the project. |
| 518 | // Schema-only branches are parentless too, but they are deletable. |
| 519 | if ( |
| 520 | branch.default || |
| 521 | (branch.parent_id === undefined && |
| 522 | branch.init_source !== "parent-schema" && |
| 523 | branch.init_source !== "schema-only") |
| 524 | ) { |
| 525 | return true; |
| 526 | } |
| 527 | if (branch.protected) { |
| 528 | const updated = yield* updateProjectBranch({ |
| 529 | project_id: output.projectId, |
| 530 | branch_id: output.branchId, |
| 531 | branch: { protected: false }, |
| 532 | }); |
| 533 | yield* waitForOperations(updated.operations); |
| 534 | } |
| 535 | const deleted = yield* deleteProjectBranch({ |
| 536 | project_id: output.projectId, |
| 537 | branch_id: output.branchId, |
| 538 | }); |
| 539 | yield* waitForOperations(deleted.operations); |
| 540 | return false; |
| 541 | }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(false))); |
| 542 | if (retained) return; |
| 543 | yield* getProjectBranch({ |
| 544 | project_id: output.projectId, |
| 545 | branch_id: output.branchId, |
| 546 | }).pipe( |
| 547 | Effect.flatMap(() => Effect.fail(new DeletionPending({ resourceId: output.branchId }))), |
| 548 | Effect.catchTag("NotFound", () => Effect.void), |
| 549 | Effect.retry({ |
| 550 | while: (error) => error._tag === "NeonDeletionPending", |
| 551 | schedule: Schedule.spaced("2 seconds"), |
| 552 | times: 8, |
| 553 | }), |
| 554 | Effect.timeout("20 seconds"), |
| 555 | ); |
| 556 | }), |
| 557 | // Parent fan-out: branches are scoped to a project, and there is no |
| 558 | // account-wide branch enumeration API. Enumerate every project, then |
| 559 | // list+hydrate the branches of each (bounded concurrency), producing |
| 560 | // the exact `read` Attributes shape for each branch. |
| 561 | list: Effect.fn(function* () { |
| 562 | const projects = yield* listAllProjects; |
| 563 | const perProject = yield* Effect.forEach( |
| 564 | projects, |
| 565 | (project) => |
| 566 | Effect.gen(function* () { |
| 567 | const branches = yield* listAllBranches(project.id); |
| 568 | return yield* Effect.forEach(branches, (branch) => hydrateBranch(project.id, branch), { |
| 569 | concurrency: 10, |
| 570 | }); |
| 571 | }).pipe( |
| 572 | // The project may be deleted between enumeration and listing. |
| 573 | Effect.catchTag("NotFound", () => Effect.succeed([])), |
| 574 | ), |
| 575 | { concurrency: 10 }, |
| 576 | ); |
| 577 | return perProject.flat().filter((row): row is Branch["Attributes"] => row !== undefined); |
| 578 | }), |
| 579 | }); |
| 580 | |
| 581 | const listAllProjects = Effect.gen(function* () { |
| 582 | const projects: ListProjectsResponse["projects"][number][] = []; |
| 583 | let cursor: string | undefined; |
| 584 | while (true) { |
| 585 | const page = yield* listProjects(cursor !== undefined ? { cursor } : {}); |
| 586 | projects.push(...page.projects); |
| 587 | const nextCursor = page.pagination?.cursor; |
| 588 | // Neon returns a `pagination.cursor` on every response (the `created_at` |
| 589 | // of the last row), not a "has next page" flag — stop once a page comes |
| 590 | // back empty or the cursor stops advancing to avoid an infinite loop. |
| 591 | if (page.projects.length === 0 || nextCursor === undefined || nextCursor === cursor) { |
| 592 | break; |
| 593 | } |
| 594 | cursor = nextCursor; |
| 595 | } |
| 596 | return projects; |
| 597 | }); |
| 598 | |
| 599 | const listAllBranches = (projectId: string) => |
| 600 | Effect.gen(function* () { |
| 601 | const branches: ListProjectBranchesResponse["branches"][number][] = []; |
| 602 | let cursor: string | undefined; |
| 603 | do { |
| 604 | const page = yield* listProjectBranches({ |
| 605 | project_id: projectId, |
| 606 | ...(cursor !== undefined ? { cursor } : {}), |
| 607 | }); |
| 608 | branches.push(...page.branches); |
| 609 | cursor = page.pagination?.next; |
| 610 | } while (cursor); |
| 611 | return branches; |
| 612 | }); |
| 613 | |
| 614 | const hydrateBranch = ( |
| 615 | projectId: string, |
| 616 | branch: ListProjectBranchesResponse["branches"][number], |
| 617 | previous?: Branch["Attributes"], |
| 618 | ) => |
| 619 | Effect.gen(function* () { |
| 620 | const dbs = yield* listProjectBranchDatabases({ |
| 621 | project_id: projectId, |
| 622 | branch_id: branch.id, |
| 623 | }); |
| 624 | const db = dbs.databases.find((db) => db.name === previous?.databaseName) ?? dbs.databases[0]; |
| 625 | if (!db) return undefined; |
| 626 | const conn = yield* fetchConnection(projectId, branch.id, db.name, db.owner_name); |
| 627 | const attributes: Branch["Attributes"] = { |
| 628 | branchId: branch.id, |
| 629 | branchName: branch.name, |
| 630 | projectId, |
| 631 | parentBranchId: branch.parent_id, |
| 632 | parentLsn: branch.parent_lsn, |
| 633 | parentTimestamp: branch.parent_timestamp, |
| 634 | initSource: |
| 635 | branch.init_source === "parent-schema" || branch.init_source === "schema-only" |
| 636 | ? "schema-only" |
| 637 | : branch.init_source === "parent-data" |
| 638 | ? "parent-data" |
| 639 | : undefined, |
| 640 | protected: branch.protected, |
| 641 | default: branch.default, |
| 642 | expiresAt: branch.expires_at, |
| 643 | databaseName: db.name, |
| 644 | roleName: db.owner_name, |
| 645 | connectionUri: conn.uri, |
| 646 | pooledConnectionUri: conn.pooled, |
| 647 | origin: parsePostgresOrigin(conn.uri), |
| 648 | pooledOrigin: parsePostgresOrigin(conn.pooled), |
| 649 | migrationsDir: previous?.migrationsDir, |
| 650 | migrationsTable: previous?.migrationsTable, |
| 651 | migrationsHashes: previous?.migrationsHashes ?? {}, |
| 652 | importHashes: previous?.importHashes ?? {}, |
| 653 | }; |
| 654 | return attributes; |
| 655 | }).pipe( |
| 656 | // A branch/database/endpoint can disappear mid-enumeration — skip it. |
| 657 | Effect.catchTag("NotFound", () => Effect.undefined), |
| 658 | ); |
| 659 | |
| 660 | const rootDir = Effect.sync(() => process.cwd()); |
| 661 | const createBranchName = (id: string, name: string | undefined) => |
| 662 | Effect.gen(function* () { |
| 663 | return name ?? (yield* createPhysicalName({ id })); |
| 664 | }); |
| 665 | |
| 666 | const findBranchByName = (projectId: string, name: string) => |
| 667 | Effect.gen(function* () { |
| 668 | const matches: ListProjectBranchesResponse["branches"][number][] = []; |
| 669 | let cursor: string | undefined; |
| 670 | do { |
| 671 | const page = yield* listProjectBranches({ |
| 672 | project_id: projectId, |
| 673 | search: name, |
| 674 | ...(cursor !== undefined ? { cursor } : {}), |
| 675 | }); |
| 676 | for (const b of page.branches) { |
| 677 | if (b.name === name) matches.push(b); |
| 678 | } |
| 679 | cursor = page.pagination?.next; |
| 680 | } while (cursor); |
| 681 | return matches; |
| 682 | }); |
| 683 | |
| 684 | const maybeResolveProjectId = (source: BranchSource): string | undefined => { |
| 685 | if (source && "projectId" in source && typeof source.projectId === "string") { |
| 686 | return source.projectId; |
| 687 | } |
| 688 | return undefined; |
| 689 | }; |
| 690 | |
| 691 | const resolveProjectId = (source: BranchSource) => { |
| 692 | const projectId = maybeResolveProjectId(source); |
| 693 | return projectId |
| 694 | ? Effect.succeed(projectId) |
| 695 | : Effect.fail( |
| 696 | new BranchStateError({ |
| 697 | reason: "Invalid Neon project source: must be a Project or { projectId }", |
| 698 | }), |
| 699 | ); |
| 700 | }; |
| 701 | |
| 702 | const resolveParentBranchId = (source: ParentBranchSource | undefined, projectId: string) => |
| 703 | Effect.gen(function* () { |
| 704 | if (!source) return undefined as string | undefined; |
| 705 | if ("branchId" in source && typeof source.branchId === "string") { |
| 706 | if ( |
| 707 | "projectId" in source && |
| 708 | typeof source.projectId === "string" && |
| 709 | source.projectId !== projectId |
| 710 | ) { |
| 711 | return yield* new BranchStateError({ |
| 712 | reason: "Parent branch belongs to another project", |
| 713 | }); |
| 714 | } |
| 715 | return source.branchId; |
| 716 | } |
| 717 | if ("name" in source && source.name) { |
| 718 | const matches = yield* findBranchByName(projectId, source.name); |
| 719 | if (matches.length === 0) { |
| 720 | return yield* new BranchStateError({ |
| 721 | reason: `Parent branch "${source.name}" not found in project ${projectId}`, |
| 722 | }); |
| 723 | } |
| 724 | if (matches.length > 1) { |
| 725 | return yield* new BranchStateError({ |
| 726 | reason: `Multiple branches with name "${source.name}" in project ${projectId}`, |
| 727 | }); |
| 728 | } |
| 729 | return matches[0]!.id; |
| 730 | } |
| 731 | return undefined as string | undefined; |
| 732 | }); |
| 733 | |
| 734 | export class BranchStateError extends Data.TaggedError("NeonBranchStateError")<{ |
| 735 | reason: string; |
| 736 | }> {} |
| 737 | |
| 738 | const syncEndpoints = Effect.fn(function* ( |
| 739 | projectId: string, |
| 740 | branchId: string, |
| 741 | desired: BranchEndpointConfig[], |
| 742 | ) { |
| 743 | const { project } = yield* getProject({ project_id: projectId }); |
| 744 | const defaults = project.default_endpoint_settings ?? {}; |
| 745 | const { endpoints } = yield* listProjectBranchEndpoints({ |
| 746 | project_id: projectId, |
| 747 | branch_id: branchId, |
| 748 | }); |
| 749 | const remaining = [...endpoints].sort((a, b) => a.id.localeCompare(b.id)); |
| 750 | for (const config of desired) { |
| 751 | const index = remaining.findIndex((endpoint) => endpoint.type === config.type); |
| 752 | let observed = index < 0 ? undefined : remaining.splice(index, 1)[0]; |
| 753 | const settings = { |
| 754 | autoscaling_limit_min_cu: |
| 755 | config.autoscalingLimitMinCu ?? defaults.autoscaling_limit_min_cu ?? 0.25, |
| 756 | autoscaling_limit_max_cu: |
| 757 | config.autoscalingLimitMaxCu ?? defaults.autoscaling_limit_max_cu ?? 2, |
| 758 | suspend_timeout_seconds: |
| 759 | config.suspendTimeoutSeconds ?? defaults.suspend_timeout_seconds ?? 0, |
| 760 | }; |
| 761 | if (!observed) { |
| 762 | const created = yield* createProjectEndpoint({ |
| 763 | project_id: projectId, |
| 764 | endpoint: { branch_id: branchId, type: config.type, ...settings }, |
| 765 | }).pipe( |
| 766 | Effect.catchTag("Conflict", (error) => |
| 767 | listProjectBranchEndpoints({ |
| 768 | project_id: projectId, |
| 769 | branch_id: branchId, |
| 770 | }).pipe( |
| 771 | Effect.flatMap(({ endpoints }) => { |
| 772 | const matches = endpoints.filter((endpoint) => endpoint.type === "read_write"); |
| 773 | return config.type === "read_write" && matches.length === 1 |
| 774 | ? Effect.succeed({ endpoint: matches[0]!, operations: [] }) |
| 775 | : Effect.fail(error); |
| 776 | }), |
| 777 | ), |
| 778 | ), |
| 779 | ); |
| 780 | yield* waitForOperations(created.operations); |
| 781 | observed = created.endpoint; |
| 782 | } |
| 783 | if ( |
| 784 | observed.autoscaling_limit_min_cu !== settings.autoscaling_limit_min_cu || |
| 785 | observed.autoscaling_limit_max_cu !== settings.autoscaling_limit_max_cu || |
| 786 | observed.suspend_timeout_seconds !== settings.suspend_timeout_seconds |
| 787 | ) { |
| 788 | const updated = yield* updateProjectEndpoint({ |
| 789 | project_id: projectId, |
| 790 | endpoint_id: observed.id, |
| 791 | endpoint: settings, |
| 792 | }); |
| 793 | yield* waitForOperations(updated.operations); |
| 794 | } |
| 795 | } |
| 796 | for (const endpoint of remaining) { |
| 797 | yield* deleteProjectEndpoint({ |
| 798 | project_id: projectId, |
| 799 | endpoint_id: endpoint.id, |
| 800 | }).pipe( |
| 801 | Effect.flatMap(({ operations }) => waitForOperations(operations)), |
| 802 | Effect.catchTag("NotFound", () => Effect.void), |
| 803 | ); |
| 804 | } |
| 805 | }); |
| 806 | |
| 807 | const buildEndpoints = (endpoints: BranchEndpointConfig[] | undefined) => { |
| 808 | const list = endpoints ?? [{ type: "read_write" as const }]; |
| 809 | return list.map((e) => ({ |
| 810 | type: e.type, |
| 811 | autoscaling_limit_min_cu: e.autoscalingLimitMinCu, |
| 812 | autoscaling_limit_max_cu: e.autoscalingLimitMaxCu, |
| 813 | suspend_timeout_seconds: e.suspendTimeoutSeconds, |
| 814 | })); |
| 815 | }; |
| 816 | |
| 817 | const fetchConnection = ( |
| 818 | projectId: string, |
| 819 | branchId: string, |
| 820 | databaseName: string, |
| 821 | roleName: string, |
| 822 | ) => |
| 823 | Effect.gen(function* () { |
| 824 | const direct = yield* getConnectionURI({ |
| 825 | project_id: projectId, |
| 826 | branch_id: branchId, |
| 827 | database_name: databaseName, |
| 828 | role_name: roleName, |
| 829 | pooled: false, |
| 830 | }); |
| 831 | const pooled = yield* getConnectionURI({ |
| 832 | project_id: projectId, |
| 833 | branch_id: branchId, |
| 834 | database_name: databaseName, |
| 835 | role_name: roleName, |
| 836 | pooled: true, |
| 837 | }); |
| 838 | return { uri: direct.uri, pooled: pooled.uri }; |
| 839 | }); |