Deploying from Atlas Cloud
In the past, we have recommended users to build a migrations Docker image as part of their CI pipeline and then use that image during their deployment process. This is still a valid approach, as it bundles together the Atlas binary needed to run migrations with the migrations themselves. However, over the last year we have received feedback from many users that this approach is cumbersome and requires a lot of boilerplate code to be written.
To address this, we have introduced a new way to deploy migrations directly from Atlas Cloud.
On a high-level this approach works as follows:
- Users sync their migration directory to Atlas Cloud whenever you push new code to your mainline branch.
- Migrations are executed directly from Atlas Cloud during deployment.
This guide shows you how to set up this approach for your project.
Prerequisites
- An Atlas Cloud account with administrator access. (If you don't have an account, you can sign up for free.)
- Sync your migration directory from GitHub to your Atlas Cloud account. (See Syncing Migration Directories for more information.)
- A token for an Atlas Cloud Bot user with permissions report CI/CD runs and read the migration directory. (See Creating a Bot User for more information.
Deploying migrations from Atlas Cloud
Once your migration directory is synced to Atlas Cloud, you can deploy them using the atlas
CLI.
To get started, create a project configuration file named atlas.hcl
:
variable "cloud_token" {
type = string
default = getenv("ATLAS_TOKEN")
}
atlas {
cloud {
token = var.cloud_token
}
}
data "remote_dir" "migration" {
name = "<name of dir>"
}
env {
name = atlas.env
url = getenv("DATABASE_URL")
migration {
dir = data.remote_dir.migration.url
}
}
Let's review what this configuration file does:
- The
cloud_token
variable is used to authenticate with Atlas Cloud. You can either set this variable in your environment or pass it in as a command line argument. - The
atlas
block sets global configuration for Atlas. In this case, we are setting Atlas to work against Atlas Cloud, using the token we defined in the previous step. - We define a data source of the type
remote_dir
to fetch the migration directory from Atlas Cloud. We use thename
parameter to specify the name of the directory we want to fetch. This name is the same as the name you used when you synced your migration directory. - Finally, we define an environment using the
env
block that uses the migration directory we fetched from Atlas Cloud. To avoid setting database credentials in the configuration file, we use theDATABASE_URL
environment variable.
Running migrations from Atlas Cloud
Once you have created your configuration file, you can run migrations from Atlas Cloud using the atlas
CLI
using the following commands:
export ATLAS_TOKEN=<your token>
export DATABASE_URL=<your database url>
atlas migrate apply --env <env name>
Let's review what these commands do:
- We set the
ATLAS_TOKEN
environment variable to the token we created earlier. - We set the
DATABASE_URL
environment variable to the URL of the database we want to run migrations against. - We run the
atlas migrate apply
command to apply migrations to the database. The--env
flag is used to specify the name of the environment we defined in the configuration file.
The atlas migrate apply
command will run all migrations that have not been applied to the database yet:
Migrating to version 20230306221009 (1 migrations in total):
-- migrating version 20230306221009
-> create table users (
id int primary key
)
-- ok (8.60933ms)
-------------------------
-- 68.037117ms
-- 1 migrations
-- 1 sql statements
Viewing migrations in Atlas Cloud
After the migrations have been applied, you can view them in Atlas Cloud by heading to the /deployments
page
in your Atlas Cloud account. You should see a new deployment with the name of the environment you specified in
the configuration file. Clicking on the deployment will show you the details of the deployment, including the
migrations that were applied: