atlas-mysql

MySQL 向け Atlas

Atlas がスキーマを管理する際の、MySQL と MariaDB に固有の事項を説明します。atlas スキルではワークフローとコマンドを扱い、このスキルでは MySQL で異なるルール、エッジケース、回答を扱います。MariaDB については、異なる点を取り上げます。TiDB、PlanetScale、SingleStore などの MySQL 互換エンジンは対象外です。

ファイル

このスキルは SKILL.md と、references/ 配下にある 7 つのリファレンスファイルで構成されており、それぞれ以下の URL から参照できます。 https://atlasgo.io/skills/atlas-mysql/references/<name>。タスクで必要なリファレンスをお読みください。

ファイル	参照する内容
references/dev-database.md	dev URL とその適用範囲、atlas tool docker、docker ブロック、文字セットと照合順序、RDS、Cloud SQL、Azure、MariaDB、接続 URL
references/security.md	ユーザーとロール、ホスト、GRANT と REVOKE、パスワード、ロールの有効化
references/objects.md	ログインが必要なオブジェクト、列挙型とセット、外部キーのインデックス、チェック、生成列、関数とトリガー、正規化された定義、MariaDB
references/hcl.md	HCL でのスキーマの記述：NOT NULL のデフォルト、デフォルト値と ON UPDATE、AUTO_INCREMENT、型、インデックス、エンジン、パーティション、ビュー、ルーチン、シードデータ
references/migrations.md	MY* の lint 検出項目、テーブルのコピー、部分的な失敗と復旧、区切り文字、ロック、リビジョンテーブル、ベースライン
references/testing.md	すべての変更のテスト：スキーマテスト、シード行を使ったマイグレーションテスト、CI
references/custom-rules.md	どのアナライザーでもチェックできない場合に、HCL ルール言語でカスタム lint ルールを作成する方法：述語、演算子、各 MySQL オブジェクトが公開する情報、例

必要なもの

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

ルール

1. まず atlas whoami でログイン状態を確認します。ログインしていない場合は、ユーザーに atlas login を実行するよう依頼してください： ログアウト状態では、Atlas はビュー、トリガー、ストアドプロシージャ、関数、パーティション、ユーザー、 および権限を把握できません。アカウントを持っていないユーザーは、atlas login で無料トライアルを開始できます。
2. スキーマの内容に応じて、URL のスコープを選びます：
   • MySQL では、スキーマはデータベースです。スキーマスコープは、パスにデータベースを含む URL を使い、Atlas は そのデータベースを管理して、修飾なしのステートメント（users）を書き込みます。サーバースコープは、パスにデータベースを含めず、 Atlas がすべてのデータベースを対象にして、各ステートメントを修飾します（app.users）。
   • ユーザーとロールはサーバーに属するため、それらを管理するにはサーバースコープが必要です。複数の データベースや、データベース間の外部キーを扱う場合も同様です。
   • サーバースコープでは、希望する状態で宣言されていないデータベースは、DROP DATABASE の対象として計画されます。
   • 開発用 URL には、ターゲットと同じスコープを指定します：docker://mysql/8/dev または docker://mysql/8。
