Atlas Migrations

8 min readAug 24, 2024

123

這份文章提供了 Atlas 版本化遷移工作流程的高層次概述。它將引導您完成創建遷移目錄、根據目標架構自動生成 SQL 遷移、將遷移目錄推送到 Atlas 架構註冊表，以及將變更應用到數據庫的步驟。如需更深入的指南，請查看本節的其他頁面或訪問官方的指南集。

Creating the first migration

Atlas 最受歡迎的功能之一是能夠根據目標架構自動生成 SQL 遷移腳本。可以通過多種方式定義架構：使用 Atlas 的 HCL 語言、標準 SQL、外部 ORM 或程序。在本指南中，我們將使用 SQL 架構來定義我們的目標狀態。

首先，讓我們創建一個簡單的 SQL 架構，其中包含兩個表：users 和 repos，並將其命名為 schema.sql：

CREATE TABLE `users` (
  `id` bigint,
  `name` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
);

CREATE TABLE `repos` (
  `id` bigint,
  `name` varchar(255) NOT NULL,
  `owner_id` bigint NOT NULL,
  PRIMARY KEY (`id`),
  CONSTRAINT `owner_id` FOREIGN KEY (`owner_id`) REFERENCES `users` (`id`)
);

我們已經創建了 schema.sql 文件，現在我們要使用 Atlas 來生成遷移腳本。這個遷移腳本將包含必要的 SQL 命令，用於將我們定義的架構應用到實際的數據庫中。

atlas migrate diff initial \
  --to file://schema.sql \
  --dev-url "docker://mysql/8/dev" \
  --format '{{ sql . "  " }}'

遷移差異標誌(Migrate Diff Flags)：

dev-url - 這是用來指定開發數據庫的 URL。開發數據庫是 Atlas 用來計算架構變更的臨時數據庫。
format - 這個標誌用於控制生成的 SQL 腳本的格式，特別是縮進。

運行 ls migrations，你會注意到 Atlas 已經創建了兩個文件：

最後，它指示用戶運行 ls migrations 命令來查看 Atlas 創建的文件。正如我之前解釋的，這通常會顯示兩個文件：一個 SQL 遷移文件和一個 Atlas 元數據文件。

Pushing migrations to the Schema Registry

現在我們有了第一個遷移，我們可以將它應用到數據庫。有多種方法可以實現這一點，大多數方法都在指南部分有所介紹。在這個例子中，我們將演示如何將遷移推送到 Atlas 架構註冊表，這很像將 Docker 映像推送到 Docker Hub。

這種方法的優點可能包括：

集中管理遷移
便於團隊協作
可以跟踪不同環境的架構版本

首先，登入 Atlas。如果這是你第一次使用，你將會被提示創建一個帳戶和一個工作空間（組織）：

atlas login

登入後，我們將新遷移專案命名為 app，並執行 atlas migrate push：

atlas migrate push app \
  --dev-url "docker://mysql/8/dev"

Applying migrations

一旦我們的 app 遷移目錄已經被推送，我們可以從任何 CD 平台將其應用到資料庫，而無需從版本控制中提取遷移檔案。為了這個例子，我們來啟動一個Docker本地資料庫，作為我們的生產資料庫，並將遷移應用到它：

docker run --rm -d --name atlas-demo -e MYSQL_ROOT_PASSWORD=pass -e MYSQL_DATABASE=example -p 3306:3306 mysql

接著，我們將創建一個簡單的 Atlas 配置檔案（atlas.hcl），用來儲存我們環境的設置：

# The "local" environment represents our local testings.
env "local" {
  url = "mysql://root:pass@:3306/example"
  migration {
    dir = "atlas://app"
  }
}

最後一步是將遷移應用到資料庫。我們執行 atlas migrate apply 並使用 --env 標誌來指示 Atlas 從 atlas.hcl 檔案中選擇環境配置：

atlas migrate apply --env local

Generating another migration

在應用第一次遷移後，我們需要更新在 schema.sql 中定義的架構，並告訴 Atlas 生成另一個遷移。這樣可以讓遷移目錄（以及資料庫）與新定義的目標架構（schema.sql）保持一致。

我們來對架構做兩個變更：

在 repos 表中新增一個 description 欄位。
新增一個 commits 表，並使用外鍵將其與 repos 和 users 表連接起來。

CREATE TABLE `users` (
  `id` bigint,
  `name` varchar(255) NOT NULL,
  PRIMARY KEY (`id`)
);

CREATE TABLE `repos` (
  `id` bigint,
  `name` varchar(255) NOT NULL,
  `description` varchar(255) NULL,
  `owner_id` bigint NOT NULL,
  PRIMARY KEY (`id`),
  CONSTRAINT `owner_id` FOREIGN KEY (`owner_id`) REFERENCES `users` (`id`)
);

CREATE TABLE `commits` (
  `id` bigint,
  `message` varchar(255) NOT NULL,
  `repo_id` bigint NOT NULL,
  `author_id` bigint NOT NULL,
  PRIMARY KEY (`id`),
  CONSTRAINT `repo_id` FOREIGN KEY (`repo_id`) REFERENCES `repos` (`id`),
  CONSTRAINT `author_id` FOREIGN KEY (`author_id`) REFERENCES `users` (`id`)
);

接下來，我們準備再次執行 atlas migrate diff 來生成新的遷移：

atlas migrate diff add_commits \
  --to file://schema.sql \
  --dev-url "docker://mysql/8/dev" \
  --format '{{ sql . "  " }}'

執行 ls migrations，你會注意到一個新的遷移已經生成。我們再次執行 atlas migrate push，並觀察遷移目錄頁面上的更新：

atlas migrate push app \
  --dev-url "docker://mysql/8/dev"

目前mysql

讓我們apply最新的遷移，然後再次檢查我們的資料庫：

atlas migrate apply --env local

如你所見，資料庫現在已經與遷移目錄保持同步：

Atlas Migrations

Creating the first migration

Pushing migrations to the Schema Registry

Applying migrations

Generating another migration

Written by Jeff Yen