Amazon Aurora MySQL v1（5.6 互換）→ v3（8.0 互換）移行を計画する（5）Oracle 公式ドキュメントを読む
これは
の続きです。
細部の調査に入る前に考えておくこと
ここからはいよいよ細部に入って行きますが、その前にあらかじめ考えておくべき点があります。
移行の流れ・移行ステップにあわせた調査をする
Aurora MySQL v1 から v3 へ、アップグレードに際して SQL 文の非互換などでアプリケーションを修正するとなれば、以下のような点に気を付ける必要があります。
- Aurora のアップグレードより前に、アプリケーション内の SQL 文を Aurora MySQL v3 で動く状態にしておく必要がある
- 安全に進めるために、修正を Aurora アップグレードと同時にリリースするのではなく、事前に（必要に応じて何度かに分けて）リリースしておくのが良さそう
- そのためには Aurora MySQL v3（MySQL 8.0.23）だけではなく既存の v1（同 5.6.10a）でも動く SQL 文への修正が求められる
- パフォーマンス劣化がないことも必要
- 実行結果やパフォーマンスに問題のない設定（パラメータグループ） の用意が必要
つまり、細部の調査で洗い出す対象は、
- MySQL 5.6.11 から 8.0.23 までの間に動作仕様が変わった機能と削除（廃止）された機能
- その間に追加された機能のうち、既存の機能や SQL 文の実行に影響を与えるもの
が中心となります。
リリースモデルの変更に注意する
ただし Aurora MySQL v3 へのアップグレードでは、もう一点大きな注意点があります。
それは 「MySQL 8.0 でのリリースモデルの変化と Aurora MySQL v3 への影響」 です。
MySQL 8.0 では、GA 後のマイナーバージョンで新規の機能追加や破壊的な動作変更、機能削除（廃止）が行われる方針に変わったため、Aurora MySQL のリリースモデルも v2 までとは違って MySQL 8.0 のマイナーバージョンに追従していくことになりました。
この点を考慮すれば、
- MySQL 8.0.24 以降に動作仕様が変わった機能と削除（廃止）された機能
- MySQL 5.6.11 以降に非推奨（Deprecated）になり、まだ削除（廃止）されていない機能
にも配慮する必要があります。
例えば、以前紹介した サイボウズのブログ記事 でも、現時点の MySQL 8.0 では（非推奨にはなったものの）未削除のSQL_CALC_FOUND_ROWS・FOUND_ROWS()が取り上げられていました。
これらについては、
- Aurora MySQL v1 → v3 移行の準備段階で修正しておく
- Aurora MySQL v1 → v3 移行後に修正する
- とりあえず放置して必要になったら修正する
のうち、どの対応を取るのか決める必要がありますが、調査前に決めるのは難しいケースが多いと思いますので、どの対応になっても良い形で調査記録を残すのが良いでしょう。
結果、非推奨の機能も（非推奨になったバージョンを含めて）記録するのが良さそうです。
Oracle 公式ドキュメントの使い方
ようやく本題です。
以前紹介した公式ドキュメントがいくつかありますが、それぞれの使い方を考えてみましょう。
リリースノート（英語）
マイナーバージョンごとの変更点が記された資料です。
前述の サイボウズのブログ記事 でもリリースノートで変更点を確認していましたが、変更点の網羅性は高いです。
ただし、リリースノートを軸に調査をする場合、
- 分量が多く、全て英語
- Aurora MySQL v1 → v3 アップグレードに関係のない情報も多数含まれる
あたりがネックになりそうです。
リファレンスマニュアル（日本語）
日本語マニュアルについてはこちらもご覧ください。
記事のスクリーンショットにあるとおり、MySQL 8.0.25 までの修正点をベースに作られています。
一見、こちら ↑ のページに MySQL 8.0 の（パラメータ以外の）変更点が網羅されているかのように見えますが、ここには一部しか記載されていません。
変更点を全て知るには、各セクションの情報を読んでいく必要があります。
バージョン間差異のリファレンス（英語）
実は MySQL 8.0 の薄い本 執筆初期にはこのリファレンスには キーワードと予約語 あたりしかなかった気がするのですが、現在
- サーバ変数とオプション（パラメータ）
- オペレータ・ビルトイン関数
INFORMATION_SCHEMAテーブルPERFORMANCE_SCHEMAテーブルsysスキーマテーブル- キーワードと予約語
などについて、MySQL 5.6・5.7・8.0 の差分を見ることができます。
ここに列挙されている項目の変更点を調べるのに非常に役立ちそうです。
ただし、ステートメントの動作の変更点などを見つけるのは困難なので、これだけを頼りに調査を進めると調査漏れが生じそうです。
結局、どう調べる？
- パラメータグループの変更点については、Aurora のパラメータグループ（クラスタ・データベース）に存在する項目だけをバージョン間差異のリファレンス（英語）で確認する
INFORMATION_SCHEMAテーブル・PERFORMANCE_SCHEMAテーブル・sysスキーマテーブルについてもバージョン間差異のリファレンス（英語）で確認する- オペレータ・ビルトイン関数については、一旦バージョン間差異のリファレンス（英語）で確認する
- キーワードと予約語については後述
- あとはリファレンスマニュアルの英語と日本語を切り替えて検索を併用して調査する（後述）
あたりになるでしょうか。
キーワードと予約語の変更をどうするか？
キーワードと予約語については、以下のとおりです。
- 既存の SQL 文のデータベース（スキーマ）名・テーブル名・カラム名等がすべて「`」（半角バッククオート）で括られている場合は対応の必要なし
- 同様に、すべて「データベース名.テーブル名」や「テーブル名.カラム名（インデックス名）」形式で記されている場合も対応の必要なし
- 既存の SQL 文のデータベース（スキーマ）名・テーブル名・カラム名等をすべて「`」で括る（または「.」（ドット）で区切る形式に）修正を行う場合は、ここでの詳細調査を行わない
- これら以外の場合は予約語をバージョン間差異のリファレンス（英語）で確認
- 調査結果をもとに、既存の SQL 文の修正範囲を「全体」にするか「予約語とバッティングする名前のみ」に限定するかを決めることになります
リファレンスマニュアルの英語と日本語を切り替えて使う
MySQL 8.0 の公式マニュアルでは、途中マイナーバージョンでの変更点はバージョン番号とともに記載されています。
そこで「8.0」などのバージョン番号を検索すると、（それ以外のセクション番号などを拾ってしまうケースもありますが）対象ページを探すことができます。
ただし、残念なことに日本語版では正しく機能しません。
そのため、英語版で「8.0」を検索し、読む際に右上のセレクタで日本語に切り替えます。
初期のマイナーバージョンの変更点はこの限りではなかった気がしますので、一応前掲の
にも目を通しておきます。
まとめ
- 調査前に「何を調査対象にすべきか」を検討する
- リリースノート（英語）を読んで確認するのが一番網羅性が高いが、難易度が高い
- そのため、バージョン間差異のリファレンス（英語）とリファレンスマニュアルの英語・日本語切り替えと検索を活用して調査すると良さそう
次回から細部の調査に入っていきますが、調査結果の資料を随時更新していく形になるため、Zenn 記事の追加は不定期になります。
に続きます。
Discussion