PostgreSQLコンテナをDocker Composeで運用する設計｜データ永続化と初期化スクリプト、ダンプ取得の実務

この記事のポイント

・docker composeのnamedボリュームでコンテナ削除後もDBデータが残る永続化を実現できる
・/docker-entrypoint-initdb.dにSQLファイルを置くと初回起動時だけ自動実行される
・pg_dumpはdocker compose exec経由で稼働中コンテナから直接取得できる
・ボリュームが既に存在すると初期化スクリプトが再実行されない点が最大のはまりどころ

# docker-compose.yml（最小構成：PostgreSQL + namedボリューム）
services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: changeme
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  pgdata:

# コンテナを起動してpostgresに接続し、テストデータを投入する
$ docker compose up -d
$ docker compose exec db psql -U appuser -d appdb -c \
  "CREATE TABLE memo (id serial PRIMARY KEY, body text);"
$ docker compose exec db psql -U appuser -d appdb -c \
  "INSERT INTO memo (body) VALUES ('test record');"

# コンテナを削除する（--volumes なしでボリュームは残る）
$ docker compose down

# 再作成してデータを確認する
$ docker compose up -d
$ docker compose exec db psql -U appuser -d appdb -c "SELECT * FROM memo;"
 id |    body
----+-------------
  1 | test record
(1 row)

# docker-compose.yml（initdb対応版）
services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: changeme
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./initdb:/docker-entrypoint-initdb.d:ro

volumes:
  pgdata:

# initdb/01_create_tables.sql
CREATE TABLE IF NOT EXISTS users (
  id   SERIAL PRIMARY KEY,
  name VARCHAR(100) NOT NULL,
  email VARCHAR(200) UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS articles (
  id         SERIAL PRIMARY KEY,
  user_id    INTEGER REFERENCES users(id),
  title      VARCHAR(200) NOT NULL,
  body       TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

# initdb/02_seed_data.sql（マスタデータ投入）
INSERT INTO users (name, email) VALUES
  ('山田 太郎', 'yamada@example.com'),
  ('鈴木 花子', 'suzuki@example.com')
ON CONFLICT DO NOTHING;

$ docker compose logs db | grep -E 'initdb|running'
db-1  | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/01_create_tables.sql
db-1  | /usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/02_seed_data.sql

# 注意: 既存のボリューム（データ）を完全に削除してから再作成する
# ※ 本番データがある場合は先にダンプを取得してから実行すること
$ docker compose down -v
$ docker compose up -d

# プレーンSQLフォーマットでダンプを取得する（-Tでバイナリ混入を防ぐ）
$ docker compose exec -T db pg_dump -U appuser -d appdb > appdb_$(date +%Y%m%d_%H%M%S).sql

# 実行結果の確認
$ ls -lh appdb_*.sql
-rw-r--r-- 1 user user 4.5K Sep  6 10:00 appdb_20260906_100000.sql

# ダンプ内容の先頭を確認
$ head -5 appdb_20260906_100000.sql
--
-- PostgreSQL database dump
--
-- Dumped from database version 16.4
-- Dumped by pg_dump version 16.4

# 別環境またはコンテナ再作成後のPostgreSQLに復元する
$ docker compose exec -T db psql -U appuser -d appdb < appdb_20260906_100000.sql

# 復元後のテーブル確認
$ docker compose exec db psql -U appuser -d appdb -c "\dt"
        List of relations
 Schema |   Name   | Type  |  Owner
--------+----------+-------+---------
 public | articles | table | appuser
 public | users    | table | appuser
(2 rows)

# カスタム形式でダンプを取得する（.dumpファイル）
$ docker compose exec -T db pg_dump -U appuser -d appdb -Fc > appdb_20260906.dump

# カスタム形式の復元はpg_restoreを使う
$ docker compose exec -T db pg_restore -U appuser -d appdb < appdb_20260906.dump

#!/bin/bash
# /opt/scripts/backup-postgres.sh

COMPOSE_DIR="/opt/myapp"
BACKUP_DIR="/var/backup/postgres"
DB_SERVICE="db"
DB_USER="appuser"
DB_NAME="appdb"
KEEP_DAYS=7
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE="${BACKUP_DIR}/${DB_NAME}_${TIMESTAMP}.sql.gz"

mkdir -p "${BACKUP_DIR}"

cd "${COMPOSE_DIR}" && \
  docker compose exec -T "${DB_SERVICE}" pg_dump -U "${DB_USER}" -d "${DB_NAME}" \
  | gzip > "${BACKUP_FILE}"

# 7日より古いバックアップを削除する
find "${BACKUP_DIR}" -name "*.sql.gz" -mtime +${KEEP_DAYS} -delete

echo "Backup completed: ${BACKUP_FILE}"

# crontabへの登録例（毎日午前3時に実行）
$ crontab -e
0 3 * * * /opt/scripts/backup-postgres.sh >> /var/log/postgres-backup.log 2>&1

db-1  | initdb: error: directory "/var/lib/postgresql/data" exists but is not empty
db-1  | If you want to create a new database system, either remove or empty
db-1  | the directory "/var/lib/postgresql/data" or run initdb
db-1  | with an argument other than "/var/lib/postgresql/data".

# ホスト側のディレクトリ所有者をPostgresコンテナのUID(999)に変更する
$ sudo chown -R 999:999 ./data

$ docker compose exec db pg_dump -U wronguser -d appdb
pg_dump: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432"
failed: FATAL:  role "wronguser" does not exist