1import * as Effect from "effect/Effect";
2import * as FileSystem from "effect/FileSystem";
3import * as Path from "effect/Path";
4import type { PlatformError } from "effect/PlatformError";
5import { ChildProcess } from "effect/process";
6import * as crypto from "node:crypto";
7import * as Artifacts from "../Artifacts.ts";
8import { isResolved } from "../Diff.ts";
9import * as Provider from "../Provider.ts";
10import { Resource } from "../Resource.ts";
11import { exec } from "../Util/exec.ts";
12import { isNonInteractive } from "../Util/interactive.ts";
13import type { Providers } from "./Providers.ts";
14
15export type Dialect = "postgres" | "mysql" | "sqlite";
16
17type DrizzleSnapshot = {
18 id?: string;
19 prevIds?: string[];
20};
21
22type DrizzleKitApi = {
23 generateDrizzleJson?: (
24 imports: Record<string, unknown>,
25 prevId?: string,
26 schemaFilters?: string[],
27 ) => Promise<unknown>;
28 generateMigration?: (prev: unknown, cur: unknown) => Promise<string[]>;
29};
30
31export type SchemaProps = {
32 /**
33 * Path to the schema module, relative to the current working directory.
34 * The module is loaded via dynamic `import()` so drizzle-kit can introspect
35 * the table definitions, then diffed against the latest snapshot under
36 * `out` to detect changes.
37 *
38 * @example "./src/schema.ts"
39 */
40 schema: string;
41 /**
42 * Output directory for generated migrations. Each migration is written as
43 * `{out}/{timestamp}_migration/{migration.sql, snapshot.json}`. Pass this
44 * through as a database resource's `migrations` prop (`Neon.Branch`,
45 * `Fly.Postgres`, `Cloudflare.D1.Database`, …) to apply pending
46 * migrations on deploy.
47 *
48 * @default "./migrations"
49 */
50 out?: string;
51 /**
52 * SQL dialect to generate migrations for. Selects which `drizzle-kit/api-*`
53 * module is loaded.
54 *
55 * @default "postgres"
56 */
57 dialect?: Dialect;
58};
59
60export type Schema = Resource<
61 "Drizzle.Schema",
62 SchemaProps,
63 {
64 /** Path to the migrations directory, relative to the current working directory. */
65 out: string;
66 /**
67 * sha256 of the latest snapshot.json. Stable across deploys when the
68 * schema is unchanged; bumps trigger an update which regenerates pending
69 * migration SQL. Downstream `migrationsDir` consumers read this to
70 * detect drift and reapply.
71 */
72 snapshotHash: string;
73 /** Names of all migration directories under `out`, in order. */
74 migrations: string[];
75 },
76 never,
77 Providers
78>;
79
80/**
81 * A Drizzle schema managed as an Alchemy resource.
82 *
83 * Wraps drizzle-kit's programmatic API (`generateDrizzleJson` /
84 * `generateMigration`) so migration SQL is regenerated as part of `alchemy
85 * deploy` whenever the source schema changes. The output directory is
86 * intended to be passed straight to a database resource's `migrations`
87 * prop, giving you a single deploy-driven flow:
88 *
89 * ```typescript
90 * const schema = yield* Drizzle.Schema("app-schema", {
91 * schema: "./src/schema.ts",
92 * });
93 *
94 * const branch = yield* Neon.Branch("app-branch", {
95 * project,
96 * migrations: schema,
97 * });
98 *
99 * const db = yield* Fly.Postgres("Db", {
100 * region: "iad",
101 * migrations: schema,
102 * });
103 * ```
104 *
105 * `Drizzle.Schema` runs first (because the database resource depends
106 * on its `out` output), regenerates pending migration files, and the
107 * database resource then applies them.
108 *
109 * The resource is delete-safe: removing it from the stack does **not** wipe
110 * the migrations directory, since migration files are typically checked in
111 * and shared with other environments.
112 *
113 * @resource
114 */
115export const Schema = Resource<Schema>("Drizzle.Schema");
116
117const dialectModule = (dialect: Dialect): string => {
118 switch (dialect) {
119 case "postgres":
120 return "drizzle-kit/api-postgres";
121 case "mysql":
122 return "drizzle-kit/api-mysql";
123 case "sqlite":
124 return "drizzle-kit/api-sqlite";
125 }
126};
127
128const sha = (s: string) => crypto.createHash("sha256").update(s).digest("hex");
129
130const tsStamp = () =>
131 new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
132
133export const SchemaProvider = () =>
134 Provider.effect(
135 Schema,
136 Effect.gen(function* () {
137 const fs = yield* FileSystem.FileSystem;
138 const path = yield* Path.Path;
139
140 const resolveOut = (p: SchemaProps) =>
141 path.resolve(process.cwd(), p.out ?? "./migrations");
142
143 // The `out` attribute is exposed as a path relative to the current
144 // working directory so that persisted state stays portable across
145 // machines/checkouts. Internal filesystem ops always use the absolute
146 // `resolveOut` form.
147 const relativeOut = (abs: string) => path.relative(process.cwd(), abs);
148
149 const resolveSchema = (p: SchemaProps) =>
150 path.resolve(process.cwd(), p.schema);
151
152 const loadSchemaModule = (p: SchemaProps) =>
153 Effect.gen(function* () {
154 const schemaPath = resolveSchema(p);
155 return yield* Effect.tryPromise({
156 try: () =>
157 import(/* @vite-ignore */ schemaPath) as Promise<
158 Record<string, unknown>
159 >,
160 catch: (cause) =>
161 new Error(`Failed to import schema at ${p.schema}: ${cause}`),
162 });
163 });
164
165 const loadKit = (dialect: Dialect) =>
166 Effect.tryPromise({
167 try: () =>
168 import(
169 /* @vite-ignore */ dialectModule(dialect)
170 ) as Promise<DrizzleKitApi>,
171 catch: (cause) =>
172 new Error(
173 `Failed to load drizzle-kit/${dialect} (is drizzle-kit installed?): ${cause}`,
174 ),
175 });
176
177 const drizzleKitBin = (dialect: Dialect) =>
178 Effect.gen(function* () {
179 const apiUrl = yield* Effect.try({
180 try: () => import.meta.resolve(dialectModule(dialect)),
181 catch: (cause) =>
182 new Error(`Failed to resolve drizzle-kit/${dialect}: ${cause}`),
183 });
184 const apiFileUrl = yield* Effect.try({
185 try: () => new URL(apiUrl),
186 catch: (cause) =>
187 new Error(`Failed to parse drizzle-kit/${dialect} URL: ${cause}`),
188 });
189 const apiPath = yield* path.fromFileUrl(apiFileUrl);
190 return path.join(path.dirname(apiPath), "bin.cjs");
191 });
192
193 const runDrizzleGenerate = (props: SchemaProps, out: string) =>
194 Effect.gen(function* () {
195 const dialect = props.dialect ?? "postgres";
196 const bin = yield* drizzleKitBin(dialect);
197 const schemaPath = resolveSchema(props);
198 const nodeExecPath = yield* Effect.sync(() => process.execPath);
199 const nodeModulesPath = path.join(process.cwd(), "node_modules");
200
201 // drizzle-kit globs the --schema/--out values; Windows backslashes
202 // are treated as glob escapes and match nothing, so pass forward
203 // slashes.
204 const args = [
205 bin,
206 "generate",
207 "--dialect",
208 dialect === "postgres" ? "postgresql" : dialect,
209 "--schema",
210 schemaPath.replaceAll("\\", "/"),
211 "--out",
212 out.replaceAll("\\", "/"),
213 ];
214
215 const commandOptions = {
216 cwd: process.cwd(),
217 env: { NODE_PATH: nodeModulesPath },
218 extendEnv: true,
219 };
220
221 // Hand the terminal to drizzle-kit only when this process may
222 // prompt at all — the same detection (TTY, CI, `--no-input`,
223 // `ALCHEMY_NO_TUI`, agent env) every other spawned command uses.
224 if (!isNonInteractive() && process.stderr.isTTY) {
225 const handle = yield* ChildProcess.make(nodeExecPath, args, {
226 ...commandOptions,
227 stdin: "inherit",
228 stdout: "inherit",
229 stderr: "inherit",
230 }).pipe(
231 Effect.mapError(
232 (cause) =>
233 new Error(`drizzle-kit generate failed: ${String(cause)}`),
234 ),
235 );
236 const exitCode = yield* handle.exitCode;
237 if (exitCode !== 0) {
238 return yield* Effect.fail(
239 new Error(`drizzle-kit generate failed with exit ${exitCode}`),
240 );
241 }
242 return;
243 }
244
245 const result = yield* exec(
246 ChildProcess.make(nodeExecPath, args, commandOptions),
247 ).pipe(
248 Effect.mapError(
249 (cause) =>
250 new Error(`drizzle-kit generate failed: ${String(cause)}`),
251 ),
252 );
253 if (result.exitCode === 0) return;
254
255 // Since drizzle-kit 1.0.0-rc.4 the non-interactive CLI refuses
256 // ambiguous decisions (rename-vs-create, data-loss confirmation)
257 // with a `missing_hints` report on exit 2. These are deliberate
258 // safety prompts — the generated SQL is applied to the real
259 // database later in the same deploy — so we never answer them
260 // automatically. Ask the user to decide.
261 if (result.exitCode === 2) {
262 return yield* Effect.fail(
263 new Error(
264 [
265 `drizzle-kit needs a decision for ${props.schema} that cannot be made non-interactively (rename vs create, or a change that loses data):`,
266 "",
267 result.stdout.trim(),
268 "",
269 "To resolve, generate the migration yourself and commit it:",
270 ` npx drizzle-kit generate --dialect ${dialect === "postgres" ? "postgresql" : dialect} --schema ${props.schema} --out ${props.out ?? "./migrations"}`,
271 "then re-run the deploy (the schema resource will see no drift and apply the committed migration).",
272 "Alternatively, run the deploy in a terminal to answer drizzle-kit's prompts interactively.",
273 ].join("\n"),
274 ),
275 );
276 }
277
278 return yield* Effect.fail(
279 new Error(
280 `drizzle-kit generate failed: ${result.stdout}\n${result.stderr}`,
281 ),
282 );
283 });
284
285 // List `<ts>_*` migration directories under `out`, sorted by numeric
286 // prefix. Returns an empty array if `out` doesn't exist.
287 const listMigrationDirs = (out: string) =>
288 Effect.gen(function* () {
289 const exists = yield* fs.exists(out);
290 if (!exists) return [] as string[];
291 const entries = yield* fs.readDirectory(out);
292 return entries.filter((name) => /^\d+_/.test(name)).sort();
293 });
294
295 // The latest snapshot is the head of the `prevIds` chain — the one no
296 // other snapshot points back to. Directory-name order alone is not
297 // enough: two migrations generated within the same second share the
298 // timestamp prefix, and the random name suffix then decides the sort.
299 const readLatestSnapshot = (out: string) =>
300 Effect.gen(function* () {
301 const dirs = yield* listMigrationDirs(out);
302 const entries: Array<{ snapshot: DrizzleSnapshot; hash: string }> =
303 [];
304 for (const dir of dirs) {
305 const snapshotPath = path.join(out, dir, "snapshot.json");
306 const exists = yield* fs.exists(snapshotPath);
307 if (!exists) continue;
308 const text = yield* fs.readFileString(snapshotPath);
309 entries.push({
310 snapshot: JSON.parse(text) as DrizzleSnapshot,
311 hash: sha(text),
312 });
313 }
314 if (entries.length === 0) return undefined;
315 const referenced = new Set(
316 entries.flatMap((entry) => entry.snapshot.prevIds ?? []),
317 );
318 const head = entries.find(
319 (entry) =>
320 entry.snapshot.id !== undefined &&
321 !referenced.has(entry.snapshot.id),
322 );
323 // Fall back to name order for snapshots without id/prevIds chains.
324 return head ?? entries[entries.length - 1];
325 });
326
327 const detectDriftWithCli = (props: SchemaProps) =>
328 Effect.gen(function* () {
329 const out = resolveOut(props);
330 const tmpOut = yield* fs.makeTempDirectory({
331 prefix: "alchemy-drizzle-generate-",
332 });
333
334 return yield* Effect.gen(function* () {
335 const outExists = yield* fs.exists(out);
336 if (outExists) yield* copyDirectory(out, tmpOut);
337
338 const before = yield* listMigrationDirs(tmpOut);
339 yield* runDrizzleGenerate(props, tmpOut);
340
341 const after = yield* listMigrationDirs(tmpOut);
342 const latest = yield* readLatestSnapshot(tmpOut);
343 const changed = after.some((dir) => !before.includes(dir));
344
345 const prevEntry = outExists
346 ? yield* readLatestSnapshot(out)
347 : undefined;
348
349 return {
350 mode: "cli" as const,
351 out,
352 cur: latest?.snapshot,
353 prevEntry,
354 changed,
355 };
356 }).pipe(
357 Effect.ensuring(
358 fs.remove(tmpOut, { recursive: true }).pipe(Effect.ignore),
359 ),
360 );
361 });
362
363 /**
364 * Run drizzle-kit's diff against the latest stored snapshot and
365 * return whether any SQL statements would be emitted. Used by both
366 * `diff` (to decide whether the resource actually needs an update)
367 * and `regenerate` (to decide whether to write a new migration dir).
368 */
369 const detectDrift = (props: SchemaProps) =>
370 Effect.gen(function* () {
371 const out = resolveOut(props);
372 const dialect = props.dialect ?? "postgres";
373
374 const kit = yield* loadKit(dialect);
375 if (!kit.generateDrizzleJson || !kit.generateMigration) {
376 return yield* detectDriftWithCli(props);
377 }
378
379 const generateDrizzleJson = kit.generateDrizzleJson;
380 const generateMigration = kit.generateMigration;
381
382 const schemaModule = yield* loadSchemaModule(props);
383 const prevEntry = yield* readLatestSnapshot(out);
384 const cur = yield* Effect.tryPromise({
385 try: () =>
386 generateDrizzleJson(schemaModule, prevEntry?.snapshot.id),
387 catch: (cause) =>
388 new Error(`drizzle-kit generateDrizzleJson failed: ${cause}`),
389 });
390
391 // For the initial migration, drizzle-kit needs an *empty* snapshot
392 // produced by `generateDrizzleJson({})`, not a bare `{}` — the
393 // snapshot has internal fields (`ddl`, etc.) that the differ reads.
394 const prev =
395 prevEntry?.snapshot ??
396 (yield* Effect.tryPromise({
397 try: () => generateDrizzleJson({}),
398 catch: (cause) =>
399 new Error(
400 `drizzle-kit generateDrizzleJson (empty baseline) failed: ${cause}`,
401 ),
402 }));
403 const sqlStatements = yield* Effect.tryPromise({
404 try: () => generateMigration(prev, cur),
405 catch: (cause) =>
406 new Error(`drizzle-kit generateMigration failed: ${cause}`),
407 });
408 return {
409 mode: "programmatic" as const,
410 out,
411 cur,
412 prevEntry,
413 sqlStatements,
414 };
415 }).pipe(Artifacts.cached("detectDrift"));
416
417 /**
418 * Generate a new migration directory if the schema has drifted from
419 * the latest snapshot. Returns the new state regardless.
420 */
421 const regenerate = (props: SchemaProps) =>
422 Effect.gen(function* () {
423 const drift = yield* detectDrift(props);
424
425 if (drift.mode === "cli") {
426 if (drift.changed) {
427 yield* runDrizzleGenerate(props, drift.out);
428 }
429
430 const migrations = yield* listMigrationDirs(drift.out);
431 const latest = yield* readLatestSnapshot(drift.out);
432 const snapshotHash = latest?.hash ?? sha(JSON.stringify(drift.cur));
433 return {
434 out: relativeOut(drift.out),
435 snapshotHash,
436 migrations,
437 };
438 }
439
440 const { out, cur, sqlStatements } = drift;
441
442 if (sqlStatements.length > 0) {
443 yield* fs.makeDirectory(out, { recursive: true });
444 const dirName = `${tsStamp()}_migration`;
445 const dirPath = path.join(out, dirName);
446 yield* fs.makeDirectory(dirPath, { recursive: true });
447 const sql =
448 sqlStatements.join("\n--> statement-breakpoint\n") + "\n";
449 yield* fs.writeFileString(path.join(dirPath, "migration.sql"), sql);
450 yield* fs.writeFileString(
451 path.join(dirPath, "snapshot.json"),
452 JSON.stringify(cur, null, 2),
453 );
454 }
455
456 const migrations = yield* listMigrationDirs(out);
457 const latest = yield* readLatestSnapshot(out);
458 const snapshotHash = latest?.hash ?? sha(JSON.stringify(cur));
459 return {
460 out: relativeOut(out),
461 snapshotHash,
462 migrations,
463 };
464 });
465
466 return {
467 // Non-listable: a Drizzle.Schema is a local build artifact (generated
468 // migration SQL under `out`, a path supplied entirely by props with no
469 // account/store to enumerate). There is no remote enumeration API, so
470 // there is nothing to discover out-of-band.
471 list: () => Effect.succeed([]),
472 diff: Effect.fn(function* ({ news, output }) {
473 if (!isResolved(news)) return undefined;
474 if (!output) return undefined;
475 // Only flag an update when drizzle-kit would emit new SQL —
476 // otherwise downstream resources (e.g. Neon.Branch) would see
477 // `schema.out` as an unresolved Output during plan and cascade
478 // into spurious updates of their own.
479 const drift = yield* detectDrift(news);
480 const changed =
481 drift.mode === "cli"
482 ? drift.changed
483 : drift.sqlStatements.length > 0;
484 // Originally `output.out` was an absolute path, which is not portable.
485 // So, we trigger an update to migrate existing resources to the
486 // canonical (cwd-relative) form. This is safe because `regenerate`
487 // is idempotent. Compare against the canonical form rather than
488 // testing `isAbsolute`: on Windows a cross-drive `out` can never be
489 // relativized, so its canonical form IS absolute and an isAbsolute
490 // check would flag an update on every deploy.
491 return changed || output.out !== relativeOut(resolveOut(news))
492 ? { action: "update" }
493 : undefined;
494 }),
495 read: Effect.fn(function* ({ olds, output }) {
496 if (!output) return undefined;
497 const out = resolveOut(olds ?? ({} as SchemaProps));
498 const exists = yield* fs.exists(out);
499 if (!exists) return undefined;
500 const latest = yield* readLatestSnapshot(out);
501 const migrations = yield* listMigrationDirs(out);
502 return {
503 out: relativeOut(out),
504 snapshotHash: latest?.hash ?? output.snapshotHash,
505 migrations,
506 };
507 }),
508 reconcile: Effect.fn(function* ({ news, output, session }) {
509 yield* session.note(
510 `${output ? "Regenerating" : "Generating"} drizzle migrations for ${news.schema}`,
511 );
512 return yield* regenerate(news);
513 }),
514 delete: Effect.fn(function* () {
515 // Migrations are typically checked in; do not delete on resource
516 // teardown.
517 }),
518 };
519 }),
520 );
521
522const copyDirectory = (
523 from: string,
524 to: string,
525): Effect.Effect<void, PlatformError, Path.Path | FileSystem.FileSystem> =>
526 Effect.gen(function* () {
527 const path = yield* Path.Path;
528 const fs = yield* FileSystem.FileSystem;
529
530 yield* fs.makeDirectory(to, { recursive: true });
531 const entries = yield* fs.readDirectory(from);
532
533 for (const entry of entries) {
534 const source = path.join(from, entry);
535 const target = path.join(to, entry);
536 const stat = yield* fs.stat(source);
537 if (stat.type === "Directory") {
538 yield* copyDirectory(source, target);
539 } else {
540 const contents = yield* fs.readFile(source);
541 yield* fs.writeFile(target, contents);
542 }
543 }
544 });