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

main
mdx 116 lines 3.83 KB
Raw
1 ---
2 title: Migrations
3 description: Apply SQL migrations and seed data to Neon projects and branches as part of every deploy — ordered, hashed, and tracked in Alchemy's __alchemy_migrations table.
4 ---
5
6 Both `Neon.Project` and `Neon.Branch` accept a `migrations` prop — a
7 folder of `.sql` files (or a [`Drizzle.Schema`](/sql/drizzle/migrations)
8 resource) applied in order as part of every deploy. On a project,
9 migrations run against the default branch's primary database; on a
10 branch, they run against the branch itself:
11
12 ```typescript
13 const project = yield* Neon.Project("my-project", {
14 migrations: "./migrations",
15 });
16 ```
17
18 Because branches are copy-on-write forks, a branch created from a
19 migrated parent already contains the parent's schema — and its
20 tracking table. Point the branch at the same `migrations` directory and only
21 migrations added after the fork are applied:
22
23 ```typescript
24 const featureBranch = yield* Neon.Branch("feature", {
25 project,
26 migrations: "./migrations",
27 });
28 ```
29
30 ## Ordering and hashing
31
32 Files are discovered recursively under the migrations directory and sorted by
33 their numeric prefix (`0001_init.sql`, `0002_users.sql`, …), falling
34 back to name order for files without one. Each file's contents are
35 SHA-256 hashed and the hashes are persisted in the resource's state
36 (`migrationsHashes`), so adding a migration file — or editing an
37 existing one — is what marks the resource for an update on the next
38 deploy. When nothing changed, the migration step is skipped
39 entirely.
40
41 ## The tracking table
42
43 Applied migrations are recorded in Alchemy's `__alchemy_migrations`
44 table (created automatically), one row per file:
45
46 ```sql
47 CREATE TABLE IF NOT EXISTS "__alchemy_migrations" (
48 id SERIAL PRIMARY KEY,
49 hash text NOT NULL,
50 created_at bigint,
51 name text,
52 applied_at timestamp with time zone DEFAULT now()
53 );
54 ```
55
56 A database previously migrated with drizzle-kit or Prisma is
57 [adopted automatically](/sql/effect-sql/migrations#adopting-an-existing-database):
58 its old tracking table's history is copied in once and the old table
59 is frozen. Projects deployed by older Alchemy versions (which used a
60 `neon_migrations` table) are upgraded in place.
61
62 On each deploy, files whose names already appear in the table are
63 skipped, and their content hashes must still match. Use
64 `migrations: { dir, table }` to put the bookkeeping in
65 a differently-named table:
66
67 ```typescript
68 const project = yield* Neon.Project("my-project", {
69 migrations: { dir: "./migrations", table: "my_migrations" },
70 });
71 ```
72
73 ## Transactional apply
74
75 Each pending migration runs inside a transaction together with its
76 bookkeeping `INSERT` into the tracking table, so partial application
77 is impossible: a failing statement rolls the whole file back and
78 fails the deploy, while migrations that already committed stay
79 applied. Fix the file and re-deploy — the run resumes from the
80 failed migration.
81
82 ## Seed data with importFiles
83
84 `importFiles` lists additional `.sql` files to apply after
85 migrations. Paths are resolved relative to the working directory:
86
87 ```typescript
88 const project = yield* Neon.Project("my-project", {
89 migrations: "./migrations",
90 importFiles: ["./seed/users.sql"],
91 });
92 ```
93
94 Unlike migrations, import files are not recorded in the tracking
95 table. Each file is content-hashed and re-applied whenever its
96 contents change, so write them to be safe to run more than once
97 (`INSERT ... ON CONFLICT DO NOTHING`, `CREATE OR REPLACE`, and the
98 like). Files whose hashes match the previous deploy are skipped.
99
100 ## Where next
101
102 Guides:
103
104 - [Add Drizzle ORM](/cloudflare/data/drizzle) — typed schemas and
105 generated migrations.
106
107 Related:
108
109 - [Neon overview](/neon) — projects, branches, and composing with
110 your cloud.
111 - [Setup](/neon/setup) — credentials and provider registration.
112
113 Reference:
114
115 - [Project API reference](/providers/neon/project)
116 - [Branch API reference](/providers/neon/branch)