Skip to main content

Importing a Goose project to Atlas

TL;DR​

  • pressly/goose is a popular database migration CLI tool and Go library that's widely used in the Go community.
  • Atlas is an open-source tool for inspecting, planning, linting and executing schema changes to your database.
  • Developers using goose that want to start managing their database schema using Atlas can follow this guide to import an existing project to Atlas.

Prerequisites​

Convert the migration files​

The first step in importing a project to Atlas is to convert the existing migration files from the Goose SQL format to the Atlas format.

To automate this process Atlas supports the atlas migrate import command. To read more about this command, read the docs.

Suppose your migrations are located in a directory named goose and you would like to convert them and store them in a new directory named atlas. For this example, let's assume we have a simple Goose project with only two files:

.
├── 20221027094633_init.sql
└── 20221027094642_new.sql

Run:

atlas migrate import --from file://goose?format=goose --to file://atlas

Observe that a new directory named atlas was created with 3 files:

.
├── 20221027094633_init.sql
├── 20221027094642_new.sql
└── atlas.sum

A few things to note about the new directory:

  • When converting the migration files, Atlas ignores the down migrations as those are not supported by Atlas.
  • Atlas created a file named atlas.sum. To ensure migration history is correct while multiple developers work on the same project in parallel, Atlas enforces migration directory integrity using this file.
  • Comments not directly preceding a SQL statement are dropped as well.

Set the baseline on the target database​

Like many other database schema management tools, Atlas uses a metadata table on the target database to keep track of which migrations were already applied. In the case where we start using Atlas on an existing database, we must somehow inform Atlas that all migrations up to a certain version were already applied.

To illustrate this, let's try to run Atlas's migrate apply command on a database that is currently managed by Goose using the migration directory that we just converted:

atlas migrate apply --dir file://atlas --url mysql://root:pass@localhost:3306/dev

Atlas returns an error:

Error: sql/migrate: connected database is not clean: found table "atlas_schema_revisions" in schema "dev". baseline version or allow-dirty is required

To fix this, we use the --baseline flag to tell Atlas that the database is already at a certain version:

atlas migrate apply --dir file://atlas --url mysql://root:pass@localhost:3306/dev  --baseline 20221027094642

Atlas reports that there's nothing new to run:

No migration files to execute

That's better! Next, let's verify that Atlas is aware of what migrations were already applied by using the migrate status command:

atlas migrate status --dir file://atlas --url mysql://root:pass@localhost:3306/dev

Atlas reports:

Migration Status: OK
  -- Current Version: 20221027094642
  -- Next Version:    Already at latest version
  -- Executed Files:  1
  -- Pending Files:   0

Great! We have successfully imported our existing Goose project to Atlas.

Wrapping up​

In this guide we have demonstrated how to take an existing project that is managed by pressly/goose, a popular schema migration tool to be managed by Atlas.

Have questions? Feedback? Find our team on our Discord server.