From 417c21f49ed744930e72570cbe28321f64a30263 Mon Sep 17 00:00:00 2001 From: Julian Cuni Date: Sat, 2 May 2026 09:55:22 +0200 Subject: [PATCH] Document destructive-apply hazard in directus entity page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A real incident hit during directus Phase 1 task 1.5: 5 newly-created collections were destroyed by a container rebuild because the baked-in snapshot was stale. directus schema apply --yes enforces the snapshot as the single source of truth — anything not in the snapshot gets deleted. This is correct for fresh-environment provisioning and prod, but catastrophic during active schema development. Adding a callout to the directus entity page so future readers see the operator rule alongside the snapshot/apply pattern documentation: Never restart or rebuild the Directus container while there are uncommitted schema changes. Always: change → snapshot → commit → rebuild/restart. The recovery path (re-apply via MCP / admin UI, snapshot before restart) is straightforward in dev but would be data-loss in prod. Phase 3 hardening will introduce a DIRECTUS_SCHEMA_APPLY_MODE env var with auto/dry-run/skip modes so dev environments default to non-destructive behavior. --- wiki/entities/directus.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/wiki/entities/directus.md b/wiki/entities/directus.md index f679c8d..ac788d5 100644 --- a/wiki/entities/directus.md +++ b/wiki/entities/directus.md @@ -67,6 +67,12 @@ Local dev edits the schema in the admin UI, then snapshots before commit. CI bui This treats `schema.yaml` as the source of truth and the admin UI as its editor. Don't hand-edit `schema.yaml`; round-trip through the UI to keep the format consistent. +> **⚠️ Destructive-apply hazard.** `directus schema apply --yes` enforces the snapshot as the single source of truth: anything in the running DB that is *not* in the snapshot gets **deleted** during apply. This is correct for fresh-environment provisioning and prod, but a foot-gun during active schema development. The boot pipeline runs apply on every container start (entrypoint step 2/4 — see [[processor]] for the analogous staged-apply pattern). +> +> **Operator rule:** *Never restart or rebuild the Directus container while there are uncommitted schema changes.* The flow is always: change in admin UI / via MCP → `pnpm run schema:snapshot` → commit → only then rebuild/restart. +> +> A real incident hit this during Phase 1 task 1.5: 5 newly-created collections were destroyed by a rebuild because the baked-in snapshot was stale. Recovery was straightforward in dev (recreate via MCP, snapshot, commit) but would be data-loss in prod. CI dry-run (Phase 1 task 1.8) catches snapshot drift before it reaches stage. A long-term mitigation — `DIRECTUS_SCHEMA_APPLY_MODE` env var with `auto` / `dry-run` / `skip` modes — is on the Phase 3 hardening roadmap. + ## Phase 2 role Directus owns the `commands` collection and is the **single auth surface** for outbound device commands. The SPA inserts command rows; a Directus Flow routes them via Redis to the Ingestion instance holding the device's socket. See [[phase-2-commands]].