3. 開発用データベースでは、ターゲットと同じバージョンおよび設定（文字セットと照合順序、 lower_case_table_names、sql_mode、explicit_defaults_for_timestamp）を使用します。docker ブロックで イメージを固定し（image = "mysql:8.4"）、ターゲットの設定でサーバーを起動します（command）。 MariaDB の場合は、開発用データベースにも MariaDB を使います。RDS では、IAM ユーザーを作成する マイグレーション（IDENTIFIED WITH AWSAuthenticationPlugin）に、そのプラグインをモックした開発用イメージが必要です （references/dev-database.md）。dev を実環境のデータベースに接続しないでください。
4. すべての schema ブロックで charset と collate を宣言します。そうしないと、希望する状態には開発用 サーバーのデフォルト（MySQL 8 では utf8mb4_0900_ai_ci）が使用され、他のデフォルトを使うターゲットに対する スキーマスコープの計画が modify schema エラーで失敗します（references/dev-database.md）。
5. ユーザーとロールの管理には、サーバースコープと mode { roles = true } が必要です。MySQL には external 属性がないため、宣言されていないアカウントは、Atlas の接続に使うユーザーも含めて、削除対象として計画されます： そのユーザーを宣言し、最初の計画でほかのアカウントを確認してから、skip 差分ポリシーで drop_user と drop_role を設定し、計画から削除を除外します。付与されたロールは、SET DEFAULT ROLE の後にのみ有効になります （references/security.md）。
6. MySQL と MariaDB にはトランザクション DDL がありません。各 DDL ステートメントは個別にコミットされるため、 マイグレーションファイルまたは計画が途中で失敗すると、適用も途中の状態になり、--tx-mode でも防げません。 ファイルを小さく保ち、適用前にテストしてください（ルール 9）。復旧するには、失敗したステートメントとその後の ステートメントを修正して atlas migrate hash を実行するか、適用済みのステートメントを atlas migrate down で取り消します （references/migrations.md）。
7. 大きなテーブルに対する変更を適用する前に、すべての MY1* リント検出結果を確認します。こうした変更は テーブルをコピーまたは再構築するか、書き込みをブロックします。enum と set の値は末尾に追加し、生成列には VIRTUAL を優先して使い、engine の編集内容を確認します（references/migrations.md）。
8. 常に開発用 URL を指定して計画します。指定しない場合、Atlas は _utf8mb4 導入句など、MySQL が書き換えた定義を比較し、 外部キー用に MySQL が作成したインデックスを削除する計画を立てることがあります （references/objects.md）。
9. 変更を完了したと報告する前に、習慣として必ずテストします。atlas schema validate を実行し、追加または変更する 関数、プロシージャ、トリガー、ビュー、生成列、チェックごとに test "schema" ケースを追加します。また、データを 移動または変換するマイグレーションごとに、シード行を使った test "migrate" ケースを追加します。 atlas schema test と atlas migrate test で実行します（references/testing.md）。
10. 組み込みアナライザーでチェックできない場合は、HCL ルール言語でカスタムリントルールを記述します。許可する文字セットや 決定的関数など、ユーザーが指定した規約についても同様です。ルールでは、Atlas が調査する任意のオブジェクトの 任意の属性をチェックでき、リントによってすべての変更に適用されます（references/custom-rules.md）。

よくある質問への簡単な回答

