🚀 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 経由でインストール
```bash
poetry add --group dev alembic
```

### 2. Alembic 初期化
```bash
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` にすべてのモデルをインポート
```python
from .user import User
from .hobby import Hobby
# ... 他のモデル
```

### 5. Alembic でモデルを読み込ませる（`alembic/env.py`）
```python
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`
```yaml
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` ファイル例
```env
POSTGRES_USER=app_user
POSTGRES_PASSWORD=securepassword
POSTGRES_DB=app_db
POSTGRES_HOST=db
POSTGRES_PORT=5432
```

---

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

### 1. 初回マイグレーションファイル作成
```bash
poetry run alembic revision --autogenerate -m "initial migration"
```

### 2. マイグレーション実行
```bash
poetry run alembic upgrade head
```

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

```bash
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`                  |

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

---

## ✅ まとめ

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

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