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.