Skip to main content

Get Started with Atlas

Get started with Atlas in under 10 minutes and continue through the website for more features and guides.

For a more detailed introduction to Atlas, check out the full Getting Started guide.

Installation​

To download and install the latest release of the Atlas CLI, simply run the following in your terminal:

curl -sSf https://atlasgo.sh | sh

The default binaries distributed in official releases are released under the Atlas EULA. If you would like obtain a copy of Atlas Community Edition (under an Apache 2 license) follow the instructions here.

Inspecting our database​

The atlas schema inspect command supports reading the database description provided by a URL and outputting it in three different formats: Atlas DDL (default), SQL, and JSON. We will demonstrate be using the Atlas DDL and SQL formats, as the JSON format is often used for processing the output using jq.

To connect to your database, go to the URL documentation to configure the connection URL for your database.

Use the -u flag with the URL to connect to your database and write the output to a file.

For this quickstart guide, we will use a MySQL database containing a simple users table with id and name columns.

atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.my.hcl

Open the schema.hcl file to view the Atlas schema that describes our database.

schema.hcl
table "users" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "name" {
    null = true
    type = varchar(100)
  }
  primary_key {
    columns = [column.id]
  }
}

Changing our schema​

Now, consider we want to add a blog_posts table and have our schema represent a simplified blogging system.

Let's add the following to our schema file and use Atlas to plan and apply the changes to our database.

Edit the schema.hcl file and add the following table block:

schema.hcl
table "blog_posts" {
  schema = schema.example
  column "id" {
    null = false
    type = int
  }
  column "title" {
    null = true
    type = varchar(100)
  }
  column "body" {
    null = true
    type = text
  }
  column "author_id" {
    null = true
    type = int
  }
  primary_key {
    columns = [column.id]
  }
  foreign_key "author_fk" {
    columns     = [column.author_id]
    ref_columns = [table.users.column.id]
  }
}

Now, let's apply these changes by running a migration.

In Atlas, migrations can be applied in two types of workflows: declarative and versioned.

Declarative Migrations​

The declarative approach requires the user to define the desired schema state, and Atlas provides a safe way to alter the database to get there. Let's see this in action.

To apply our schema changes to our database, we will run the apply command:

atlas schema apply \
  -u "mysql://root:pass@localhost:3306/example" \
  --to file://schema.hcl
  --dev-url "docker://mysql/8/example"

This command compares the current state of our database (-u) to the desired state defined in our schema file (--to) using a dev database (--dev-url), and creates a plan to apply the changes that are required to get to the desired state.

Atlas presents the plan it created by displaying the SQL statements:

-- Planned Changes:
-- Create "blog_posts" table
CREATE TABLE `example`.`blog_posts` (`id` int NOT NULL, `title` varchar(100) NULL, `body` text NULL, `author_id` int NULL, PRIMARY KEY (`id`), INDEX `author_id` (`author_id`), CONSTRAINT `author_fk` FOREIGN KEY (`author_id`) REFERENCES `example`.`users` (`id`))
Use the arrow keys to navigate: ↓ ↑ → ←
? Are you sure?:
  ▸ Apply
    Abort

Apply the changes, and that's it! You have successfully run a declarative migration.

To ensure that the changes have been made to the schema, you can run the inspect command again.

atlas schema inspect \
  -u "mysql://root:pass@localhost:3306/example" \
  --web

This time, we use the --web/-w flag to open the Atlas Web UI and view the schema.

Loading ERD...

Versioned Migrations​

Alternatively, the versioned migrations workflow, sometimes called "change-based migrations", allows each change to the database schema to be checked-in to source control and reviewed during code-review. Users can still benefit from Atlas intelligently planning migrations for them, however they are not automatically applied.

To start, we will calculate the difference between the desired and current state of the database by running the atlas migrate diff command.

To run this command, we need to provide the necessary parameters:

  • --dir - the URL to the migration directory (file://migrations by default)
  • --to - the URL of the desired state
  • --dev-url - a URL to a dev database that will be used to compute the diff
atlas migrate diff create_blog_posts \
  --dir "file://migrations" \
  --to "file://schema.hcl" \
  --dev-url "docker://mysql/8/example"

Run ls migrations, and you will notice that Atlas has created two files:

-- create "blog_posts" table
CREATE TABLE `example`.`blog_posts` (`id` int NOT NULL, `title` varchar(100) NULL, `body` text NULL, `author_id` int NULL, PRIMARY KEY (`id`), INDEX `author_id` (`author_id`), CONSTRAINT `author_fk` FOREIGN KEY (`author_id`) REFERENCES `example`.`users` (`id`))

Now that we have our migration files ready, you can use the migrate apply command to apply the changes to the database. To learn more about this process, check out the Versioned Migrations documentation.

Next Steps​

In this short tutorial we learned how to use Atlas to inspect databases, as well as use declarative and versioned migrations.

Continue exploring Atlas by checking out our other guides and documentation for more features and use cases:

  • Databases and Features - Review the different databases and features Atlas supports
  • Atlas Cloud - Set up Atlas Cloud to visualize and monitor your database schema changes
  • Custom Schema Policy - Define and enforce custom schema policies for your schemas and migrations
  • CI/CD - Automate your database schema management by integrating Atlas into your CI/CD pipeline
  • Schema Monitoring - Monitor your database schema changes and detect drift
  • Database-per-Tenant - Use Atlas to manage multi-tenant databases
  • And much more
Need help getting started?
Join our Discord server