Dockerfile postgresを組み込む設計パターン｜初期化SQLと永続化の実装例

この記事のポイント

・initdb.d以下のSQLは「初回起動時のみ」自動実行される
・named volumeを使えばコンテナ削除後もデータが保持される
・DockerfileのENV・COPY順序がDB初期化の動作に影響する
・healthcheck付きdepends_onでDBの準備完了を待機できる

# PostgreSQL 16 をベースに初期化SQLを埋め込む例
FROM postgres:16

# 環境変数（compose側で上書き可能）
ENV POSTGRES_DB=appdb
ENV POSTGRES_USER=appuser
ENV POSTGRES_PASSWORD=changeme

# 初期化SQLをコンテナ内のinitdb.dに配置
COPY ./initdb/ /docker-entrypoint-initdb.d/

.
├── Dockerfile
└── initdb/
    ├── 01_create_tables.sql
    └── 02_insert_seeds.sql

FROM postgres:16

ENV POSTGRES_DB=appdb
ENV POSTGRES_USER=appuser
ENV POSTGRES_PASSWORD=changeme

COPY initdb/ /docker-entrypoint-initdb.d/

-- ユーザーテーブルの作成
CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 初期ユーザーデータの挿入
INSERT INTO users (username, email)
VALUES
    ('admin', 'admin@example.com'),
    ('testuser', 'test@example.com')
ON CONFLICT (username) DO NOTHING;

$ docker build -t myapp-postgres .
[+] Building 1.4s (6/6) FINISHED
 => [internal] load build definition from Dockerfile
 => [internal] load metadata for docker.io/library/postgres:16
 => [1/2] FROM docker.io/library/postgres:16
 => [2/2] COPY initdb/ /docker-entrypoint-initdb.d/
 => exporting to image
 => => naming to docker.io/library/myapp-postgres

$ docker run -d --name mydb   -p 5432:5432   -v pgdata:/var/lib/postgresql/data   myapp-postgres
3a7f8c1e2b9d4e6f8a0b2c4d6e8f0a12b34c56d78e90fa12bc34de56f78901234

$ docker logs mydb 2>&1 | grep -E 'initdb|running|ready'
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/01_create_tables.sql
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/02_insert_seeds.sql
2026-10-01 08:23:04.782 UTC [1] LOG:  database system is ready to accept connections

$ docker exec -it mydb psql -U appuser -d appdb -c "SELECT * FROM users;"
 id | username |        email         |         created_at
----+----------+----------------------+----------------------------
  1 | admin    | admin@example.com    | 2026-10-01 08:23:03.451234
  2 | testuser | test@example.com     | 2026-10-01 08:23:03.461234
(2 rows)

# ボリュームの一覧表示
$ docker volume ls
DRIVER    VOLUME NAME
local     pgdata

# ボリュームの詳細（マウントポイントの確認）
$ docker volume inspect pgdata
[
    {
        "CreatedAt": "2026-10-01T08:23:01Z",
        "Driver": "local",
        "Mountpoint": "/var/lib/docker/volumes/pgdata/_data",
        "Name": "pgdata",
        "Scope": "local"
    }
]

# コンテナを削除（-v を付けないとボリュームは残る）
$ docker rm -f mydb

# 同じボリュームをマウントして新コンテナを起動
$ docker run -d --name mydb2   -p 5432:5432   -v pgdata:/var/lib/postgresql/data   myapp-postgres

# データが保持されているかを確認
$ docker exec -it mydb2 psql -U appuser -d appdb -c "SELECT count(*) FROM users;"
 count
-------
     2
(1 row)

# compose.yml（Docker Compose v2記法）
services:
  db:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-appdb}
      POSTGRES_USER: ${POSTGRES_USER:-appuser}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?DB password is required}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    image: your-app:latest
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: "postgresql://appuser:changeme@db:5432/appdb"

volumes:
  pgdata:

$ docker compose up -d
[+] Running 3/3
 ✔ Network myapp_default  Created
 ✔ Container myapp-db-1   Healthy
 ✔ Container myapp-app-1  Started

$ docker compose ps
NAME            IMAGE              STATUS
myapp-db-1      myapp-postgres     running (healthy)
myapp-app-1     your-app:latest    running

# .env（.gitignore 対象に必ず追加すること）
POSTGRES_DB=appdb
POSTGRES_USER=appuser
POSTGRES_PASSWORD=your-strong-password-here

# .gitignore
.env

# ボリューム内にデータが存在するか確認
$ docker run --rm -v pgdata:/data alpine ls /data
PG_VERSION  base  global  pg_commit_ts  pg_dynshmem ...
# ↑ファイルが存在する場合は初期化済み → ボリュームを削除して再初期化が必要

# ボリュームを削除して再起動（データは完全に消える）
$ docker compose down -v
$ docker compose up -d

# コンテナのマウント状況を確認
$ docker inspect mydb --format='{{json .Mounts}}' | python3 -m json.tool
[
    {
        "Type": "volume",
        "Name": "pgdata",
        "Source": "/var/lib/docker/volumes/pgdata/_data",
        "Destination": "/var/lib/postgresql/data",
        "Driver": "local",
        "RW": true
    }
]
# Destination が /var/lib/postgresql/data であることを確認する
# Mounts が空配列 [] の場合はボリューム指定が漏れている

# ホスト側ディレクトリの所有者を postgres の UID に変更
$ sudo chown -R 999:999 ./data

# または named volume に切り替える（推奨）