Directus changes its schema and content over time. To maintain predictability between environments, versioning migrations and snapshots is essential.
Objective
- Avoid schema drift between dev/staging/prod.
- Allow content reproducibility (when necessary).
- Ensure that destructive changes are noticed before applying.
Migrations (schema)
Rules:
- Treat schema as code: migrations/snapshots versioned in the repository.
- Apply migrations in the correct order and with review (PR) when changing collections/fields/relations/constraints.
- Do not "edit in prod" to resolve it; create a migration and run it in the pipeline.
- Keep changes compatible first: add → migrate content → remove/transform in future steps.
Data Import/Export
Use when:
- Initial project seed (e.g., default categories)
- Controlled content reset in staging
- Data migration between schema versions
Rules:
- Export the minimum necessary for seeds: essential data and references.
- When importing, validate dependencies: relations/foreign keys must exist in the destination.
- Avoid overwriting production with generic snapshots; keep exports per environment.
Environment strategy
- Dev: higher speed, but always with snapshots/migrations in a PR.
- Staging: full validation (auth, queries, UI).
- Prod: changes with a window and documented rollback/forward strategy.
Security
- Exported data may contain PII: handle it carefully (separate storage, permissions, do not log).
- Do not commit secrets or tokens in exports.
Integration with the toolkit
- Modeling:
directus-data-modeling - Permissions:
directus-auth-permissions - Consumption:
directus-integration - Extensions:
directus-extensions - Files:
directus-files
Completion criteria
- Schema changes follow a reproducible path (export/snapshot + migration)
- Import/seed is controlled and documented per environment
- The pipeline reduces drift and facilitates rollback when there is an incident