diff --git a/CLAUDE.md b/CLAUDE.md
index 9496d90..d305927 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -56,3 +56,14 @@ Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.
   ```
 - A local MariaDB is expected to already be running on `127.0.0.1:3306` with the `file_converter` DB and `convert_user` credentials seeded.
 - Known pre-existing failures unrelated to any fix: `test/cleanup.test.js` ("deletes an expired pending job...") and `test/jobs/jobRepository.test.js` ("finds expired jobs and allows deleting them") — both fail on `main` independent of other changes (looks like a clock/timezone mismatch around `expiresAt` comparisons, not yet root-caused). Don't assume a change caused these; verify against `main` first if they show up again.
+
+## Database schema & migrations
+
+- `prisma/schema.prisma` is the source of truth for the `conversion_jobs` schema; `prisma/migrations/` is its version history. `db/schema.sql` no longer exists.
+- Prisma CLI commands (`prisma migrate dev`, `prisma migrate deploy`, `prisma generate`) need `DATABASE_URL` in their own process environment, separate from the app. Compute it from the same `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME` values used for local tests, via `node scripts/printDatabaseUrl.js` — never write `DATABASE_URL` into `.env` or `.env.local`.
+- To create a new migration locally after editing `prisma/schema.prisma`:
+  ```
+  DB_HOST=127.0.0.1 DB_USER=convert_user DB_PASSWORD=change_me DB_NAME=file_converter STORAGE_DIR=./storage \
+    DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate dev --name <description>
+  ```
+- To apply pending migrations in production: with the real `DB_*` values loaded from `.env`, run `DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy` before starting the app.
diff --git a/prisma/migrations/0_init/migration.sql b/prisma/migrations/0_init/migration.sql
new file mode 100644
index 0000000..fba9171
--- /dev/null
+++ b/prisma/migrations/0_init/migration.sql
@@ -0,0 +1,30 @@
+-- CreateTable
+CREATE TABLE `conversion_jobs` (
+    `id` INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
+    `uuid` CHAR(36) NOT NULL,
+    `status` ENUM('pending', 'processing', 'done', 'failed') NOT NULL DEFAULT 'pending',
+    `family` VARCHAR(32) NOT NULL,
+    `source_format` VARCHAR(16) NOT NULL,
+    `target_format` VARCHAR(16) NOT NULL,
+    `original_filename` VARCHAR(255) NOT NULL,
+    `input_path` VARCHAR(255) NOT NULL,
+    `output_path` VARCHAR(255) NULL,
+    `input_mime_type` VARCHAR(128) NOT NULL,
+    `output_mime_type` VARCHAR(128) NULL,
+    `input_size_bytes` INTEGER UNSIGNED NOT NULL,
+    `output_size_bytes` INTEGER UNSIGNED NULL,
+    `quality` SMALLINT UNSIGNED NULL,
+    `conversion_duration_seconds` DECIMAL(10, 3) NULL,
+    `error_message` VARCHAR(255) NULL,
+    `error_log` TEXT NULL,
+    `created_at` DATETIME(0) NOT NULL DEFAULT CURRENT_TIMESTAMP(0),
+    `updated_at` DATETIME(0) NOT NULL DEFAULT CURRENT_TIMESTAMP(0),
+    `expires_at` DATETIME(0) NOT NULL,
+    `cleaned_at` DATETIME(0) NULL,
+
+    UNIQUE INDEX `uniq_uuid`(`uuid`),
+    INDEX `idx_status`(`status`),
+    INDEX `idx_expires_at`(`expires_at`),
+    PRIMARY KEY (`id`)
+) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+
diff --git a/prisma/migrations/migration_lock.toml b/prisma/migrations/migration_lock.toml
new file mode 100644
index 0000000..592fc0b
--- /dev/null
+++ b/prisma/migrations/migration_lock.toml
@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "mysql"