| name | atlas-best-practices |
| description | Use when working with atlas.hcl, Atlas CLI commands, schema HCL/SQL files, or migration planning and reviews, including Atlas v1.1 security, data, and exporter capabilities. |
Atlas Best Practices
Atlas supports declarative and versioned schema workflows. Keep this file minimal and load only the reference file needed for the current task.
Workflow Selection
- Use declarative workflow when desired schema state is the source of truth.
- Use versioned workflow when migration files are required for auditing and staged deployments.
- Use baseline workflow when onboarding an existing database.
Default Execution Flow
- Confirm the target
env in atlas.hcl.
- Confirm
dev is configured and isolated from production.
- Plan first, then lint/test/validate, then apply.
- Run production changes through CI/CD or approved deployment workflow.
Quick Commands
atlas schema apply --env local
atlas migrate diff add_change --env local
atlas migrate lint --env local --latest 1
atlas migrate apply --env local
atlas migrate validate --env local
atlas migrate status --env local
Reference Map
- core-workflows.md
Use for environment config, schema-as-code patterns, declarative vs versioned workflows, baselining, and ORM provider loading.
- safety-and-quality.md
Use for lint analyzers, transaction modes, schema tests, pre-execution checks, and CI patterns.
- atlas-v1-1-features.md
Use for Atlas v1.1 coverage (released on 2026-02-03), including security as code, declarative data, new drivers/platform support, Slack integration, schema exporters, and MySQL TLS.
- cli-agent-gaps.md
Use for Atlas CLI capabilities and edge cases agents often miss: planning workflows, migration directory maintenance commands, URL/TLS pitfalls, feature availability, and version policy constraints.
Guardrails
- Keep credentials out of source files; prefer Atlas data sources and input variables.
- Require explicit review for destructive or data-dependent migrations.
- Fail loudly on unsupported drivers, missing
dev URLs, or unknown environment names.