Skip to main content

Schema as Code: Directory Structure for HCL Files

Question​

How do I configure Atlas to load the database schema from nested directories with HCL files?

 /project
 ├── main.hcl
 ├── extensions
 └── schemas
     └── public
         ├── public.hcl
         ├── tables
         │   ├── pets.hcl
         │   ├── posts.hcl
         │   ├── profiles.hcl
         │   └── user_groups.hcl
         ├── functions/
         └── types/

How do I resolve out-of-order migration conflicts after a hotfix?

When working with multiple branches and applying hotfixes directly to production, out-of-order migration conflicts may occur if migration files are created with timestamps that don't reflect the actual merge order.

The Problem​

Consider this scenario:

Initial state:

  • Master branch:
    • 001_initial.sql
  • Dev branch (PR pending):
    • 001_initial.sql
    • 002_add_posts.sql
    • 004_add_index.sql

After hotfix applied directly to production:

  • Master branch:
    • 001_initial.sql
    • 003_hotfix_add_email.sql ← hotfix added
  • Dev branch (unchanged):
    • 001_initial.sql
    • 002_add_posts.sql
    • 004_add_index.sql

out-of-order migrations

After merging master into dev - the problem:

  • 001_initial.sql - Applied to production
  • 002_add_posts.sql - Dev-only, not applied to production
  • 003_hotfix_add_email.sql - Applied to production
  • 004_add_index.sql - Dev-only, not applied to production

This creates a non-linear migration history where migration files 002 and 004 were created before and after the hotfix timestamp but haven't been applied to production.

Handling drift between my schema and the atlas_schema_revisions table

Question​

My revisions table lists the following versions:

mysql> SELECT * FROM  "atlas_schema_revisions";
+-------------------------+---------+-----+
| version                 | applied | ... |
+-------------------------+---------+-----+
| .atlas_cloud_identifier | 0       |     |
| 20251007053111          | 1       |     |
| 20251007051222          | 1       |     |
| 20250618084333          | 1       |     |
+-------------------------+---------+-----+

However, when I inspect the target database, the schema changes from 20250618084333 were never applied. How can I delete the latest row(s) so the revision history reflects the actual state?