trm/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document destructive-apply hazard in directus entity page

Browse Source 
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.
This commit is contained in:
Julian Çuni
2026-05-02 09:55:22 +02:00
parent 507aa8b23b
commit 417c21f49e
1 changed files with 6 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/entities/directus.md
+6
View File
@@ -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]].