postgres:18 のDockerコンテナが Restarting になり続けた原因と修正

起きたこと

ローカル開発用に postgres:18 のコンテナを起動しようとしたところ、docker compose up -d 自体は成功したように見えた。

docker compose up -d

しかし、状態を確認するとPostgreSQLコンテナが起動完了せず、再起動を繰り返していた。

docker compose ps

NAME      IMAGE         SERVICE   STATUS
db-cp     postgres:18   db        Restarting (1)

出ていたログ

docker compose logs db --tail=100

ログには以下のような内容が出ていた。

Error: in 18+, these Docker images are configured to store database data in a
format which is compatible with "pg_ctlcluster"

Counter to that, there appears to be PostgreSQL data in:
  /var/lib/postgresql/data (unused mount/volume)

The suggested container configuration for 18+ is to place a single mount
at /var/lib/postgresql

原因

compose.yaml では PostgreSQL 18 を使っていた。

image: postgres:18

一方で、volume のマウント先は以下のようになっていた。

volumes:
  - db-data:/var/lib/postgresql/data

PostgreSQL 18系のDockerイメージでは、データディレクトリの扱いが変わっている。

ログにも、18以降では /var/lib/postgresql に単一のmountを置く構成が提案されていた。

そのため、/var/lib/postgresql/data にvolumeを直接マウントしていたことが原因で、コンテナが起動できず Restarting になっていた。

修正方法

compose.yaml のvolumeマウント先を変更した。

修正前:

volumes:
  - db-data:/var/lib/postgresql/data

修正後:

volumes:
  - db-data:/var/lib/postgresql

最終的な compose.yaml は以下。

services:
  db:
    image: postgres:18
    container_name: db-cp
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-postgres}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
    ports:
      - "5432:5432"
    volumes:
      - db-data:/var/lib/postgresql

volumes:
  db-data:

その後、古いvolumeを削除して起動し直した。

docker compose down -v
docker compose up -d

確認する。

docker compose ps

STATUS が Up になればOK。

どう判断したか

判断材料は3つ。

1. docker compose up -d は成功していた
2. しかし docker compose ps では Restarting になっていた
3. docker compose logs db に PostgreSQL 18 のデータディレクトリ仕様に関するエラーが出ていた

特に重要だったのは、ログ内の以下の部分。

there appears to be PostgreSQL data in:
  /var/lib/postgresql/data

The suggested container configuration for 18+ is to place a single mount
at /var/lib/postgresql

このため、アプリケーションやMakefileではなく、PostgreSQLコンテナのvolumeマウント設定の問題だと判断した。

注意点

docker compose down -v はDocker volumeを削除する。

今回のようにローカル開発用DBで、migrationやseedから作り直せる場合は問題ない。

ただし、消してはいけないデータが入っているDBでは実行しないこと。必要な場合は先にバックアップや pg_upgrade を検討する。

参考

• https://github.com/docker-library/postgres/pull/1259
• https://github.com/docker-library/postgres/issues/37

結論

英語読めるようにしよう