Docker 開発環境: MySQL 5.7 から 8.0 への移行手順 - opensource-workshop/connect-cms GitHub Wiki

背景

docker-compose.yml の更新 #2289により、開発用データベースコンテナが MySQL 5.7 から 8.0 ベースのイメージに切り替わります。
既存の docker/db/mysql_data ディレクトリをそのままマウントすると MySQL 8.0 の起動時に失敗し、環境全体が立ち上がらなくなるため、事前にデータのバックアップとディレクトリの移行作業が必要です。

対象環境

  • Connect-CMS 開発用 Docker Compose スタック（従来の app / db / mailhog 構成）
  • docker/db/mysql_data に MySQL 5.7 の永続化データが残っている場合

作業の流れ

  1. MySQL 5.7 コンテナを起動したまま、必要なデータをダンプする
  2. コンテナを停止し、旧データディレクトリを退避または削除する
  3. 新しい docker-compose.yml を適用して MySQL 8.0 を初期化する
  4. 必要に応じてバックアップをリストアする

以下では docker compose を利用した例を記載しています。古いバージョンの Docker Compose をお使いの場合は docker-compose に読み替えてください。

1. バックアップを取得する

# 任意のバックアップ保存先を作成
mkdir -p backup/mysql

# connect スキーマのみバックアップする例
docker compose exec db \
  mysqldump --single-transaction --routines --events \
  -u"${DB_USERNAME:-JohnDoe}" -p"${DB_PASSWORD:-foobar}" \
  "${DB_DATABASE:-connect}" > backup/mysql/connect.sql

# すべてのスキーマをバックアップしたい場合
docker compose exec db \
  mysqldump --single-transaction --routines --events --all-databases \
  -uroot -p"${MYSQL_ROOT_PASSWORD:-hogehoge}" > backup/mysql/all.sql

注意: ここで使用している環境変数は既存の MySQL 5.7 コンテナのデフォルト値です。値を変更している場合は適宜読み替えてください。

2. コンテナを停止し、旧データを退避する

docker compose down

# 旧データを残しておきたい場合は退避
mv docker/db/mysql_data docker/db/mysql_data_57_backup

# データが不要であれば削除しても構いません
# rm -rf docker/db/mysql_data

3. MySQL 8.0 コンテナを初期化する

# リポジトリを最新化（例）
git pull origin master

# 新しいイメージをビルド
docker compose build webapp

# DB コンテナのみ先に起動して初期化を完了させる
docker compose up -d db

# ログを確認し、"ready for connections" が出力されていれば初期化完了
docker compose logs -f db

データディレクトリが空の場合、新しいコンテナは docker/db/initdb.d 配下のスクリプトを利用して connect, connect_testing, connect_dusk の 3 つのデータベースを自動生成します。

4. バックアップをリストアする（必要な場合）

# 例: connect スキーマのバックアップをリストア
docker compose exec -T db \
  mysql -u"${DB_USERNAME:-app}" -p"${DB_PASSWORD:-secret}" \
  "${DB_DATABASE:-connect}" < backup/mysql/connect.sql

# 旧来の root パスワードを利用する場合
docker compose exec -T db \
  mysql -uroot -p"${MYSQL_ROOT_PASSWORD:-root-secret}" < backup/mysql/all.sql

リストア後は、必要に応じて docker compose up -d で webapp や mailhog を起動します。

よくあるトラブル

  • MySQL 8.0 が Upgrade required エラーで停止する
    → 旧ディレクトリ docker/db/mysql_data が残っている可能性があります。手順 2 に従って退避・削除してください。

  • Access denied でバックアップが実行できない
    → DB_USERNAME や MYSQL_ROOT_PASSWORD を .env で変更している場合があります。docker compose exec db env で現在の値を確認してコマンドを書き換えてください。

  • バックアップが巨大でコマンドラインから実行できない
    → mysql / mysqldump コマンドに --max-allowed-packet を付与する、あるいは gzip で圧縮するなど調整してください。