はじめに
システム移行は、
当日うまくやる作業ではなく、事前準備でほぼ結果が決まる作業です。
- コードは問題ない
- テストも通っている
- それでも本番でトラブルが起きる
こうしたケースの多くは、
移行リハーサル不足、もしくは
移行手順書・レビューの甘さが原因です。
本記事では、実際に手を動かすエンジニア視点で、
本番移行で慌てないために必要な準備をまとめます。
この記事で扱うこと
- なぜ移行リハーサルが重要なのか
- エンジニア向け移行手順書の書き方
- 本番で機能するレビュー観点チェックリスト
システム移行は「コード以外」で壊れる
システム移行は、コードだけの問題ではありません。
- SQL / バッチ / 移行スクリプト
- OS・ミドルウェア・言語バージョン差異
- 設定ファイル（env / yaml / xml）
- 権限、文字コード、タイムゾーン
- 本番データ量による処理時間の変化
つまり、アプリケーションが正しくても失敗する要素が大量にある。
移行リハーサルをしないということは、
これらを本番で初めて実行するということです。
なぜ移行リハーサルが重要なのか（エンジニア視点）
SQL・バッチは本番データ量で豹変する
開発環境では一瞬で終わる処理が、
- データ件数
- インデックス差
- ロック競合
によって、数十分〜数時間かかることは珍しくありません。
これを本番で初めて知ると、
スケジュールも判断も崩れます。
環境差異は「実行」しないと見えない
よくある地雷：
- 本番だけ言語・ミドルウェアのバージョンが違う
- 本番だけ文字コードが違う
- 本番だけファイルパスや権限が違う
これらはコードレビューでは発見できません。
リハーサルで実行して初めて見つかる問題です。
移行リハーサルは手順書のデバッグ工程
リハーサルを行うと、必ず以下が発生します。
- 手順書に書いていない作業が出てくる
- 実際は順番が違うことに気づく
- 人の記憶で補完していた作業が露呈する
つまり、
移行リハーサル = 移行手順書のデバッグです。
エンジニア視点での移行手順書の書き方
移行手順書は「説明資料」ではない
移行手順書は、
本番で見ながらそのまま作業できる設計図であるべきです。
本番移行では、
- 緊張している
- 時間制限がある
- 想定外のエラーが起きる
この前提で書かれていない手順書は、ほぼ機能しません。
① 前提条件・事前確認
最初に「実行してはいけない状態」を明示します。
- 実行環境（本番 / 検証 / DR）
- 実行ユーザー（OS / DB / アプリ）
- サービス停止確認方法
- 実行禁止条件（時間帯・並行作業）
② 全体のタイムライン
細かい手順の前に、全体像を示します。
- 00:00 サービス停止
- 00:10 バックアップ取得
- 00:30 データ移行
- 02:00 動作確認
- 02:30 サービス再開
今どこにいるか分からなくなると、人はミスをします。
③ 手順は「1操作 = 1ステップ」
悪い例：
DBを停止し、バッチを実行して確認する
良い例：
- DBを停止する
- 停止を確認する
- バッチを実行する
細かすぎるくらいでちょうどいいです。
④ コマンドはコピペ前提で書く
- コマンドは省略しない
- オプション含めフル記載
- 実行ディレクトリを明示
cd /opt/app/migration
./migrate.sh --env=prod
⑤ 期待結果を書く
各手順の後に必ず記載します。
- 正常時のログ例
- 件数が一致していること
- 画面・状態の確認方法
次に進んでいいかを自分で判断できる状態を作ります。
⑥ エラー時の分岐を書く
- 続行可能なエラー
- 中断すべきエラー
- 次に取る行動
「エラーが出たら連絡」は、現場では役に立ちません。
⑦ 切り戻し手順
- 移行手順と同じ粒度
- コマンド省略なし
- リハーサルで実行済み
切り戻せない移行は賭けです。
移行手順書 レビュー観点チェックリスト
前提条件
- 実行環境・ユーザーが明確
- 実行禁止条件が定義されている
全体像
- タイムラインがある
- 切り戻し不可ポイントが分かる
手順粒度
- 1手順1操作
- 暗黙知（よしなに・適宜）がない
コマンド
- フル記載されている
- コピペ実行可能
期待結果
- 正常／異常の判断ができる
エラー対応
- エラー時の分岐と行動が明確
切り戻し
- 実行可能な内容になっている
- 切り戻し後の確認手順がある
リハーサル反映
- リハーサル結果が反映されている
- 作業時間の実測値が書かれている
属人性
- 特定の人に依存していない
最終確認
- これを自分が一人で本番実行できるか？
まとめ
- システム移行の成否は事前準備で決まる
- 移行リハーサルはエンジニアのための防具
- 移行手順書はリハーサルで完成する
- レビューは「本番で生き残れるか」を見る
本番移行で慌てないために必要なのは、気合でも経験でもなく、準備の質です。