Skip to main content

Project Structure

After successfully verifying Atlas can connect to your database and understand its schema, let's proceed to setting up your project.

A typical project layout may look something similar to this:

.
├── atlas.hcl
├── migrations
│   ├── 20240520182315.sql
│   ├── 20240520182336.sql
│   └── atlas.sum
└── schema.hcl

A typical Atlas project comprises 3 important parts:

  • Schema-as-Code - The desired state of your database should be present "as code" in the source control repository of your project.
  • Project Configuration File - this file is typically named atlas.hcl and is located in the root directory of your project. If you are using a "Monorepo" architecture, you will have one of these files per Atlas project.
  • Migrations - While Atlas supports both purely Versioned and Declarative workflows, currently most teams that use Atlas in production use the mixed approach where the source of truth for the desired state of the schema is stored "as code", but migrations are still explicitly managed in a dedicated directory, typically named migrations/.

Step 1: Create your project config file​

Before moving on to building CI and deployment pipelines, we will focus on building a setup for local development.

Let's start this by creating our initial project configuration file.

Create a file named atlas.hcl and place it at your project root.

In this file define an env block for local development:

env "local" {
  dev = "docker://postgres/16/dev" // <-- Replace your with your dev database URL.
}

Be sure to replace the dev URL with the URL you determined in Step 3 of the previous section.

Step 2: Verify your configuration works​

Let's repeat our verification from the previous section, this time using the --env flag instead of spelling out our Dev Database URL explicitly:

atlas schema diff --env local --from file://schema.hcl --to "$DB_URL"

This command will calculate the diff between the schema which we saved from your live database to schema.hcl in a previous step and the current schema of the database in $DB_URL.

Unless your database schema changed in the interim, you should see the same output you got in the verification step of the previous section:

Schemas are synced, no changes to be made.

In the next section, we will explore how to define the desired schema of your database, as code.