🍱

ent. と atlas を利用したスキーマの可視化

2024/01/07に公開

1. はじめに

GolangでORMを使うなら ent. がおすすめ！の記事で、ent.の紹介をした続きになります。
前回は、atlasを利用したスキーマの可視化を省いて説明したので、今回はその紹介になります。
🤔「ent.って何・・・？」という方は、前回の私の記事を読んでいただけると少し分かるかもしれません！（宣伝

2.atlas って何？

atlasは、2021年に設立されたarigaからOSSで提供されている「モダンなDevOps原則に従ったデータベーススキーマの管理とマイグレーションツール」です。

主に、以下の２つの機能を提供してくれます。

Declarative: Terraformと同様、Atlasはデータベースの現在の状態と、HCL、SQL、ORMスキーマで定義された望ましい状態を比較する。この比較に基づいて、データベースを望ましい状態に移行するための移行計画を生成し、実行する。
Versioned: バージョン管理他のツールとは異なり、Atlasは自動的にスキーマのマイグレーションを計画します。ユーザーは、HCL、SQL、または選択したORMで希望のデータベーススキーマを記述し、Atlasを利用することで、必要なマイグレーションを計画し、リントし、データベースに適用することができます。

Key Featuresを見ると色々な機能があり使いこなすのは中々難しいですが、今回はent.のQuick Introductionに記載されているVisualize the Schemaに焦点を当てて利用します。

https://github.com/ariga/atlas

3. 開発環境

以下に、筆者の開発環境と本記事で利用するリポジトリを記載します。

golang v1.21.4
docker 4.16.2
postgresql 16.1
ent. v0.12.5
atlas v0.15.1-04e0010-canary

4. atlasを利用した可視化の方法

ent.のQuick Introdctuionで作成したスキーマを可視化するには、以下の手順に従って下さい。

4-1. atlasのインストール

まずは、atlasのインストールしましょう。
私は以下のようにbrewを利用してインストールしました。

brew install ariga/tap/atlas

brew以外の方法でインストールしたい方は、installationを参照して下さい。

インストールが完了したら、以下のようにコマンドが動作するか確認しておきましょう。

atlas -h

正常にインストールが完了していると、以下のように出力されます。
沢山コマンドがありますが、今回利用するのはschemaコマンドになります。

A database toolkit.

Usage:
  atlas [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  license     Display license information
  login       Log in to Atlas Cloud.
  logout      Logout from Atlas Cloud.
  migrate     Manage versioned migration files
  schema      Work with atlas schemas.
  version     Prints this Atlas CLI version information.

Flags:
  -h, --help   help for atlas

Use "atlas [command] --help" for more information about a command.

4-2. ent.のチュートリアルが完了しているリポジトリを取得

前回の記事でスキーマの定義まで完了しているリポジトリを用意しているので、それを取得して下さい。

git clone git@github.com:KaiTakabe0301/entdemo.git

4-3. スキーマからHCLファイルの作成

atlasでスキーマを可視化するには、hcl形式のファイルかSQL形式のファイルを出力する必要があります。
本節では、hcl形式でファイルを出力することにします。
また、hclのファイル出力方法も複数あるので、ここではそれらの方法も解説します。

4-3-1. Dev Databaseを利用した方法

atlasには、Dev Databaseという機能があります。
これは、atlasに搭載されている特殊なdocker driverを利用することで一時的に検証用のデータベースを立ち上げることができるものです。
これを利用することで、データベースを立ち上げずともHCL形式でスキーマの可視化が可能です。

では、早速Dev Databaseを利用して、スキーマの可視化を行いましょう。
まずは、4-2節で取得したリポジトリに移動して、以下のコマンドを実行して下さい。

atlas schema inspect \
-u "ent://ent/schema" \
--dev-url "docker://postgres/15/dev?search_path=public"

実行結果を記載する前に、簡単にコマンドの説明をしておきます。

atlas schema inspect で、データベースの解析を行いスキーマの可視化を行います
-uオプションで、解析対象のリソースを設定します。
データベースのURLやスキーマのファイルパスをdriver://username:password@address/dbname?param=value設定することができます。
今回はent.のスキーマを設定したかったので、driverにentを指定し、ファイルパスとしてent/schemaを設定しています。
--dev-urlオプションで、Dev Databaseを利用できます。利用できるdriverは、URLsから確認できます。
今回は、docker driverからpostgresqlを利用したかったので"docker://postgres/15/dev?search_path=public"を設定しています。

コマンドが正常に終了すると、スキーマを解析した結果が以下のようにHCL形式で出力されます。

 atlas schema inspect \
  -u "ent://ent/schema" \
  --dev-url "sqlite://file?mode=memory&_fk=1"
  }
  primary_key {
    columns = [column.group_id, column.user_id]
  }
  foreign_key "group_users_group_id" {
    columns     = [column.group_id]
    ref_columns = [table.groups.column.id]
    on_update   = NO_ACTION
    on_delete   = CASCADE
  }
  foreign_key "group_users_user_id" {
    columns     = [column.user_id]
    ref_columns = [table.users.column.id]
    on_update   = NO_ACTION
    on_delete   = CASCADE
  }
}
table "groups" {
  schema = schema.public
  column "id" {
    null = false
    type = bigint
    identity {
      generated = BY_DEFAULT
    }
  }
  column "name" {
    null = false
    type = character_varying
  }
  primary_key {
    columns = [column.id]
  }
}
table "users" {
  schema = schema.public
  column "id" {
    null = false
    type = bigint
    identity {
      generated = BY_DEFAULT
    }
  }
  column "age" {
    null = false
    type = bigint
  }
  column "name" {
    null    = false
    type    = character_varying
    default = "unknown"
  }
  primary_key {
    columns = [column.id]
  }
}
schema "public" {
  comment = "standard public schema"
}

