PostgreSQL with Docker Compose

Prerequisites

Windows 11、起動済みのDocker Desktop（Linux containers）、Docker Compose v2を想定します。Composeの定義とDockerコマンドは他のOSでも共通です。

PowerShell / PC側

docker version
docker compose version

docker versionでClient / Server両方を確認します。Serverに接続できなければDocker Desktopの起動を待ってください。

以降、Dockerコマンドはcompose.yamlを置いたディレクトリのPowerShellで実行します。SQLとバックスラッシュコマンドは、接続後のコンテナ内psqlで実行します。

1. Create compose.yaml

新しい作業ディレクトリを作成します。

PowerShell / PC側

mkdir postgres-lab
cd postgres-lab
notepad compose.yaml

以下の内容をUTF-8のcompose.yamlとして保存します（.txtを付けない）。構成はpostgres-lab/compose.yamlの1ファイルだけです。

compose.yaml / ファイル内容

services:
  postgres:
    image: postgres:18
    environment:
      POSTGRES_USER: labuser
      POSTGRES_PASSWORD: local-example-only
      POSTGRES_DB: labdb
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql

volumes:
  postgres-data:

local-example-onlyは検証用パスワードです。labuserは初期化時にスーパーユーザーとして作成されます。

PowerShell / PC側

docker compose config

解決済みのCompose設定が表示され、構文エラーがないことを確認します。出力にはパスワードも含まれます。

2. Start PostgreSQL

PowerShell / PC側

docker compose up -d
docker compose ps

up -dは必要なイメージを取得し、コンテナをバックグラウンドで起動します。psではサービスpostgresがUpで、ポートが127.0.0.1:5432に公開されていることを確認します。

PowerShell / PC側

docker compose logs -f postgres

初期化後の「database system is ready to accept connections」を確認します。初回は初期化用サーバーの起動・停止も表示されるので、最後の起動完了を待ちます。Ctrl+Cでログ追跡だけを終了します（DBは停止しません）。

3. Connect with psql

PowerShell / PC側 → コンテナ内psqlを起動

docker compose exec postgres psql -U labuser -d labdb

ホスト側へのpsqlインストールは不要です。labdb=#のプロンプトになったら次を実行します。プロンプト自体は入力しません。

psql / コンテナ内

SELECT version();
\conninfo

バージョンがPostgreSQL 18系、接続DBがlabdb、ユーザーがlabuserであることを確認します。この接続はコンテナ内のUnix socketを利用するため、初期設定ではパスワード入力を求められません。PCからのTCP接続は別途認証します。

4. Create schema and table

空の検証DBに対して一度実行します。既に作成済みなら再作成せず、次のSELECTでデータを確認できます。

psql / コンテナ内

CREATE SCHEMA lab AUTHORIZATION labuser;
\dn

labのOwnerがlabuserであることを確認します。

CREATE TABLE lab.customer (
    customer_id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    customer_name varchar(100) NOT NULL,
    email varchar(255),
    created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP
);

\dt lab.*

テーブル名をlab.customerとSchema付きで指定するため、search_pathの変更は不要です。

CREATE TABLEの構造を一覧で確認したい場合は、上のCREATE TABLE文だけ（\dtは除く）をDDL Analyzerへ貼り付け、カラム・型・制約・DEFAULTを確認できます。

5. Insert and query data

psql / コンテナ内

INSERT INTO lab.customer (customer_name, email)
VALUES
    ('Aoki', '[email protected]'),
    ('Sato', '[email protected]'),
    ('Tanaka', NULL);

SELECT
    customer_id,
    customer_name,
    email,
    created_at
FROM lab.customer
ORDER BY customer_id;

初回は3行が返り、IDと作成日時が自動設定されます。INSERTを繰り返すと、その都度3行が追加されます。

このSELECTをSQL Formatterへ貼り付けて整形したり、SQL Column Extractorで出力カラムと参照テーブルを確認できます。

Useful psql commands

すべてコンテナ内psqlで実行します。バックスラッシュコマンドにセミコロンは不要です。結果がページャーで表示された場合はqで戻ります。

Stop / Start / Remove

psqlを\qで終了してから、目的に合うコマンドを1つ実行します。

PowerShell / PC側 — 一時停止

docker compose stop

コンテナを残したまま停止します。

PowerShell / PC側 — 停止済みコンテナの再開

docker compose start

残っているコンテナを再開します。削除済みの場合はup -dを使います。

PowerShell / PC側 — 通常終了

docker compose down

コンテナとComposeのネットワークを削除します。named volumeは残ります。

Data persistence

DBデータはnamed volumeのpostgres-dataに保存します。docker compose downだけでは削除されません。

PowerShell / PC側 — 同じディレクトリで再構築

docker compose up -d
docker compose exec postgres psql -U labuser -d labdb

同じComposeプロジェクトなら同じVolumeを再利用します。上のSELECTを再実行して行が残っていることを確認できます。通常のVolume名はpostgres-lab_postgres-dataです。ディレクトリ名や-pでプロジェクト名を変えると別Volumeになるため注意してください。

Change host port

5432が使用中ならcompose.yamlのportsを次へ置き換えます。

compose.yaml / portsの置換

    ports:
      - "127.0.0.1:5433:5432"

docker compose up -dで反映します。コンテナ内は5432のまま、PCからはlocalhost:5433へ接続します。コンテナ内psqlの接続コマンドは変わりません。

Connect from DBeaver

PC上のDBeaverでPostgreSQL接続を作り、以下を入力してTest Connectionを実行します。インストールや詳細な操作は本Guideでは扱いません。

Logs

起動しない場合は、最初にログを確認します。

PowerShell / PC側

docker compose logs postgres
docker compose logs -f postgres

最初のコマンドは現在までのログを表示して終了します。-fは新しいログを追跡します。Ctrl+Cで追跡を終了できます。

Troubleshooting

Port 5432 already in use

別のPostgreSQLなどが使用中です。ホスト側だけ5433へ変更してdocker compose up -dを再実行します。

コンテナが起動しない

docker versionでServerへの接続、docker compose configで設定、docker compose ps -aとログで終了理由を確認します。Docker DesktopがLinux containersで動作しているか、イメージ取得に失敗していないかも確認してください。

Passwordを変更したのに反映されない

POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DBは空のデータディレクトリを初期化するときだけ適用されます。既存VolumeのDBには、Composeの変更やコンテナ再作成だけでは再適用されません。これは公式イメージの初期化仕様です。

データを残してパスワードだけ変更する場合は、既存の管理Roleでpsqlへ接続し、\password labuserで対話的に変更します。接続クライアント側の設定も合わせて更新してください。

Volumeに以前のDBが残っている

永続化の正常な動作です。既存のRole / DB名で接続してください。空に戻したい場合だけ、必要なデータを退避し、完全削除のWarningを確認します。別メジャーバージョンのデータをそのまま18へ流用せず、移行・復元を行ってください。

接続できない

psとログで起動完了を確認し、PCからはホスト・公開ポート・DB名・ユーザー・初期化時のパスワードを確認します。localhostがIPv6へ解決される場合は127.0.0.1を指定します。コンテナ内psqlに接続できても、PCからのTCP認証が成功するとは限りません。

Security note

Quick Reference

PowerShellでpostgres-labディレクトリから実行します。狭い画面では表の中を横にスクロールできます。

Related Tools

作成したDDLとSELECTを、ブラウザ内で整理・確認できます。

Official references

• PostgreSQL Docker Official Image — tags / initialization / PGDATA
• PostgreSQL 18 — psql
• Docker Compose CLI reference