From 67f7c4836d03884370991de5bd8e1c33602102a0 Mon Sep 17 00:00:00 2001 From: Mannu Date: Sat, 30 May 2026 09:55:35 +0530 Subject: [PATCH] docs: warn that migration journal `when` must exceed the last applied MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drizzle's migrator applies a migration only when its journal `when` is greater than the max created_at already recorded. Entries 0003-0010 were given 2025-era timestamps (smaller than the 2026 baseline), so drizzle silently skipped them — they only applied via the debug-migration hot-apply endpoint. Document the rule. Co-Authored-By: Claude Opus 4.8 --- CLAUDE.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index d6429fa..e979b58 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -75,6 +75,16 @@ drizzle/meta/_journal.json # Migration order — MUST update when adding new SQL 2. Add an entry to `drizzle/meta/_journal.json` with the next `idx` and matching `tag` 3. Push to git → Dokploy auto-applies on next deploy +> ⚠️ **CRITICAL — the `when` timestamp must be greater than every existing entry.** +> Drizzle's migrator only applies a migration when its `when` (folderMillis) is **greater than the +> max `created_at` already in `drizzle.__drizzle_migrations`**. It does NOT diff by hash/idx. +> Migrations `0003`–`0010` were hand-added with 2025-era `when` values (1748…/1749…) that are +> SMALLER than the 2026 baseline (0000–0002 ≈ 1779539431897), so drizzle **silently skipped all of +> them** — they only ever got applied via the debug-migration hot-apply endpoint. +> For any new migration: set `when` to a **current `Date.now()`** (must be > 1779539431897). If you +> ever need drizzle to re-apply a skipped one, its SQL must be idempotent (`IF NOT EXISTS`); note +> `0003_circles.sql` is NOT idempotent, so do not let drizzle re-run it. + ### Hot-fix: apply migration without waiting for redeploy Use the **debug-migration endpoint** (same pattern as the Circles implementation):