Announcing v0.15: Interactive Declarative Migrations, Functions, Procedures and Domains
Hi everyone!
It's been a few weeks since our last version announcement and today I'm happy to share with you
v0.15, which includes some
very exciting improvements for Atlas:
- Interactive Declarative Migrations - Atlas supports a Terraform-like workflow for managing your database schema
using the
schema apply
command. In this release we have added a new "Lint and Edit" mode to this command, which will analyze your schema changes for issues and will allow you to edit them interactively before applying them to your database. - Functions and Stored Procedures - Atlas now supports creating and managing functions and stored procedures in your database schema.
- Postgres Domains - In addition, Atlas now supports Postgres Domains . A domain is essentially a data type with optional constraints (restrictions on the allowed set of values).
- TypeORM Integration - TypeORM is a popular ORM for Node.js. In this release, we are happy to announce the TypeORM integration, which allows you to automatically generate your database schema from your TypeORM entities, create visualizations and more.
Let's dive right in!
Interactive Declarative Migrations
Atlas supports a Terraform-like workflow for managing your database schema using the schema apply
command.
This workflow, which we call "Declarative Migrations", is a modern alternative to the traditional "versioned migrations"
workflow. In declarative migrations, you define your desired schema in one of the formats supported by Atlas and supply
a connection string to your database. Atlas compares the current and desired schema of your database and generates a
plan to migrate your database to the desired state.
Similar to Terraform, until today, Atlas would prompt you to confirm the migration plan before applying it to your database. This is a great way to ensure that you don't accidentally apply a migration that you didn't intend to. However, this flow suffers from a few drawbacks:
- Ensuring Safety - you can count on Atlas to generate a correct migration plan to your desired state,
but it's still possible that this migration will have unintended side effects. For example, adding a
UNIQUE
constraint to a column might fail if there are duplicate values in the column. - Editing - users often want to make changes to their migration plan before applying it. In the current flow, this
requires running
schema apply
with the--dry-run
flag, saving the output to a file, editing it, and then manually applying the edited migration plan to the database.
Enter: Interactive Declarative Migrations
In this release, we are introducing a new "Lint and Edit" mode to the schema apply
command. This mode is
available to logged-in users only, as it uses Atlas Cloud to provide a neat UI and rich analysis capabilities.
Let's see it in action.
Start by downloading the latest version of Atlas:
curl -sSf https://atlasgo.sh | sh
For installation instructions on other platforms, see the installation guide.
After installing Atlas, make sure to log in using the atlas login
command:
atlas login
Next, create a new file named schema.hcl
that will contain your desired schema:
schema "main" {
}
table "hello" {
schema = schema.main
column "name" {
type = varchar(100)
default = "Anonymous"
}
}
Now, let's apply this schema to a local SQLite database named "sqlite.db":
atlas schema apply -u sqlite://sqlite.db --dev-url sqlite://?mode=memory -f schema.hcl
Atlas will calculate the diff between the current (empty) state of the database and our desired state and prompt us to confirm the migration plan:
-- Planned Changes:
-- Create "hello" table
CREATE TABLE `hello` (`name` varchar NOT NULL DEFAULT 'Anonymous');
Use the arrow keys to navigate: ↓ ↑ → ←
? Are you sure?:
Apply
▸ Lint and edit # <-- Brand new!
Abort
Notice the new "Lint and edit" option. Select it and press Enter. Atlas will now analyze the migration plan and open your browser in the new, interactive migration plan screen. The screen contains three important sections:
- Migration Plan - the migration plan generated by Atlas. You can click the "Edit" button to make changes to it.
- Checks - a summary of the checks that Atlas ran against the generated plan. In this case, our plan is completely safe, so all checks passed.
- ERD - A visual representation of the change we are planning.
Once we are content with the migration plan, let's go ahead and click the "Approve and Apply" button. Atlas will apply the migration plan to the database and scroll down to the execution logs section:
Let's edit our desired state a bit to delete the hello
table and add a new users
table:
schema "main" {
}
-table "hello" {
- schema = schema.main
- column "name" {
- type = varchar(100)
- default = "Anonymous"
- }
-}
+table "users" {
+ schema = schema.main
+ column "id" {
+ type = int
+ }
+ column "email" {
+ type = text
+ }
+ primary_key {
+ columns = [column.id]
+ }
+ index "unique_email" {
+ columns = [
+ column.email
+ ]
+ unique = true
+ }
+}
Once again, let's run atlas schema apply
to apply the changes to the database and select the "Lint and Edit" option.
This time, Atlas will warn us that the migration plan is not safe:
In this case, we decide to abort the migration in order to not lose the precious data on the
hello
table. Good thing we have automatic migration linting on our side!