clover's git

the-knife

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)