atlas-postgres

PostgreSQL 向け Atlas

Atlas でスキーマを管理する際の、PostgreSQL 固有の内容について説明します。ワークフローとコマンドについては atlas スキルで扱い、このスキルでは PostgreSQL で異なるルール、エッジケース、回答について扱います。CockroachDB、YugabyteDB、Aurora DSQL などの PostgreSQL 互換エンジンは、一部の点で動作が異なります。各エンジンのガイド（https://atlasgo.io/databases）を参照してください。

ファイル

このスキルは SKILL.md と、references/ にある 7 つのリファレンスファイルで構成されます。各ファイルは https://atlasgo.io/skills/atlas-postgres/references/<name> で提供されています。タスクで必要な場合は、該当するリファレンスを読んでください。

ファイル	参照する内容
references/dev-database.md	開発用 URL とその適用範囲、atlas tool docker、docker ブロックと baseline、拡張機能、RDS、Cloud SQL、Supabase、Neon、Azure、接続 URL
references/security.md	ロールとユーザー、GRANT と REVOKE、ALTER DEFAULT PRIVILEGES、所有権、行レベルセキュリティ、プロバイダーの管理者ロール
references/objects.md	シーケンス、serial 列と identity 列、列挙型、ドメイン、列型の変更、関数、トリガー、ビュー、パーティション、インデックス、Atlas が管理しないもの
references/hcl.md	HCL でのスキーマ記述：NOT NULL のデフォルト、列型と sql()、デフォルト値、参照、キー、インデックス、テーブル設定、関数本体、シードデータ、入力変数
references/migrations.md	ロックと並行インデックス、PG* の lint 検出結果、トランザクション、接続プーラー、ロックを安全に回避する NOT NULL、シードデータ
references/custom-rules.md	チェックをカバーするアナライザーがない場合に、HCL ルール言語でカスタム lint ルールを記述する方法：述語、演算子、各 PostgreSQL オブジェクトが公開する内容、例
references/testing.md	すべての変更のテスト：関数、トリガー、ビュー、ドメイン、ポリシーのスキーマテスト、シード行を使ったマイグレーションテスト、行レベルセキュリティのテスト、テンプレートデータベース、pgTAP

必要条件

このスキルと同じ場所（../atlas/SKILL.md）にインストールされた atlas スキルが必要です。存在しない場合は、 https://atlasgo.io/skills/atlas/SKILL.md を ../atlas/SKILL.md にダウンロードし、「ファイル」セクションに記載された各リファレンスファイルを ../atlas/references/<name> にダウンロードしてください。

ルール

1. 最初に atlas whoami でログイン状態を確認してください。未ログインと表示された場合は、ユーザーに atlas login の実行を依頼してください。 ログアウト状態では、Atlas は PostgreSQL スキーマの大部分を取得できません。ビュー、関数、トリガー、シーケンス、拡張機能、パーティション、ポリシーは検査時に通知なくスキップされ、これらを定義した目標状態は、are available to logged-in users only を含むエラーで失敗します。アカウントを持っていないユーザーは、atlas login で無料トライアルを開始できます。
2. スキーマ内のオブジェクトに応じて、URL のスコープを選択してください。
   • スキーマスコープでは、search_path を含む URL を使用します。Atlas はそのスキーマのみを管理し、修飾されていないステートメント（users）を書き込みます。データベーススコープでは、search_path のない URL を使用します。Atlas はすべてのスキーマを対象とし、各ステートメントを修飾します（public.users）。
   • データベースレベルのオブジェクトは、どのスキーマにも属しません。拡張機能、イベントトリガー、外部サーバーが該当します。スキーマスコープの URL ではこれらは認識されず、エラーなしにプランから除外されるため、これらを宣言するスキーマではデータベーススコープを使用する必要があります。
   • スキーマレベルのオブジェクトは、どちらのスコープでも使用できます。インデックス、制約、トリガー、ポリシーを含むテーブルに加え、ビュー、関数、プロシージャ、シーケンス、型が該当します。
   • ロールとユーザーはクラスターレベルで、インスタンス上のすべてのデータベースで共有されます。これらの管理にはデータベーススコープが必要です（ルール 5）。
   • 開発用 URL には、ターゲットと同じスコープを指定します。スキーマスコープの場合、Docker の開発用 URL では search_path=public を使用します。このスキーマは、ターゲットで指定したスキーマに関係なく、新しいデータベースすべてに存在します。用意する開発用データベースでは、任意の空のスキーマを使用できます。
