Migration files belong in Git alongside your schema. Generate and review them when the schema changes, commit them, then deploy.
Generate migrations when the schema changes
pnpm exec drizzle-kit generate Answer any rename prompts and review the generated SQL before applying it.
generate writes migration files; migrate applies them to a database.
Commit the schema and migrations
git add src/schema.ts drizzle
git commit -m "Add schema migration" Include both the SQL and snapshots:
drizzle/
└── 20260919000000_create_users/
├── migration.sql
└── snapshot.json Deploy the committed migrations
Point the database resource at the checked-in directory:
const db = yield* Cloudflare.D1.Database("app-db", {
migrations: "./drizzle",
}); pnpm alchemy deploy This resource applies pending SQL from ./drizzle. CI should deploy the
committed files, not generate a new migration history.
For optional schema-generation automation, see the
Drizzle.Schema reference. The workflow above
keeps generation and review separate from deployment.
Durable Object migrations
Capture SQL during construction; apply it when each object activates:
Cloudflare.SqlMigrations("./drizzle") → read files into the Worker bundle
Drizzle.DurableObject({ migrations, ... }) → migrate this object's SQLite database Deployment does not eagerly migrate every object in the namespace.
Generate and commit the SQL
// drizzle.config.ts
import { defineConfig } from "drizzle-kit";
export default defineConfig({
dialect: "sqlite",
schema: "./src/schema.ts",
out: "./drizzle",
}); Define a table and its query relations:
// src/schema.ts
import { defineRelations } from "drizzle-orm";
import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
export const users = sqliteTable("users", {
id: integer("id").primaryKey({ autoIncrement: true }),
name: text("name").notNull(),
});
export const relations = defineRelations({ users }); Generate locally, review the SQL, and commit the schema and migrations together:
pnpm exec drizzle-kit generate
git add src/schema.ts drizzle
git commit -m "Create users table" CI uses these committed files when deploying.
SqlMigrations reads existing files. It does not run drizzle-kit or wait for Drizzle.Schema.
Load the directory in the outer Effect
// src/Users.ts
import * as Cloudflare from "@alchemy.run/cloudflare";
import * as Drizzle from "@alchemy.run/drizzle/Cloudflare";
import * as Effect from "effect/Effect";
import { relations, users } from "./schema.ts";
export class Users extends Cloudflare.DurableObject<Users>()(
"Users",
Effect.gen(function* () {
// Construction: capture SQL without importing .sql or migrations.js.
const migrations = yield* Cloudflare.SqlMigrations("./drizzle");
return Effect.gen(function* () {
// Activation: apply pending SQL before exposing methods.
const db = yield* Drizzle.DurableObject({ migrations, relations });
return {
addUser: (name: string) => db.insert(users).values({ name }).returning(),
listUsers: () => db.query.users.findMany(),
};
});
}),
) {} Paths are relative to the Alchemy command's working directory, not Users.ts:
cd my-app # Contains ./drizzle.
pnpm alchemy dev After SQL edits, restart alchemy dev or redeploy. SQL directories are not watched.
Choose a history table
// Default: __alchemy_migrations
const migrations = yield* Cloudflare.SqlMigrations("./drizzle"); // Custom table
const migrations = yield* Cloudflare.SqlMigrations({
dir: "./drizzle",
table: "app_migrations",
}); Apply migrations before activation
Each pending file and its history row commit in one native SQLite transaction:
0001_create_users → SQL + history row commit
0002_add_email → SQL fails; this file rolls back; activation fails
next activation → skip 0001; retry 0002 Keep applied files unchanged. Migration failures are initialization defects; the object serves no requests until activation succeeds. Query errors remain typed (EffectDrizzleQueryError; transactions can also fail with SqlError).
Without Drizzle, use the same engine in the inner Effect:
yield* migrations.apply().pipe(Effect.orDie); See the raw SQL example for the complete object.
Existing Drizzle migrations
Generated migrations.js inputs still work with Drizzle's migrator. To switch to Alchemy's engine, replace the import with a construction-time capture:
-import migrations from "../drizzle/migrations.js";
Effect.gen(function* () {
+ const migrations = yield* Cloudflare.SqlMigrations("./drizzle");
return Effect.gen(function* () {
const db = yield* Drizzle.DurableObject({ migrations, relations }); __drizzle_migrations → copy matching history → __alchemy_migrations
leave old table frozen; apply only pending files :::caution[One-way adoption]
Keep every historical SQL file and stop using Drizzle's migrator after adoption. Missing matches fail with MigrationHistoryConflictError; changing migrationsTable alone does not switch engines or convert history.
:::
For the legacy meta/_journal.json layout, upgrade before planning:
pnpm exec drizzle-kit up
# Review the upgraded SQL and snapshots.
git add drizzle
git commit -m "Upgrade Drizzle migration layout" See the complete Worker example for named-object POST and GET routes.
Existing migration history
If you explicitly choose Alchemy to manage migrations for an existing database, see adopting an existing database for the one-way history conversion and compatibility checks. Adoption is a separate decision from generating and committing migration files.
Destroy never deletes migrations
Removing Drizzle.Schema or destroying the stack leaves the checked-in migration directory intact. Database deletion still follows the database resource's lifecycle.
Dialects
dialect | Database guide |
|---|---|
"postgres" (default) | Neon, PlanetScale, Fly, Hyperdrive |
"mysql" | PlanetScale MySQL |
"sqlite" | D1, Durable Objects |