開発で使った 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 から接続する

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

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

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

✅ まとめ

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

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