個人的備忘録：FastAPI × MySQL のマイグレーション接続エラーを整理してみた

はじめに

Docker環境で FastAPI + MySQL の開発を行っている際、マイグレーション時にMySQLへの接続エラーが発生したため、その原因と解決方法を備忘録としてまとめます。

個人の備忘録程度の走り書きとなっておりますが、温かい目で見守っていただければ幸いです。

書こうと思ったきっかけ

受講しているITスクールのハッカソンの開発の一環で、Docker + Alembic + MySQL を使った開発を行っています。マイグレーションの実行時に ConnectionRefusedError が出たため、同じような状況に陥ったときにすぐ解決できるように記事として残します。

内容

問題点

.env ファイルの DATABASE_URL が以下のように設定されていた：

DATABASE_URL=mysql+pymysql://fastapi_user:fastapi_pass@localhost:3306/fastapi_db

この localhost はホストOSを指してしまうため、Dockerコンテナ内からはアクセスできません。

修正方法

Docker Compose の db サービスを利用している場合、ホスト名は localhost ではなくサービス名（ここでは db）を指定する必要があります。

DATABASE_URL=mysql+pymysql://fastapi_user:fastapi_pass@db:3306/fastapi_db

修正後の流れ

1. .env を保存
2. Docker コンテナの再起動

docker compose down
docker compose up -d

1. マイグレーション実行

make makemigration

マイグレーション時の補足エラー

最初、以下のエラーが出ました：

FileNotFoundError: No such file or directory: '/app/migrations/versions/xxx_honda.py'

これは migrations/versions/ ディレクトリが存在しなかったためです。

→ ローカルで以下を実行し、ディレクトリを作成：

mkdir -p migrations/versions

その後再度マイグレーションを行えば正常に .py ファイルが生成されます。

まとめ

Docker上でMySQLに接続する際、.env の localhost は db にする必要がある。また、マイグレーションのディレクトリが存在しないとAlembicはファイル生成に失敗するので、事前に migrations/versions を作成しておくことが重要です...！