🚀 Alembic + PostgreSQL 環境構築まとめ（Docker + VSCode + Poetry）

開発で使った Alembic の導入から、Docker 経由で立ち上げた PostgreSQL にマイグレーションを実行し、VSCode の拡張機能で接続して DB の中身を確認するまでの流れを詳細にまとめます。

※ 機密情報（パスワード等）は含まれていません。

---

🔧 前提環境

• Docker / Docker Compose
• Python 3.11
• Poetry（依存管理）
• PostgreSQL（Dockerコンテナ）
• VSCode + PostgreSQL 拡張機能

---

📦 Alembic の導入と初期化

1. Alembic を Poetry 経由でインストール

poetry add --group dev alembic

2. Alembic 初期化

poetry run alembic init alembic

これにより、以下が生成されます：

• alembic.ini
• alembic/env.py
• alembic/versions/

3. モデル定義の作成

models/ ディレクトリをプロジェクト直下に作成し、SQLAlchemy のモデルを各ファイルに分割して定義。

例：models/user.py, models/hobby.py など。

4. models/__init__.py にすべてのモデルをインポート

from .user import User
from .hobby import Hobby
# ... 他のモデル

5. Alembic でモデルを読み込ませる（alembic/env.py）

from models import Base  # models/__init__.py で Base = declarative_base() を定義しておく
from dotenv import load_dotenv
load_dotenv()

# DATABASE_URL の構築
user = os.getenv("POSTGRES_USER")
password = os.getenv("POSTGRES_PASSWORD")
host = os.getenv("POSTGRES_HOST")
port = os.getenv("POSTGRES_PORT")
database = os.getenv("POSTGRES_DB")

database_url = f"postgresql+psycopg2://{user}:{password}@{host}:{port}/{database}"
config.set_main_option("sqlalchemy.url", database_url)

---

🐃 PostgreSQL の Docker コンテナ設定

docker-compose.dev.yml

services:
  db:
    image: postgres:latest
    container_name: app-db
    env_file:
      - .env
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  backend:
    build:
      context: ./
      dockerfile: ./Dockerfile.dev
    container_name: app-backend
    volumes:
      - ./:/app
    depends_on:
      - db
    environment:
      - DATABASE_URL=postgres://...  # docker-compose.yml上でも指定可

volumes:
  postgres_data:

.env ファイル例

POSTGRES_USER=app_user
POSTGRES_PASSWORD=securepassword
POSTGRES_DB=app_db
POSTGRES_HOST=db
POSTGRES_PORT=5432

---

🛠 マイグレーションファイルの作成と実行

1. 初回マイグレーションファイル作成

poetry run alembic revision --autogenerate -m "initial migration"

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

poetry run alembic upgrade head

❗トラブル対策メモ

• localhost が動作しない → Docker 内部のサービス名（例：db）を使う
• Name or service not known → Docker の DNS 問題、もしくは起動タイミング問題
• FATAL: password authentication failed → コンテナのボリューム削除で解決することあり：

docker compose down -v

---

🧠 補足：Alembic コンテナ起動時に動かない問題

コンテナを立て直すと alembic コマンドが使えなくなることがある。

これは Dockerfile.dev に poetry install --no-root のあとに COPY . /app をしていることで、alembic のある仮想環境が上書きされてしまうのが原因。

対策

Dockerfile の COPY . /app を poetry install の前に移動しないこと。

---

🖥 VSCode 拡張機能 PostgreSQL から接続する

1. PostgreSQL 拡張機能をインストール（例：cweijan.vscode-postgresql）
2. 左ペインの DB アイコンから "Add New Connection"
3. 以下のように入力：

項目	値
Host	db（Docker 内部接続）
Port	5432
User	app_user
Password	.env で指定した値
Database	app_db

1. select database の欄で db を入力して Enter すると接続成功 🎉

---

✅ まとめ

• Alembic の導入は poetry add --group dev alembic
• DB 接続は .env 経由で構築 & alembic/env.py に設定
• Docker 内部から接続する場合、localhost ではなく db を使う
• VSCode の拡張機能でも GUI 接続が可能

開発メンバーにも共有できるよう、alembic/README.md に保存しておくと便利です！