@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 99 lines 3.27 KB
Raw
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.run/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 - [Roles](/neon/data/roles) — connect as your own Postgres role instead
93 of the owner.
94
95 Reference:
96
97 - [Project API reference](/providers/neon/project)
98 - [Branch API reference](/providers/neon/branch)
99 - [Role API reference](/providers/neon/role)