atlas

Atlas：スキーママイグレーション、データスクリプト、クラウド運用

ファイル

このスキルは SKILL.md と、references/ 以下の9つのリファレンスファイルで構成されています。各ファイルは https://atlasgo.io/skills/atlas/references/<name> で提供されています：schema-sources.md、versioned.md、declarative.md、 cicd.md、lint.md、testing.md、drift.md、cloud.md、scripts.md です。リファレンスは必要なタスクに応じて読み込んでください。「ワークフローの選択」では、どれを読むべきかを説明しています。

セキュリティ

認証情報をハードコードしないでください。atlas.hcl では環境変数を使用してください：

env "prod" {
  url = getenv("DATABASE_URL")
}

データベースのURLを atlas.hcl に保持し、会話に含めないよう、コマンドは必ず --env <name> を指定して実行してください。 まず atlas.hcl を読み、環境名を確認してください。

クイックリファレンス

すべてのドキュメントと使用例を確認するには、任意のコマンドで --help を使用してください：atlas migrate diff --help。

# Setup
atlas version                                        # Installed version
atlas whoami                                         # Login status and org
atlas login                                          # Needed by lint, test, drift, plan, scripts, schema lint, and cloud

# Schema
atlas schema inspect --env <name>                    # Inspect current schema
atlas schema validate --env <name>                   # Validate schema syntax/semantics
atlas schema diff --env <name> --from env://url --to file://schema.hcl   # Live database vs desired schema
atlas schema lint --env <name>                       # Check schema policies
atlas schema test --env <name>                       # Test schema logic

# Declarative workflow
atlas schema plan --env <name>                       # Pre-plan changes for review
atlas schema apply --env <name> --dry-run            # Preview changes
atlas schema apply --env <name>                      # Apply schema changes

# Versioned workflow
atlas migrate diff --env <name> "migration_name"     # Generate migration
atlas migrate lint --env <name> --latest 1           # Lint the newest migration
atlas migrate test --env <name>                      # Test migrations
atlas migrate apply --env <name> --dry-run           # Preview changes
atlas migrate apply --env <name>                     # Apply migration
atlas migrate status --env <name>                    # Live database vs migration directory
atlas migrate down --env <name> --dry-run            # Preview reverting the last migration
atlas migrate hash --env <name>                      # Recompute atlas.sum after manual edits
atlas migrate new --env <name> "name"                # Empty migration file for hand-written SQL
atlas migrate checkpoint --env <name>                # Squash history into a checkpoint file
atlas migrate rebase --env <name> <version>          # Rebase a migration onto newer files
atlas migrate push --env <name>                      # Push the directory to the Atlas Registry

# Linting and testing (see references/lint.md, references/testing.md)
atlas migrate lint --env ci                          # CI: new files vs the registry repo they match
atlas migrate lint --env ci --base atlas://<repo>    # The same, naming the repo: when several match
atlas migrate lint --env ci --git-base master        # No registry: new files vs the base branch
atlas schema lint --env <name>                       # Lint the whole schema against policy
atlas schema test --env <name> --run <case>          # Schema tests: functions, views, triggers
atlas schema plan test --env <name>                  # Test a declarative plan file

# Drift (see references/drift.md)
atlas migrate drift --env <name>                     # Database vs migration history, exit 1 on drift (login)
atlas schema diff --from <url> --to <url> --dev-url <dev>   # Any two states

# Atlas Cloud (see references/cloud.md)
atlas cloud repo list                                # Registry repos with synced/failed/pending counts
atlas cloud database list --env-name <env>           # Every tracked database and its status
atlas cloud migration list --status FAILED           # Failed deployments
atlas schema plan list --env <name> --pending        # Plans waiting for approval

# Data Scripts (see references/scripts.md)
atlas script exec  --env <name> --run '^name$'       # Transactional mutation
atlas script query --env <name> --run '^name$' -q    # Read or report
atlas script loop  --env <name> --run '^name$'       # Batched backfill or purge
atlas script test  --env <name>                      # Test scripts on the dev database

ワークフローの選択

