PostgreSQL コンテナを Docker Compose で管理する際、環境変数の設定はコンテナの初期動作と再起動方式に重要な影響を与えます。特に、データボリュームの存在によって各変数の適用タイミングが異なるため、これを正確に理解することが安全な運用に繋がります。

1. 必須環境変数: POSTGRES_PASSWORD

PostgreSQL コンテナを Docker イメージで起動する場合、 POSTGRES_PASSWORD はデータボリュームの状態に関係なく 必ず設定 しなければならない唯一の必須環境変数です。

変数名 役割 適用タイミング 削除時の動作
POSTGRES_PASSWORD スーパーユーザーのパスワード設定 常に必要 (初期設定およびコンテナ起動プロセス) コンテナ 起動失敗 (セキュリティエラー)

核心: この変数はコンテナをスタートするためのセキュリティ要件であり、データが既に存在する場合でも docker-compose.yml ファイル内に 明示されている必要があります。

2. 初期設定変数: 適用タイミングの理解

POSTGRES_USER と POSTGRES_DB はデータベースクラスタが 最初に作成される際（データボリュームが空の時） にのみ適用される環境変数です。

変数名 役割 適用タイミング 再起動時の変更の影響
POSTGRES_USER 初期スーパーユーザー名の指定 ボリュームが空の時のみ 無視される (既存ユーザーを維持)
POSTGRES_DB 初期データベース名の生成 ボリュームが空の時のみ 無視される (既存DBを維持)

📌 再起動時の動作原理

すでにデータが存在するボリュームを接続してコンテナを docker-compose up -d で再起動する場合、PostgreSQL イメージは初期化プロセス（initdb）をスキップして既存のデータをロードします。

したがって、コンテナ名やロギング方式などの他の設定を変更して再起動する際には、POSTGRES_USER や POSTGRES_DB の値を 修正しても既存のデータベースのユーザーや名前は変更されません。

3. Docker Compose の例

次は必須変数と推奨変数を含む簡潔な docker-compose.yml の例です。

services:
  db:
    image: postgres:latest
    restart: always
    container_name: my_postgres_db  # コンテナ名（変更可能）
    logging:
      driver: "json-file"          # ロギング方式（変更可能）
    environment:
      # ⚠️ 必須変数：必ず含める必要があります。
      POSTGRES_PASSWORD: your_secure_password 

      # 初期設定変数：ボリュームが空の時のみ適用されます。
      POSTGRES_USER: devuser
      POSTGRES_DB: main_app_db
    ports:
      - "5432:5432"
    volumes:
      # データを永続的に保存するためのボリューム
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

✨ 運用のヒント: 安全な設定変更

コンテナ名やロギング設定などを変更した後、既存データを保持しつつ再起動するには、次のコマンドを使用します。

docker-compose up -d

注意: データが含まれるボリュームを削除するコマンド（docker-compose down -v）は 絶対に使用しないように 注意が必要です。