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

main
mdx 144 lines 3.96 KB
Raw
1 ---
2 title: Branching
3 description: Neon branches are copy-on-write forks of a parent branch — create them per stage or preview, pin them to a point in time, copy schema only, and let them expire on their own.
4 ---
5
6 A `Neon.Branch` is a copy-on-write fork of a parent branch. It shares
7 storage with the parent until it starts diverging, so creating one
8 takes seconds regardless of database size — cheap enough to fork a
9 branch per stage, per pull request, or per experiment.
10
11 ## Create a branch
12
13 ```typescript
14 const project = yield* Neon.Project("my-project");
15 const dev = yield* Neon.Branch("dev-branch", { project });
16 ```
17
18 With no other props, the branch forks from the project's default
19 branch and gets a unique name generated from the app, stage, and
20 logical ID. Pass `name` to control it. The outputs include
21 `connectionUri`, `pooledConnectionUri`, and parsed `origin` /
22 `pooledOrigin` components — see [Connections](/neon/data/connections) for
23 how to use them.
24
25 ## Choose the parent
26
27 `parentBranch` selects which branch to fork from:
28
29 ```typescript
30 const dev = yield* Neon.Branch("dev", { project });
31 const featureBranch = yield* Neon.Branch("feature", {
32 project,
33 parentBranch: dev,
34 });
35 ```
36
37 It accepts another `Branch` resource, a `{ branchId: "br-..." }`, or
38 a `{ name: "dev" }` to look up by name — the deploy fails if the
39 named branch is missing or the name is ambiguous. When omitted, the
40 project's default branch is the parent.
41
42 ## Branch from a point in time
43
44 `parentLsn` forks the parent's data as of a specific Log Sequence
45 Number:
46
47 ```typescript
48 const branch = yield* Neon.Branch("at-lsn", {
49 project,
50 parentLsn: "0/3FA01B0",
51 });
52 ```
53
54 `parentTimestamp` does the same with an ISO-8601 timestamp:
55
56 ```typescript
57 const branch = yield* Neon.Branch("before-incident", {
58 project,
59 parentTimestamp: "2026-06-30T12:00:00Z",
60 });
61 ```
62
63 The fork point is fixed at creation, so changing `parentLsn` or
64 `parentTimestamp` on a subsequent deploy replaces the branch with a
65 fresh fork.
66
67 ## Schema-only branches
68
69 `initSource: "schema-only"` copies the parent's schema without its
70 data — useful when the parent holds data that shouldn't leak into
71 development branches:
72
73 ```typescript
74 const schemaBranch = yield* Neon.Branch("schema-only", {
75 project,
76 initSource: "schema-only",
77 });
78 ```
79
80 The default is `"parent-data"` (schema and data). Like the fork
81 point, `initSource` is decided at creation — changing it replaces
82 the branch.
83
84 ## Expiring preview branches
85
86 `expiresAt` tells Neon to delete the branch itself at an RFC-3339
87 timestamp — a safety net for ephemeral preview branches that might
88 outlive their deploy:
89
90 ```typescript
91 const preview = yield* Neon.Branch("preview", {
92 project,
93 expiresAt: "2026-07-08T00:00:00Z",
94 });
95 ```
96
97 Unlike the fork point, `expiresAt` is mutable: changing or removing
98 it updates the branch in place. The inverse guard is
99 `protected: true`, which marks the branch protected from deletion
100 and mutation.
101
102 ## Compute endpoints
103
104 By default each branch gets one `read_write` compute endpoint —
105 required to connect at all. `endpoints` overrides the default with
106 explicit compute settings:
107
108 ```typescript
109 const branch = yield* Neon.Branch("analytics", {
110 project,
111 endpoints: [
112 {
113 type: "read_write",
114 autoscalingLimitMinCu: 0.25,
115 autoscalingLimitMaxCu: 2,
116 suspendTimeoutSeconds: 300,
117 },
118 { type: "read_only" },
119 ],
120 });
121 ```
122
123 `autoscalingLimitMinCu` / `autoscalingLimitMaxCu` bound the compute
124 size the endpoint scales between, and `suspendTimeoutSeconds`
125 controls how long the endpoint idles before suspending.
126
127 ## Where next
128
129 Guides:
130
131 - [Branch from a shared database](/cloudflare/data/branch-from-shared-database)
132 — fork a preview branch per stage off a long-lived staging
133 project.
134
135 Related:
136
137 - [Connections](/neon/data/connections) — direct vs pooled URIs and
138 feeding `origin` into Hyperdrive.
139 - [Migrations](/neon/data/migrations) — apply SQL migrations on the
140 branch as part of the deploy.
141
142 Reference:
143
144 - [Branch API reference](/providers/neon/branch)