What is the request?
├─ A schema change
│  ├─ Project has migrations/ dir or a migration block in atlas.hcl?
│  │  ├─ Yes → Versioned: migrate diff → lint → test → apply   (references/versioned.md)
│  │  └─ No  → Declarative: schema apply --dry-run → apply     (references/declarative.md)
│  ├─ Change must be reviewed and approved before it runs?
│  │  └─ schema plan (declarative) or a PR with migrate lint (versioned)
│  ├─ Iterating on a local database?
│  │  └─ schema apply --auto-approve for fast edit-apply cycles
│  └─ Not sure → Read atlas.hcl first
├─ CI/CD: lint on PRs, push to the registry, deploy from it
│  └─ references/cicd.md (each step's inputs and errors on each platform: the atlas-action skill)
├─ A data change (backfill, purge, report, invariant check)
│  └─ Data Scripts: references/scripts.md
├─ A lint failure, a lint policy, or a custom rule
│  └─ references/lint.md
├─ Tests for functions, views, triggers, data migrations, or plans
│  └─ references/testing.md
├─ "Has this database drifted?" or a drift check for deploys
│  └─ references/drift.md
├─ A question about deployments, database status, or the registry
│  └─ Atlas Cloud: references/cloud.md
└─ ORM or schema source setup
   └─ references/schema-sources.md

atlas schema apply は、マイグレーションファイルを使わずにデータベースへスキーマ変更を直接適用します。開発中の迅速な反復に使用します。スキーマを編集し、schema apply を実行して結果を確認してください。

例

バージョン管理プロジェクト（atlas.hcl に migration ブロックがある場合）：

User: Add an email column to the users table

Agent steps:
1. atlas schema inspect --env dev           # understand current state
2. Edit schema source file                  # add email column
3. atlas schema validate --env dev          # verify syntax
4. atlas migrate diff --env dev "add_users_email"  # generate migration
5. atlas migrate lint --env dev --latest 1  # check for issues
6. atlas migrate apply --env dev --dry-run  # preview before applying

宣言型プロジェクト（schema ブロックがあり、マイグレーションディレクトリがない場合）：

Agent steps:
1. Edit schema source file                  # add email column
2. atlas schema validate --env dev          # verify syntax
3. atlas schema apply --env dev --dry-run   # read the planned SQL to the user
4. atlas schema apply --env dev             # apply (or --auto-approve on a local database)

コアコンセプト

設定ファイル（atlas.hcl）

必ず最初にプロジェクトの atlas.hcl を読んでください。環境設定が含まれています：

env "<name>" {
  url = getenv("DATABASE_URL")
  dev = "docker://postgres/17/dev?search_path=public"

  migration {
    dir = "file://migrations"       # or "atlas://<repo>" for the Atlas Registry
  }

  schema {
    src = "file://schema.hcl"
  }

  script {
    src = "file://scripts"          # Data Scripts source
  }
}

開発用データベース

Atlas は、スキーマの処理と検証に一時的な開発用データベースを使用します。URLのスコープはターゲットに合わせる必要があります。プロジェクトが単一のスキーマを管理する場合はスキーマスコープ、複数のスキーマ、拡張機能、イベントトリガーを管理する場合はデータベーススコープを指定してください。

# Schema-scoped (single schema, most common)
--dev-url "docker://mysql/8/dev"
--dev-url "docker://postgres/17/dev?search_path=public"
--dev-url "sqlite://dev?mode=memory"
--dev-url "docker://sqlserver/2022-latest/dev?mode=schema"

# Database-scoped (multiple schemas, extensions, or event triggers)
--dev-url "docker://mysql/8"
--dev-url "docker://postgres/17/dev"
--dev-url "docker://sqlserver/2022-latest/dev?mode=database"

誤ったスコープを指定すると、modify schema "public" is not allowed when migration plan is scoped to one schema のようなエラーが発生したり、データベースレベルのオブジェクト（拡張機能、イベントトリガー）がマイグレーションから暗黙的に削除されたりします。PostGIS または pgvector のスキーマには、docker://postgis/latest/dev または docker://pgvector/pg17/dev を使用してください。

スキーマが拡張機能や外部オブジェクトに依存する場合は、baseline を含む docker ブロックを使用してください：

docker "postgres" "dev" {
  image  = "postgres:17"
  schema = "public"
  baseline = <<SQL
   CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
  SQL
}

env "local" {
  src = "file://schema.hcl"
  dev = docker.postgres.dev.url
}

ワークフロー

1. スキーマの調査

詳細に進む前に、概要を確認してください。デフォルトの出力形式はHCLです。JSONには --format "{{ json . }}"、SQLには --format "{{ sql . }}" を使用してください。

# List tables (overview first, JSON output)
atlas schema inspect --env <name> --format "{{ json . }}" | jq ".schemas[].tables[].name"

# Full SQL schema
atlas schema inspect --env <name> --format "{{ sql . }}"

# Filter with --include/--exclude (useful for large schemas)
atlas schema inspect --env <name> --include "users_*"           # Only matching tables (needs atlas login)
atlas schema inspect --env <name> --exclude "*_backup"          # Skip matching tables
atlas schema inspect --env <name> --exclude "*.*[type=trigger]" # Skip triggers (database scope: "*.*.*[type=trigger]")

# Open a visual ERD in the browser (requires atlas login)
atlas schema inspect --env <name> -w

2. スキーマの比較（差分）

# Live database vs desired schema. --from and --to are always required; --env supplies the dev database.
# env://url reads the env's url so the database URL never appears on the command line.
# On a versioned database add --exclude atlas_schema_revisions, or the revisions table shows up as a drop.
atlas schema diff --env <name> --from env://url --to file://schema.hcl --exclude atlas_schema_revisions

# Compare specific sources
atlas schema diff --env <name> --from file://migrations --to file://schema.hcl

3. マイグレーションの生成

# Generate a migration from the schema diff
atlas migrate diff --env <name> "add_users_table"

# With explicit parameters
atlas migrate diff \
  --dir file://migrations \
  --dev-url docker://postgres/17/dev \
  --to file://schema.hcl \
  "add_users_table"

4. スキーマの検証

スキーマ定義は、編集のたびに、またマイグレーションの生成前に検証してください：

atlas schema validate --env <name>
atlas schema validate --dev-url docker://postgres/17/dev --url file://schema.hcl

有効な場合、コマンドは正常終了します。無効な場合は、エラー（未解決の参照、構文の問題、サポートされていない属性）が出力されます。

5. マイグレーションのLint

atlas migrate lint --env <name> --latest 1    # Lint the latest migration
atlas migrate lint --env ci                   # CI: new files vs the registry (no registry: --git-base master)
atlas schema lint --env <name>                # Check the whole schema against policy

アナライザーは、破壊的な変更（DS*）、データに依存する変更（MF*）、後方互換性のない変更（BC*）、テーブルロックや再書き込み（MY*、PG*）、命名および所有権のポリシー、HCLで記述されたカスタムルールを検出します。ポリシーは atlas.hcl の lint ブロックに記述します。

Lintの問題を修正する方法：

• 未適用のマイグレーション：ファイルを編集し、atlas migrate hash --env <name> を実行します。
• 適用済みのマイグレーション：修正用のマイグレーションを作成します。適用済みのマイグレーションは編集しないでください。
• -- atlas:nolint <code> は、ユーザーの承認がある場合にのみ使用してください。

コード、ポリシー設定、カスタムルールについては、references/lint.md を参照してください。

6. テスト

atlas schema test --env <name>                # Functions, views, triggers, constraints, queries
atlas migrate test --env <name>               # Data migrations between versions
atlas schema plan test --env <name>           # Declarative plan files
atlas script test --env <name>                # Data Scripts

テストはHCLのケース（test "schema" "<name>" { exec, catch, assert, ... }）で、開発用データベースに対して実行されます。追加する関数、ビュー、トリガー、データマイグレーションごとにテストを作成してください。ブロック構文、環境設定、修正の反復については、references/testing.md を参照してください。

7. マイグレーションの適用

atlas migrate apply --env <name> --dry-run    # Always preview first
atlas migrate apply --env <name>              # Apply
atlas migrate status --env <name>             # Verify

共有環境または本番環境に適用する前に、まずAtlas Cloudの状態を確認してください（同じターゲットで失敗中または実行中のデプロイがないか）。適用前チェックリストについては、references/cloud.md を参照してください。

8. 宣言型プランと承認

宣言型ワークフローでは、atlas schema plan によってマイグレーションプランを Atlas Registry に保存し、atlas schema apply で実行する前にレビューと承認を行えます。

atlas schema plan --env <name>                        # Plan, lint, review, approve and push
atlas schema plan --env <name> --pending              # Push for someone else to approve
atlas schema plan list --env <name> --pending         # Plans waiting for approval
atlas schema plan approve --url "atlas://<repo>/plans/<name>"
atlas schema apply --env <name>                       # Applies the approved plan as-is

プランの編集、push、pull、lint、validate、レビューポリシー、schema push については、references/declarative.md を参照してください。マイグレーションディレクトリの形式、差分ポリシー、ベースライン、down、checkpoint、rebase、実行前チェック、マルチテナントへの適用については、references/versioned.md を参照してください。

9. CI/CD

プルリクエストで lint（またはプランを作成）し、マージ時にディレクトリまたはスキーマを Atlas Registry に push して、ドリフト検出と実行前チェックを行いながら atlas://<repo> からデプロイします。GitHub Actions のワークフロー、および GitLab、CircleCI、Bitbucket、Azure DevOps、Kubernetes、Terraform 向けの同等の手順については、references/cicd.md を参照してください。各ステップの入力、出力、トークン、権限、失敗メッセージについては、atlas-action スキル（https://atlasgo.io/guides/ai-tools/agent-skills#cicd-skill）を参照してください。

標準ワークフロー

1. atlas schema inspect --env <name>：現在の状態を把握します（データベースが空の場合は省略します）
2. スキーマファイルを編集します
3. atlas schema validate --env <name>：構文をチェックします
4. atlas migrate diff --env <name> "change_name"：マイグレーションを生成します
5. atlas migrate lint --env <name> --latest 1：検証します（ログインが必要です）
6. atlas migrate test --env <name>：テストします（ログインが必要です）
7. 問題がある場合：マイグレーションを編集してから、atlas migrate hash を実行します
8. atlas migrate apply --env <name> --dry-run を実行してから、適用します

既存のデータベースを調査、差分生成、またはベースライン化する前に atlas whoami を実行し、失敗した場合はユーザーにログインを依頼してください。ログアウト状態では、atlas schema inspect と atlas schema diff はビュー、関数、プロシージャ、トリガー、シーケンス、拡張機能、その他のオブジェクトを省略しながら終了コード 0 を返すため、実際には不完全でも出力が完全に見えてしまいます。

ログインが必要なその他のコマンドは、command requires 'atlas login' または available only to Atlas Pro users というエラーで失敗します。そのステップを省略したこととその理由をユーザーに伝え、残りのステップを続行してください。

ドリフト検出

ドリフトとは、データベースと信頼できる情報源との間の差異です。質問ごとに 1 つずつ、4 つのツールを使います。

質問	ツール
このデータベースは、現在またはスケジュール実行時にマイグレーション履歴と一致していますか？	atlas migrate drift --env <name>（ドリフトがある場合は終了コード 1、cron に適しています。atlas login が必要です）
ターゲットにドリフトがある場合にデプロイをブロックする	atlas.hcl の check "migrate_apply" { drift { on_error = FAIL } }
2 つの状態の差異（宣言型、またはデータベース間）を確認するには？	atlas schema diff --from <url> --to <url>（両方のフラグが必要です）
アラート付きのエージェントベースの継続的な監視	Atlas Cloud の Schema Monitoring

コマンド、フラグ、exclude パターン、レポート作成ワークフローについては、references/drift.md を参照してください。

Atlas Cloud

atlas cloud コマンドでは、Atlas Cloud が把握している情報を確認できます。レジストリのリポジトリ、同期状態（SYNCED、PENDING、FAILED）と現在のバージョンを含む追跡対象の各データベース、各デプロイイベント（PASSED、FAILED、NO_ACTION、DRY_RUN）が対象です。運用に関する質問への回答に使用します。

質問	コマンド
データベースインフラストラクチャの概要を確認する	atlas cloud repo list を実行し、次に環境ごとに atlas cloud database list を実行します
失敗したデプロイはどれですか？	atlas cloud migration list --status FAILED
デプロイで何が起きましたか？	atlas cloud migration describe --id <id>
デプロイを待っているデータベースはどれですか？	atlas cloud database list を実行し、Status=PENDING で絞り込みます
承認待ちのプランはどれですか？	atlas schema plan list --env <name> --pending
本番環境のバージョンはいくつですか？	atlas cloud database list --env-name prod

コマンドの完全なリファレンス、レポートテンプレート、判断ルールについては、references/cloud.md を参照してください。

データスクリプト

atlas script は HCL で記述されたデータ操作を実行します。トランザクションを伴う変更には exec、読み取りやレポートには query、バッチ処理によるバックフィルやパージには loop を使用し、condition ガード、assert チェック、expect_rows、出力のマスキング、テストにも対応しています。データ操作にはスクリプトを、スキーマ操作にはマイグレーションを使用してください。完全なリファレンスについては、references/scripts.md を参照してください。

スキーマソース

HCL スキーマ、ORM 連携（GORM、Drizzle、SQLAlchemy、Django、Ent、Sequelize、TypeORM）、複合スキーマ、開発データベースの方言 URL については、references/schema-sources.md を参照してください。

既存プロジェクトのオンボーディング

プロジェクトやチーム全体を対象とするガイド付きオンボーディング（棚卸し、大規模データベースのユニットへの分割、CI、デプロイ。各段階で検証を実施）には、ユーザーは atlas-onboard スキル （https://atlasgo.io/guides/ai-tools/agent-skills#onboarding-skill）を実行できます。

バージョン管理されたマイグレーションで既存のデータベースの管理を開始するには、まずログインしてください。ログアウトした状態で inspect を実行すると、エラーなしにビュー、関数、トリガー、その他のオブジェクトがベースラインから除外されます。次に、atlas.hcl で組織を固定します。これにより、後でこのファイルを読み取るコマンド（--env）は、その組織にログインしているユーザーがいない場合に中止されます。--url を直接指定するコマンドはこのファイルを読み取らないため、その前に atlas whoami を実行してください。

atlas {
  cloud {
    org = "<org printed by atlas whoami>"
  }
}

# 1. Export the current schema to code
atlas schema inspect --env <name> --format '{{ sql . | split | write "src" }}'

# 2. Generate a baseline migration from the exported schema
atlas migrate diff --env <name> "baseline" --to "file://src"

# 3. Record the baseline as applied on each existing database (the version from the filename).
#    Deploy envs can set baseline = "<version>" in their migration block instead.
#    Preview first; --dry-run writes nothing:
atlas migrate apply --env <name> --baseline '<version>' --dry-run
#    Then, only after the user approves the named target, record it (this writes the revisions table):
atlas migrate apply --env <name> --baseline '<version>'

ベースラインマイグレーションは、既存のデータベースでは実行せずに現在の状態を記録します。新しいデータベースでは、初期スキーマを作成するために全体が実行されます。

トラブルシューティング

atlas version                                 # Check installation
atlas whoami                                  # Check login and org
atlas migrate hash --env <name>               # Repair migration integrity after manual edits

• command requires 'atlas login' または available only to Atlas Pro users：このコマンドにはログインが必要です。atlas login を実行するか、CI では atlas login --token "$ATLAS_TOKEN" を実行してください。スキップした手順を報告し、続行してください。
• 'atlas login' is required for organization <org> as specified in atlas.hcl：このプロジェクトでは組織が固定されています。ユーザーに、その組織のアカウントで atlas login を実行するよう依頼してください。
• ドライバーが見つからないというエラー：--url または --dev-url が正しく指定されていることを確認してください。
• add、drop、または modify schema "<name>" is not allowed when migration plan is scoped to one schema：開発 URL のスコープが対象と一致していません。上記の「開発データベース」を参照してください。
• migrate lint が Multiple directories found. Select one to lint against と表示し、CI で Error: ^D により失敗する場合：ローカルディレクトリに一致するレジストリリポジトリが複数あります。--base atlas://<repo> を指定してください。
• missing data source handler for "<name>"、またはドキュメントに記載されたコマンドが親コマンドの使用方法だけを表示する場合（例：atlas migrate drift）：インストールされている Atlas ではその機能を利用できません（古いリリースまたは Community Edition のビルド）。あるいは、データソースの種類に誤記があります。不明なデータソースがあると、それを参照していない環境も含め、ファイル内のすべての環境で失敗します。種類が https://atlasgo.io/atlas-schema/projects#data-sources の記載と一致することを確認し、atlas version を実行して、最新リリース（https://atlasgo.io/getting-started#step-1-install-atlas）をインストールしてください。
• Call to unknown function：atlas.hcl で使用できるのは file、fileset、getenv と、https://atlasgo.io/hcl/functions に記載された関数です。coalesce はありません。
• docker:// 開発 URL でコンテナが起動した後、dial tcp <address>: connect: connection refused により失敗する場合：Atlas は、devcontainer など、ホストの Docker デーモンを使用するコンテナ内で実行されていますが、デーモンが公開したポートに接続できません。開発データベースのコンテナを自分で起動し、コンテナから到達できるアドレス（Docker ネットワーク上の IP など）の URL を dev に設定してください（https://atlasgo.io/faq/docker-in-docker）。

主なルール

1. まず atlas.hcl を読み、そこに記載された環境名を使用します。
2. 認証情報をハードコードしないでください。getenv() と --env を使用します。
3. スキーマを編集した後は、atlas schema validate を実行します。
4. マイグレーションを適用する前に、必ずリントします。
5. 適用する前に、必ずドライランを実行します。
6. マイグレーションファイルを編集した後は、atlas migrate hash を実行します。
7. 適用済みのマイグレーションは編集しないでください。代わりに修正用のマイグレーションを作成します。
8. リントエラーを無視しないでください。修正するか、ユーザーから明示的な承認を得ます。
9. マシンごとに一度 atlas login を実行します。リント、テスト、ドリフト検出、schema plan、レビューポリシー、 スクリプト、ERD、migrate checkpoint、schema inspect --include、Atlas Cloud にはログインが必要で、未ログインの場合は失敗します。その場合は、 スキップした手順を報告して続行します。 ログインしていなくても、データベースの検査と差分の確認は失敗せず、一部のオブジェクトがスキップされます。どちらも実行前にログインしてください。 アカウントを持っていないユーザーは、atlas login で無料トライアルを開始できます。
10. 共有環境にデプロイする前に、Atlas Cloud で FAILED または PENDING のターゲットと、最近失敗したデプロイを確認します （references/cloud.md）。
11. データ変更にはアドホック SQL ではなく、Data Scripts を使用します。condition で条件を指定し、結果をアサートして、レポート内の PII をマスキングします（references/scripts.md）。
12. クラウドの状態と稼働中のデータベースの状態は、別々に報告します。atlas cloud は Atlas Cloud が把握している状態を示し、atlas migrate status はデータベース内の状態を示します。

ドキュメント

• CLI リファレンス
• バージョン管理されたマイグレーション
• 宣言型ワークフロー
• 宣言型の計画と承認
• バージョン管理された CI/CD のセットアップ
• 宣言型 CI/CD のセットアップ
• GitHub Actions
• マイグレーションのリント
• リントアナライザー
• カスタムリントルール
• スキーマテスト
• マイグレーションテスト
• ドリフト検出
• スキーマのモニタリング
• Data Scripts
• Atlas Cloud のデプロイ
• 既存のデータベースのオンボーディング
• ORM インテグレーション
• 開発用データベース