3. 開発用データベースでは、ターゲットと同じメジャーバージョンと拡張機能を実行します。docker://postgres/<version>/dev。スキーマで使用するものの管理対象ではない拡張機能、プロバイダーのロール、他チームのスキーマなどは、docker ブロックの baseline で作成してください。実環境のデータベースを dev に指定しないでください。
4. 目標状態の ALTER DEFAULT PRIVILEGES は、マイグレーションには反映されません。Atlas はこれを開発用データベースで実行し、対象となるオブジェクトごとに GRANT を 1 つ計画します。対象オブジェクトより前に記述し、FOR ROLE は使用しないでください。
5. ロールの管理には、データベーススコープと mode { roles = true } が必要です。Atlas が変更してはならないロールすべてに external = true を設定し、GRANT の指定先となる外部ロールを開発用の baseline で作成してください。マネージドサービスでは、プロバイダーの管理者ロールを除外します（references/security.md、Managed Providers）。
6. データが格納されたテーブルでインデックスを作成または削除する場合は、並行実行してください。concurrent_index 差分ポリシーを使うか、-- atlas:txmode none で始まる手書きのファイルを使用します。マイグレーションファイルに BEGIN や COMMIT を記述しないでください。txmode none を設定しない限り、Atlas は各ファイルをトランザクション内で実行します。
7. CHECK 制約と外部キーは、まず NOT VALID で追加し、別のトランザクションで検証してください。txmode none のファイルを使うか、後続のファイルで検証します。大きなテーブルでは、ロック安全な NOT NULL ポリシーを使用してください。
8. マイグレーションは直接接続で適用し、トランザクションモードの接続プーラー経由では決して適用しないでください。Supabase のトランザクションプーラー（ポート 6543）、Neon の -pooler エンドポイント、PgBouncer のトランザクションモードなどが該当します。Atlas が実行中に保持するアドバイザリロックはセッション単位ですが、これらのプーラーはロックを解除します。Supabase と Neon はどちらも、マイグレーションには直接接続を使用するよう案内しています。
9. 変更によっては、生成されたマイグレーションを手作業で編集する必要があります（references/objects.md）。
   • PostgreSQL が暗黙的に変換できない型変換（text から integer または uuid など）には、USING 句が必要です。
   • データが格納された列を serial に変換する場合は setval が必要です。そうしないと、挿入時にキーの重複エラーが発生します。
   • serial から bigserial に変換するには、ALTER SEQUENCE ... AS bigint が必要です。そうしないと、シーケンスは 2147483647 で停止したままになります。
   • 新しい enum 値は 1 つのファイルで追加し、その値を初めて使う箇所は後続のファイルに記述します。値の削除や並べ替えには手書きのマイグレーションが必要です。また、プランで変更なしと報告される場合があります。
10. 変更を完了として報告する前に、すべての変更をテストすることを習慣にしてください。atlas schema validate を実行し、追加または変更する関数、トリガー、ビュー、ドメイン、チェック、ポリシーごとに test "schema" ケースを追加してください。また、データを移動または変換する各マイグレーションについて、シード行を使った test "migrate" ケースを追加してください。atlas schema test と atlas migrate test で実行します（references/testing.md）。
11. 組み込みのアナライザーでチェックできない場合は、HCL ルール言語でカスタム lint ルールを作成してください。ユーザーが指定した規約（すべてのテーブルでの行レベルセキュリティや、すべての外部キーへのインデックス設定など）にも同様に対応してください。ルールでは、Atlas が検査する任意のオブジェクトの任意の属性をチェックでき、lint によってすべての変更にそのルールを適用できます（references/custom-rules.md）。

Quick Answers