このままだと、HCLファイルは作成されないので通常は以下のように適当なファイルに結果を出力します。

atlas schema inspect \
  -u "ent://ent/schema" \
  --dev-url "docker://postgres/15/dev?search_path=public" > entdemo.hcl

4-3-2. データベースを参照する方法

4-2節で取得したリポジトリに移動して、以下のコマンドを実行してpostgresqlを立ち上げて下さい。

docker-compose up -d

立ち上がったら、go run start.goを実行してデータベースのマイグレーションを行なって下さい。
※チュートリアルを実施済みの方は不要です。

あとは、以下のコマンドを実行して、HCL形式のファイルを作成するだけです。

atlas schema inspect -u "postgres://postgres:password@localhost:5432/entdemo?sslmode=disable" > entdemo.hcl

先ほどと異なり--dev-urlを利用していないことがわかります。

4-4. スキーマの可視化

可視化はいつになったらできるんだよ！？と思っている皆様、やっと可視化の準備が整いました！
可視化の方法も２パターンあるので、それらを順に説明します。

4-4-1. HCLファイルをatlas cloudのExploreに貼り付ける方法

まずは、先ほど保存したentdemo.hclを利用した方法を紹介します。

4-4-1-1. `entdemo.hcl`をクリップボードにコピー

筆者はmacを利用しているので、以下のコマンドでコピーしています。

cat entdemo.hcl | pbcopy

4-4-1-2. atlas cloudにアクセス

コピーが完了したら、atlas cloudのplaygroundにアクセスします。
アクセスすると、こんな画面になっているかと思います。

4-4-1-3. クリップボードの内容をコピーして可視化

以下の画像に従って、クリップボードの内容をコピーして、「Visualize」をクリックして下さい

そうすると、以下の画像のようにスキーマの可視化ができます。
※以下の画像では、外部キーを表現する矢印が見にくかったので位置をずらしています。

4-4-2. `atlas schema inspect`から直接可視化する方法

可視化するだけなら、実はもっと簡単な方法があります・・・
それは、4-3-2項で実行したコマンドを少し弄って、以下のようにします。

atlas schema inspect -u "postgres://postgres:password@localhost:5432/entdemo?sslmode=disable" -w

ファイルの出力をやめた代わりに、-wオプションが付いています。
このオプションを付与して実行すると、以下のようにatlas cloudで公開するか、もしくは個人や組織のworkspaceに出力かを選択できます。

atlas schema inspect -u "postgres://postgres:password@localhost:5432/entdemo?sslmode=disable" -w
? Where would you like to share your schema visualization?:
  ▸ Publicly (gh.atlasgo.cloud)
    Your personal workspace (requires 'atlas login')

現時点では、atlas cloudにアカウントを用意していないので「Publicly」を選択します。
すると、自動的にブラウザが開いて、先ほどと同様の画面が表示されます。
また、この際に公開用のURLも生成されるので、ご注意下さい（私のURLは、 https://gh.atlasgo.cloud/explore/9c90f96c でした）

5. さいごに

本記事では、atlasを用いたスキーマの可視化を説明しました。
ぶっちゃけた話をしてしまえば、これだけの使い方だと機能としては微妙です。
atlasの真価は、マイグレーションのバージョン管理と組み合わせて初めて発揮されます。
次回は、ent.とatlasを用いたマイグレーションのバージョン管理の方法を記事しますので、お付き合い頂けると幸いです！