1. Atlasの紹介
Atlasは、現代のDevOps原則を使用してデータベーススキーマの管理と移行を目的として設計された、言語に依存しないツールです。以下の2つのワークフローオプションを提供しています。
- 宣言的: Terraformと同様に、AtlasはHCL、SQL、またはORMスキーマを使用して定義された目的の状態と現在のデータベースの状態を比較します。この比較に基づいて、データベースを目的の状態に移行するためのマイグレーション計画を生成および実行します。
- バージョン管理: 他のツールとは異なり、Atlasはスキーマのマイグレーションを自動的に計画します。ユーザーはHCL、SQL、または選択したORMを使用して目的のデータベーススキーマを記述し、Atlasを使用してデータベースに必要なマイグレーションの計画、レビュー、適用を行うことができます。
Atlasの主な利点の1つは、データベース管理の複雑さを単純化し、バージョン管理、協力、および実装を容易にすることです。
2. Atlasのインストール
データベースのバージョンを管理するためにAtlasを使用する前に、インストールする必要があります。以下はさまざまなプラットフォーム用のインストール手順です。
2.1 macOS + Linuxへのインストール
macOSまたはLinuxシステムでは、以下のコマンドラインを使用して、最新バージョンのAtlasをダウンロードしてインストールすることができます。
curl -sSf https://atlasgo.sh | sh
このコマンドは自動的にオペレーティングシステムのバージョンを検出し、適切なビルドバージョンをダウンロードしてAtlasバイナリファイルを実行可能なパスに配置します。
2.2 Homebrewを使用したインストール
macOSを使用しており、すでにHomebrewパッケージマネージャをインストールしている場合、次のコマンドを実行するだけでAtlasを簡単にインストールできます。
brew install ariga/tap/atlas
これにより、Homebrewのリポジトリから最新バージョンのAtlasが取得され、インストールされます。
2.3 Dockerを使用したインストール
Dockerを介してAtlasをインストールおよび実行する方法は、特に一時的なテスト用途やホストシステムに追加のソフトウェアをインストールしたくないユーザーにとって、迅速で便利な方法です。
まず、Atlas Dockerイメージを取得します。
docker pull arigaio/atlas
次に、正常にインストールされているかを確認するために、ヘルプコマンドを実行できます。
docker run --rm arigaio/atlas --help
コンテナがホストネットワークやローカルディレクトリにアクセスする必要がある場合は、--net=hostフラグを使用し、必要なディレクトリをマウントします。
docker run --rm --net=host \
-v $(pwd)/migrations:/migrations \
arigaio/atlas migrate apply \
--url "mysql://root:pass@:3306/test"
2.4 Windowsへのインストール
バイナリファイルhttps://release.ariga.io/atlas/atlas-windows-amd64-latest.exeをダウンロードし、インストールパスをシステムのPATH環境変数に追加します。
3. Atlasを使用して既存のデータベーステーブル構造をエクスポートする方法
Atlasには、既存のデータベースの構造をエクスポートするための atlas schema inspect コマンドがあります。このコマンドは、データベースの説明をデータベースのURLから読み取り、デフォルトのAtlas HCL形式、SQL形式、およびJSON形式の3つの異なる形式で出力できます。このガイドでは、Atlas HCL形式とSQL形式の使用方法を説明し、JSON形式は通常、jqを使用して出力を処理するために使用されます。
ローカルで実行されているMySQLインスタンスを検査し、出力を schema.hcl というファイルに書き込むには、次のコマンドを使用します:
atlas schema inspect -u "mysql://root:pass@localhost:3306/example" > schema.hcl
schema.hcl ファイルを開いて、データベースを記述するAtlasのテーブル構造定義を表示します（HCLはAtlasによって定義されたデータベースに依存しないテーブル構造の構成形式です）。例えば、このファイルには次の内容が含まれます:
table "users" {
schema = schema.example
column "id" {
null = false
type = int
}
column "name" {
null = true
type = varchar(100)
}
primary_key {
columns = [column.id]
}
}
このコードブロックは、id と name の列を持つテーブル構造を表しています。schema フィールドは、このドキュメントの他の場所で定義された example モデル定義を参照しています。また、primary_key のサブブロックは、テーブルの主キーとして id 列を指定しています。Atlasは操作されているデータベースの構文を模倣しようとしています。この例では、id 列は int 型であり、name 列は varchar(100) 型であることが示されています。
同様に、データベースのSQLモデル定義をエクスポートするには、次のコマンドを使用します:
atlas schema inspect -u "mysql://root:pass@localhost:3306/example" --format '{{ sql . }}' > schema.sql
schema.sql ファイルを開いて、通常はいくつかのCREATE TABLEステートメントを含んでいるデータベースのSQLの説明を表示します。
この方法により、既存のデータベーステーブル構造の詳細を理解するのが便利になり、後続のバージョン管理されたマイグレーションの正確な参照が提供されます。
4.2.1 差分の計算
マイグレーションを開始する前に、現在のデータベース構造と目標の状態を比較し、両者の違いを特定する必要があります。これは atlas migrate diff コマンドを実行することで実現できます。
atlas migrate diff create_blog_posts \
--dir "file://migrations" \
--to "file://schema.hcl" \
--dev-url "docker://mysql/8/example"
--dir はマイグレーションフォルダのURLを指定し、デフォルトは file://migrations です。 --to は目標状態のURLを指定し、--dev-url は差分を計算するのに使用する開発用データベースのURLを提供します（注意：この --dev-url は、差分を計算するためにAtlasが使用する空のデータベースを指定する必要があります）。
ヒント：SQLファイルを生成する場合は、
--formatパラメータを使用してフォーマットを設定するため、前のセクションを参照してください。
4.2.2 マイグレーションの適用
差分の計算が完了すると、Atlas は migrations フォルダに保存された2つのマイグレーションファイルを生成します。たとえば、選択したフォーマットがSQLの場合、diff コマンドによって生成されるファイルは以下のような、新しいテーブルを作成するためのマイグレーションコマンドを含むSQLファイルです:
-- "blog_posts" テーブルを作成
CREATE TABLE `blog_posts` (
`id` int NOT NULL,
`title` varchar(100) DEFAULT NULL,
`body` text DEFAULT NULL,
`author_id` int NULL REFERENCES `users`(id),
PRIMARY KEY (`id`)
);
マイグレーションファイルが生成されたら、これらの変更を管理するためにバージョン管理ツール（例: Git）を使用できます。この方法を使用すると、開発環境で多くのデータベーステーブル構造の変更を行うことができます。そしてリリース時に、開発環境とUAT環境を比較するためにAtlasコマンドを使用して、データベーステーブル構造のマイグレーションファイルを生成することが可能です。これらのマイグレーションファイルは、UAT環境と本番環境に適用してデータベースをアップグレードすることができます。
これらのDeclarativeおよびVersionedの2つのワークフローは、さまざまな開発および展開モードに柔軟性を提供し、データベーススキーマの変更を管理するためのプロジェクトのニーズに最も適した方法をチームが選択できるようにします。
5. HCL形式の記述
5.1 導入
HCLはデータベーステーブル構造の定義を記述するために使用される宣言型の言語です。Atlas は、データベーススキーマを記述するためにHCL形式を使用し、データベースのさまざまな側面を記述するための豊富な構造を提供します。HCLの利点は、可読性と保守性の高さ、および変数の注入や追加の注釈などの機能のサポートにあります。
ヒント：プロジェクトが複数のデータベースに適応する必要がある場合、HCLを使用してデータベースに依存しない方法で表の構造を記述することは非常に便利です。
5.2 schema オブジェクト
schema オブジェクトはデータベーススキーマを記述するために使用されます。MySQLおよびSQLiteでは、DATABASE を、PostgreSQLでは SCHEMA を表します。HCLファイルには1つ以上のschema オブジェクトが含まれることがあります。
schema "public" {
comment = "スキーマのコメント"
}
schema "private" {}
5.3 table オブジェクト
table オブジェクトはSQLデータベースのテーブルを記述するために使用され、列、インデックス、制約、および異なるデータベースドライバがサポートするさまざまな追加プロパティを含みます。
table "users" {
schema = schema.public
column "id" {
type = int
}
column "name" {
type = varchar(255)
}
column "manager_id" {
type = int
}
primary_key {
columns = [
column.id
]
}
index "idx_name" {
columns = [
column.name
]
unique = true
}
foreign_key "manager_fk" {
columns = [column.manager_id]
ref_columns = [table.users.column.id]
on_delete = CASCADE
on_update = NO_ACTION
}
}
5.4 column オブジェクト
column は、テーブル内の列を定義するために使用される table のサブリソースです。
column "name" {
type = text
null = false
}
column "age" {
type = integer
default = 42
}
column "active" {
type = tinyint(1)
default = true
}
5.5 primary_keyオブジェクト
primary_keyは、テーブルの主キーを定義するtableのサブリソースです。
primary_key {
columns = [column.id]
}
5.6 foreign_keyオブジェクト
foreign_keyは、他のテーブルの列を参照する列を定義するtableのサブリソースです。
table "orders" {
schema = schema.market
// ...
column "owner_id" {
type = integer
}
foreign_key "owner_id" {
columns = [column.owner_id]
ref_columns = [table.users.column.id]
on_update = NO_ACTION
on_delete = NO_ACTION
}
}
5.7 indexオブジェクト
indexオブジェクトは、テーブルのインデックスを表します。
index "idx_name" {
columns = [
column.name
]
unique = true
}