clover's git

the-knife

1	---
2	title: Connections
3	description: Every Neon project and branch exposes direct and pooled connection URIs plus pre-parsed origin outputs — feed the direct origin to Hyperdrive and the pooled one to everything else.
4	---
5
6	Every Neon project and branch exposes its connection details as
7	outputs: raw URIs and pre-parsed origins, each in a direct and a
8	pooled flavor. Which one to use depends on who is connecting.
9
10	## The four connection outputs
11
12	Both `Neon.Project` and `Neon.Branch` expose the same four
13	attributes:
14
15	```typescript
16	import * as Neon from "alchemy/Neon";
17
18	const project = yield* Neon.Project("app-db");
19	const branch = yield* Neon.Branch("preview", { project });
20
21	branch.connectionUri; // direct Postgres URI
22	branch.pooledConnectionUri; // pooled URI (Neon's pgbouncer)
23	branch.origin; // parsed direct connection components
24	branch.pooledOrigin; // parsed pooled connection components
25	```
26
27	On a project, they target the default branch's primary database; on
28	a branch, the branch's own primary database.
29
30	The direct URI connects straight to the branch's compute endpoint.
31	The pooled URI routes through Neon's pgbouncer-based pooler, which
32	lets many short-lived clients share a small number of Postgres
33	connections.
34
35	## The origin shape
36
37	`origin` and `pooledOrigin` are the same connections parsed into
38	the structured shape Postgres consumers like `Cloudflare.Hyperdrive`
39	accept:
40
41	```typescript
42	type PostgresOrigin = {
43	scheme: "postgres" | "postgresql" | "mysql";
44	host: string;
45	port: number;
46	database: string;
47	user: string;
48	password: Redacted.Redacted<string>;
49	};
50	```
51
52	The `password` is a `Redacted` value, so it never prints in logs or
53	plan output. (`"mysql"` is in the union because the same shape is
54	shared with MySQL providers like PlanetScale — Neon origins are
55	always `postgres`/`postgresql`.)
56
57	## Direct behind Hyperdrive, pooled for everyone else
58
59	Hyperdrive is itself a connection pooler, so point it at the
60	**direct** origin — stacking it on top of Neon's pooler means two
61	poolers fighting over the same connections:
62
63	```typescript
64	const hyperdrive = yield* Cloudflare.Hyperdrive.Connection("app-hyperdrive", {
65	origin: branch.origin, // direct — Hyperdrive does the pooling
66	dev: branch.pooledOrigin, // local dev bypasses Hyperdrive
67	});
68	```
69
70	The `dev` override matters because `bun alchemy dev` doesn't create
71	a Hyperdrive config at all — the local Worker connects to the
72	database directly. With Hyperdrive out of the path, nothing pools
73	those connections, so `pooledOrigin` sends local dev through Neon's
74	pooler instead.
75
76	The same rule applies to anything else that connects without
77	Hyperdrive in front — CI jobs, containers, `psql` on your laptop.
78	Hand those clients the pooled URI:
79
80	```typescript
81	return { databaseUrl: branch.pooledConnectionUri };
82	```
83
84	## Where next
85
86	Guides:
87
88	- [Hyperdrive](/cloudflare/data/hyperdrive) — the full walkthrough:
89	provision Neon, front it with Hyperdrive, bind it into a Worker.
90	- [Branching](/neon/data/branching) — copy-on-write branches, each with
91	its own connection outputs.
92
93	Reference:
94
95	- [Project API reference](/providers/neon/project)
96	- [Branch API reference](/providers/neon/branch)