質問	回答
マイグレーションを適用するローカル MySQL データベース	atlas tool docker --url "docker://mysql/8/myapp" --name my-db で URL が出力されます。atlas tool docker kill --name my-db で停止します（references/dev-database.md）
modify schema "..." is not allowed when migration plan is scoped to one schema	開発用データベースの文字セット、照合順序、またはコメントがターゲットと異なります（references/dev-database.md）
すべてのテーブルで文字セットまたは照合順序の変更が表示される	開発サーバーのデフォルト設定が期待する状態に反映されています。スキーマで明示するか、開発サーバーをターゲットに合わせてください（references/dev-database.md）
_latin1 または _utf8mb4 だけが異なるドリフト	command を使って、ターゲットの文字セットで開発サーバーを起動してください（references/dev-database.md）
テーブル名が変更として表示され続ける	開発サーバーの lower_case_table_names がターゲットと異なります（references/dev-database.md、サーバーバージョンと設定）
プランが他のデータベースを削除する（DROP DATABASE）	サーバースコープではすべてのデータベースが対象になります。--schema で実行範囲を制限するか、スキーマスコープを使ってください（references/dev-database.md）
Error 1046: No database selected	スキーマスコープのプランをサーバースコープの URL で適用しています（references/dev-database.md）
cannot use HCL with more than 1 schema when dev-url is limited to schema	サーバースコープの開発用 URL docker://mysql/8 を使ってください（references/dev-database.md）
マイグレーションが途中で失敗し、migrate status に (last one partially) と表示される	MySQL は失敗前のステートメントを保持しています。残りを修正して atlas migrate hash を実行するか、atlas migrate down で取り消してください（references/migrations.md）
名前変更が削除と追加として表示される	renamed_from で宣言してください。そうしないとデータが失われます（references/hcl.md）
lint で MY1* チェックが報告される	変更によってテーブルがコピーまたは再構築されるか、書き込みがブロックされます。コピーを避けるには、手書きのファイルで ALGORITHM=INSTANT を強制するか、オンラインスキーマ変更ツールを使ってください（references/migrations.md、テーブルのコピー）
Error 1553 (HY000): Cannot drop index ...: needed in a foreign key constraint	開発用 URL でプランを作成するか、外部キーのインデックスを宣言してください（references/objects.md）
検査やプランに外部キーが一切表示されない	テーブルで MyISAM が使われており、外部キーが無視されています。InnoDB を使ってください（references/objects.md）
Error 1418 (HY000): This function has none of DETERMINISTIC, NO SQL, or READS SQL DATA ...	deterministic または data_access を設定するか、log_bin_trust_function_creators を有効にしてください（references/objects.md）
enum 値の削除に失敗する、または行が '' になる	厳格な sql_mode では、その値を保持する行があると失敗し、非厳格モードでは値が空になります。先に該当する行を更新してください（references/objects.md）
Error 1826 または Error 3822、制約名の重複	外部キー名と check 名はテーブル単位ではなく、データベース単位で一意です（references/objects.md）
Error 1059 (42000): Identifier name ... is too long	名前は 64 文字までです。インデックス名または制約名を明示的に指定してください（references/objects.md）
RDS で DEFINER 句に対して Error 1227 (42000): Access denied が発生する	マイグレーションファイルから DEFINER 句を削除してください（references/objects.md）
ビューの読み込み時に Error 1146 (42S02): Table ... doesn't exist が発生する	ビューが別のデータベースを参照しています。開発用 baseline で作成するか、サーバースコープを使ってください（references/objects.md）
IDENTIFIED WITH mysql_native_password が開発用データベースで失敗する	MySQL 8.4 ではこのプラグインが無効になり、9.0 では削除されています。ターゲットと同じバージョンで開発用データベースを実行してください（references/dev-database.md）
タイムスタンプで Error 1067: Invalid default value が発生する	カラムの精度に合わせて、デフォルト値を sql("current_timestamp(6)") と記述してください（references/hcl.md）
指定していないのにカラムが NOT NULL になった	HCL のカラムは null = true を設定しない限り NOT NULL です（references/hcl.md）
ERROR 1170 (42000): BLOB/TEXT column ... used in key specification without a key length	インデックス要素に prefix を指定してください（references/hcl.md）
スキーマで宣言していないユーザーまたはロールが削除対象としてプランされる	それらを宣言するか、drop_user と drop_role で削除をスキップしてください（references/security.md）
付与されたロールが反映されない	MySQL では SET DEFAULT ROLE ALL TO 'user'@'host' を実行するか、activate_all_roles_on_login を有効にしてください。MariaDB では、ユーザーが持てるデフォルトロールは 1 つです。SET DEFAULT ROLE <role> FOR 'user'@'host' を実行してください（references/security.md）
RDS IAM ユーザーを作成するマイグレーションで Error 1524 (HY000): Plugin 'AWSAuthenticationPlugin' is not loaded が発生する	プラグインのモックを使って開発用イメージをビルドし、atlas tool docker --env <env> でローカルデータベースを起動してください（references/dev-database.md、開発用データベースでの RDS IAM ユーザー）
invalid port ":..." after host	パスワードをパーセントエンコードするか、urlescape で URL を組み立ててください（references/dev-database.md）
server does not allow insecure connections, client must use SSL/TLS	URL に ?tls=true を追加してください（references/dev-database.md）
同じサーバー上のデータベースで並列適用されない	デフォルトのロック名を共有しています。ターゲットごとに lock_name を設定してください（references/migrations.md）

ドキュメント

• MySQL HCL リファレンス：https://atlasgo.io/hcl/mysql、MariaDB 用：https://atlasgo.io/hcl/mariadb
• 開発用データベース：https://atlasgo.io/concepts/dev-database
• セキュリティ：https://atlasgo.io/guides/mysql/security-declarative、 https://atlasgo.io/guides/mysql/security-versioned
• リントチェック：https://atlasgo.io/lint/analyzers
• 各データベースのガイド：https://atlasgo.io/databases