@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, 04:45 UTC

main
mdx 154 lines 4.78 KB
Raw
1 ---
2 title: Drizzle Postgres on Hetzner
3 description: Run a Drizzle API on a Hetzner Server with external Neon Postgres and reviewed SQL migrations.
4 ---
5
6 Alchemy's Hetzner provider has no managed Postgres resource; this guide runs the application on Hetzner and stores its data in **Neon Postgres**. Start with [Hetzner setup](/hetzner/setup), the [Service tutorial](/hetzner/tutorial/part-2), [Neon setup](/neon/setup), and a `src/schema.ts` exporting `Users` from the [Postgres client guide](/sql/drizzle/postgres).
7
8 ## Install the database dependencies
9
10 ```sh
11 pnpm add @alchemy.run/drizzle drizzle-orm@1.0.0-rc.5 @effect/sql-pg
12 pnpm add -D drizzle-kit@1.0.0-rc.5
13 ```
14
15 The Drizzle versions match the repository's Effect integration.
16
17 ## Configure migrations
18
19 ```typescript
20 // drizzle.config.ts
21 import { defineConfig } from "drizzle-kit";
22
23 export default defineConfig({
24 dialect: "postgresql",
25 schema: "./src/schema.ts",
26 out: "./drizzle",
27 dbCredentials: { url: process.env.DATABASE_URL! },
28 });
29 ```
30
31 The migration runner uses Neon's direct connection URL; the Service will use its pooled URL.
32
33 ## Generate after changing the schema
34
35 ```sh
36 pnpm exec drizzle-kit generate
37 ```
38
39 Review the generated SQL and snapshots, including any rename decisions, before applying them.
40
41 ## Commit the migration
42
43 ```sh
44 git add src/schema.ts drizzle.config.ts drizzle
45 git diff --cached
46 ```
47
48 ```sh
49 git commit -m "Add users migration"
50 ```
51
52 Commit the schema, SQL, and snapshots together; do not generate migration history during deployment.
53
54 ## Declare the external database
55
56 ```typescript
57 // src/db.ts
58 import * as Neon from "@alchemy.run/neon";
59
60 export const Db = Neon.Project("Db", {
61 region: "aws-eu-central-1",
62 });
63 ```
64
65 The project's default branch hosts the database; see [Neon connections](/neon/data/connections) for its direct and pooled outputs.
66
67 ## Register Neon alongside Hetzner
68
69 ```diff lang="typescript"
70 // alchemy.run.ts
71 +import * as Neon from "@alchemy.run/neon";
72 +import * as Layer from "effect/Layer";
73
74 - providers: Hetzner.providers(),
75 + providers: Layer.mergeAll(Hetzner.providers(), Neon.providers()),
76 ```
77
78 Keep the tutorial's Server, `yield* Api`, and state backend unchanged.
79
80 ## Pass the database URL to the Service
81
82 Replace the Service's props object in `src/api.ts` with this Effect, importing `Db` from `./db.ts`:
83
84 ```typescript
85 Effect.gen(function* () {
86 const server = yield* Box;
87 const database = yield* Db;
88 return {
89 server,
90 main: import.meta.url,
91 port: 3000,
92 env: { DATABASE_URL: database.pooledConnectionUri },
93 };
94 }),
95 ```
96
97 The URL is server-side configuration, not browser configuration; protect the state backend and never expose it as a public Stack output.
98
99 ## Provision before the first migration
100
101 ```sh
102 pnpm alchemy deploy
103 ```
104
105 Keep the tutorial's `/health` route independent of database tables so systemd deployment readiness does not depend on migrations. Allow the Server outbound access to Neon's Postgres endpoint over TLS.
106
107 ## Apply the committed SQL
108
109 ```sh
110 pnpm exec drizzle-kit migrate
111 ```
112
113 Supply the Neon project's `connectionUri` as secret `DATABASE_URL` in the migration runner, retaining its TLS parameters. This guide keeps Drizzle as the migration owner and does not set Neon's optional `migrations` prop.
114
115 ## Read the URL at runtime
116
117 ```diff lang="typescript"
118 // src/api.ts
119 +import * as Drizzle from "@alchemy.run/drizzle/Postgres";
120 +import * as Config from "effect/Config";
121
122 Effect.gen(function* () {
123 + const db = yield* Drizzle.Postgres(Config.Redacted("DATABASE_URL"));
124 return {
125 ```
126
127 Add this to the Service's runtime Effect, not its props Effect; the URL and connection are resolved lazily when queried.
128
129 ## Query after the health check
130
131 ```diff lang="typescript"
132 +import { Users } from "./schema.ts";
133
134 if (url.pathname === "/health") {
135 return yield* HttpServerResponse.json({ ok: true });
136 }
137 -return HttpServerResponse.text("Hello from Hetzner!");
138 +const users = yield* db.select().from(Users).pipe(Effect.orDie);
139 +return yield* HttpServerResponse.json({ users });
140 ```
141
142 The existing request handler supplies the query scope, and `/health` remains independent of the database.
143
144 ## Deploy the application
145
146 ```sh
147 pnpm alchemy deploy
148 ```
149
150 For later changes, generate, review, and commit the schema, SQL, and snapshots before applying migrations and deploying compatible application code. `alchemy deploy` updates the systemd Service; it does not replace the migration command used here.
151
152 ## Continue
153
154 See the [Neon connection guide](/neon/data/connections), [portable Postgres queries](/sql/drizzle/postgres), and [migration workflow](/sql/drizzle/migrations). The [hetzner-website-vite example](https://github.com/alchemy-run/alchemy/tree/main/examples/hetzner-website-vite) supplies the Neon-to-Service environment wiring; this guide uses committed migrations instead of that example's request-time table creation.