質問	回答
マイグレーションを適用するためのローカル PostgreSQL データベース	atlas tool docker --url "docker://postgres/17/myapp?search_path=public" --name my-db で URL が表示されます。atlas tool docker kill --name my-db で停止できます（references/dev-database.md）
cannot drop type ... because other objects depend on it が表示される、またはビューや関数がプランに含まれない	atlas whoami を実行してください。ログアウト中は、Atlas はビューや関数をスキップします。型に依存するものも含まれます（ルール 1）
Supabase、Neon、または PgBouncer 経由で使用する Atlas の URL	トランザクションモードのプーラーではなく、直接接続を指定します（references/migrations.md、接続プーラー）
pq: unsupported startup parameter: search_path	URL が PgBouncer 経由になっています。直接接続を使用してください（references/migrations.md、接続プーラー）
マイグレーションに CREATE EXTENSION が含まれない	URL のスコープがスキーマ単位になっています。拡張機能にはデータベース単位のスコープが必要です（references/dev-database.md）
プランで public スキーマが削除される	データベース単位のスコープでは、望ましい状態はすべてのスキーマを対象とします。schema "public" {} を宣言するか、スキーマ単位の URL を使用してください（references/dev-database.md）
cannot diff a schema with a database connection	URL と開発用 URL のスコープが異なります（references/dev-database.md）
connected database is not clean	dev が空でないデータベースを指しています（references/dev-database.md）
すべてのプランで同じ変更が表示される	対象と同じスコープの開発用 URL を設定してください。Atlas はその URL 上で既定値と式を正規化します（references/dev-database.md）
指定していないのに、列が NOT NULL になった	HCL の列は、null = true が設定されていない限り NOT NULL です（references/hcl.md）
text から integer または uuid への ALTER COLUMN ... TYPE が失敗する	マイグレーションファイルに USING 句を追加してください（references/objects.md、列の変更）
列が serial になった後、重複キーエラーで挿入に失敗する	setval でシーケンスを移動してください（references/objects.md）
enum 値を削除したのに、差分に変更が表示されない	enum 値の削除は計画されません。変更を手動で記述してください（references/objects.md、Enum）
unsafe use of new value	enum 値の追加と、その値の最初の使用を別々のマイグレーションファイルに記述してください（references/objects.md、Enum）
pq: type "geometry" does not exist	スキーマ内または開発用の baseline で拡張機能を作成してください。PostGIS イメージだけではインストールされません（references/dev-database.md）
インデックスに対して Lint が PG101 または PG103 を報告する	concurrent_index ポリシーまたは atlas:txmode none を使用してください（references/migrations.md）
行レベルセキュリティや外部キーインデックスなど、すべてのテーブルで守るべき規約がある	カスタム Lint ルールを記述してください（references/custom-rules.md）
行レベルセキュリティのテストが、ポリシーの内容にかかわらず成功する	開発用データベースへの接続にスーパーユーザーを使用しているため、ポリシーがバイパスされています。非特権ロールでテストしてください（references/testing.md）
pq: unexpected transaction status idle	ファイルから BEGIN／COMMIT を削除してください。Atlas はすでにトランザクション内で実行しています（references/migrations.md）
URL のスコープ変更後に ambiguous revision table が表示される	既存のテーブルがあるスキーマを --revisions-schema に設定してください（references/migrations.md）
パーティションテーブルで DROP and CREATE is required が表示される	パーティションキーの変更や、既存テーブルのパーティション化には、手書きのマイグレーションが必要です（references/objects.md）
開発用データベースで ERROR: out of shared memory が表示される	docker ブロックで max_locks_per_transaction を 128 より大きい値にしてください（references/dev-database.md）
マイグレーションにイベントトリガーが含まれない	データベース単位の開発用 URL を使用してください（references/objects.md）
すべてのプランで postgres（Cloud SQL）、RDS マスターユーザー、または別のプロバイダーの管理者ユーザーから権限が取り消される	管理者が通常のロールとして扱われる開発用データベースでプランを作成してください（references/security.md、マネージドプロバイダー）
新しいロールに何千ものテーブルへの SELECT が必要	テーブルごとに権限を付与するのではなく、pg_read_all_data のメンバーにしてください（references/security.md）
開発用データベース上のオブジェクトは postgres が所有しているが、本番環境では別の所有者になっている	所有者は望ましい状態に含まれません（references/security.md、所有権）
マイグレーションに ALTER DEFAULT PRIVILEGES がない	これは想定どおりです。Atlas はオブジェクトごとに、そこから派生する GRANT を計画します（references/security.md）
シーケンスへの権限付与後、bigserial 列が bigint になった	これは想定どおりです。シーケンスが明示的に管理されるようになりました（references/objects.md）

ドキュメント

• PostgreSQL HCL リファレンス：https://atlasgo.io/hcl/postgres
• 開発用データベース：https://atlasgo.io/concepts/dev-database
• セキュリティ：https://atlasgo.io/guides/postgres/security-declarative, https://atlasgo.io/guides/postgres/security-default-privileges
• ロックに安全な変更：https://atlasgo.io/guides/lock-safe-not-null, https://atlasgo.io/lint/analyzers
• 各データベースのガイド：https://atlasgo.io/databases