Docker ComposeでPostgreSQLの開発環境を構築する手順

このサイトはアフィリエイト広告(Amazonアソシエイト含む)を掲載しています。
Dockerコンテナ内のPostgreSQLと、Composeで起動するコマンドを描いたイラスト

「ローカルにPostgreSQLをインストールしたら他の開発環境と設定が干渉してしまった……」「OSが違うと手順がバラバラになってしまった……」ということ、ありますよね。

実はこの問題、Dockerを使うとほぼ解消できます。数行の設定ファイルを書くだけで、環境汚染なし・チーム間で再現性のある開発用PostgreSQL環境が数分で立ち上がりますよ。

筆者はもともとDockerを使ったことがありませんでした。この記事ではそんなDocker超初心者でも構築できた、インストールから接続確認まで順を追って解説します。

Docker Composeを使えばdocker-compose.yamlを作成してdocker compose up -dを実行するだけでPostgreSQLの開発環境を起動できます。この記事ではPostgreSQL 16を例にVolumeによるデータ永続化とpsql・GUIツールからの接続確認まで進めます。

検証環境(確認日:2026年7月)

この記事は以下の環境で動作を確認しています。
OS:Windows 11 Home 25H2
Docker:29.6.1
Docker Compose:v5.3.0
PostgreSQLイメージ:postgres:16-alpine

目次

Dockerなら数分で開発用PostgreSQL環境を作れる

Dockerを使うとローカルDB構築が圧倒的に簡単になる理由

PostgreSQLをローカルマシンに直接インストールする方法もありますが、Dockerを使うと次の点が大きく変わります。

  • OSにPostgreSQLの設定ファイルが散らばらない(環境が汚れない)。
  • docker compose up -dで起動しdocker compose stopで停止できる。
  • チームメンバーと同じdocker-compose.yamlを共有するだけで環境が揃う。
  • PostgreSQLのバージョンごとにイメージとデータ用Volumeを分けて検証環境を用意できる。

不要になったらコンテナを削除するだけで済むので、ローカル環境をスッキリ保てるのも地味にありがたいです。

今回構築する「最小構成PostgreSQL環境」の全体像

内容
PostgreSQLバージョン16-alpine(公式イメージ)
接続ポート5432(ホスト) → 5432(コンテナ)
データ永続化Docker Volume(postgres16)
構成ファイルdocker-compose.yamlの1ファイルのみ

alpineは軽量なAlpine Linuxをベースにしたイメージです。今回はpostgres:16-alpineを使用します。通常版とはベースOSや含まれるライブラリが異なるため、拡張機能を追加する場合は対応状況を確認してください。

完成後にできること

  • コンテナを削除してもデータが消えない永続化設定
  • ターミナルからpsqlコマンドで直接接続
  • DBeaver・TablePlusなどGUIツールから接続
  • アプリケーション(Node.js、Python、Javaなど)からのDB接続

Docker初心者が最初に知っておくべき基本知識

Dockerを使うメリットやローカル環境との違いを先に整理したい方はこちらも参考になります。

コンテナ・イメージ・Docker Composeの関係

Dockerを使う上で最低限押さえておきたい概念が3つあります。

イメージ

アプリケーションの「設計図」です。PostgreSQL公式イメージにはPostgreSQLが動くために必要なものがすべて詰まっています。

コンテナ

イメージを実際に起動した「実行中の箱」です。イメージ1つから何個でもコンテナを作れます。

Docker Compose

複数のコンテナをまとめて定義・管理するためのツールです。docker-compose.yamlに設定を書いておけば、コマンド一発で環境が立ち上がります。

「イメージ=プログラムのCD-ROM、コンテナ=そのCDを入れて起動したPC」というイメージで捉えると少し分かりやすいかもしれません。

開発環境の準備(Dockerのインストール)

Windows・MacでDockerをインストールする

DockerはWindows・Macともに「Docker Desktop」というアプリをインストールするのが最短ルートです。

  1. Docker公式サイトにアクセスします。
  2. OSに合わせたインストーラをダウンロードします。
  3. インストーラを実行し、指示に従ってDocker Desktopをセットアップします。
  4. Docker Desktopを起動します。
  5. タスクバーまたはメニューバーにクジラのアイコンが表示されれば起動完了です。

WindowsではWSL2(Windows Subsystem for Linux 2)が必要になる場合があります。インストーラが案内してくれるので、指示に従って有効化してください。


SQL Server の環境構築も同じ流れで進められます。Docker Desktop のセットアップが済んでいれば、以下の記事もあわせて参考にしてみてください。

Dockerが正常に動いているか確認する

インストール後ターミナル(PowerShellまたはTerminal.app)で以下のコマンドを実行し、バージョンが表示されれば準備完了です。

コマンド
docker --version
実行結果
Docker version 29.6.1, build 8900f1d

エラーが出る場合はDocker Desktopが起動しているかを確認してみてください。

docker-compose.yamlでPostgreSQL環境を定義する

今回使用するdocker-compose.yaml(最小構成)

作業用ディレクトリを1つ作り、その中に以下の内容でdocker-compose.yamlを作成します。次の設定ではPostgreSQL 16をホストの5432番ポートで公開し、データをpostgres16というDocker Volumeへ保存します。

docker-compose.yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: postgres16
    restart: unless-stopped

    environment:
      POSTGRES_USER: 【DBユーザー名】
      POSTGRES_PASSWORD: 【DBパスワード】
      POSTGRES_DB: 【DB名】
      TZ: Asia/Tokyo

    ports:
      - "5432:5432"

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

volumes:
  postgres16:

たったこれだけです。各設定の意味を一つずつ見ていきましょう。

この例はローカル検証用の最小構成です。実際のユーザー名やパスワードを書いたComposeファイルをそのままGitへコミットしないでください。チームで共有する場合は.envやDocker Compose Secretsへ分離します。

docker-compose.yamlの各設定内容

image

Docker Hub上の公式PostgreSQLイメージを指定しています。postgres:16は16系を指定するタグです。取得済みのイメージが自動更新されるわけではないため、同じメジャーバージョンの新しいイメージを取得するときはdocker compose pull postgresを実行し、その後docker compose up -dで反映します。postgres:latestと書いてしまうと将来的に意図しないメジャーバージョンアップが起きることがあるため、バージョンを明示するのがおすすめです。

今回選んだpostgres:16-alpine(Alpine Linuxベースの軽量版)と通常版の違いはこんな感じです。

postgres:16postgres:16-alpine
ベースOSDebianAlpine Linux
イメージサイズ約400MB約100MB前後
起動速度普通速い

container_name

container_nameを指定するとコンテナをpostgres16という固定名で操作できます。省略した場合はComposeがプロジェクト名とサービス名をもとにコンテナ名を生成します。通常は省略しても問題ありません。

restart

PCやDocker Desktopを起動したときにコンテナを自動再起動するかどうかの設定です。

値挙動
no自動再起動しない(デフォルト)
always常に再起動する
unless-stopped手動停止時以外は再起動する
on-failureエラー終了時のみ再起動する

ports

ホスト側のポート:コンテナ側のポートの形式で書きます。"5432:5432"でホストの5432番ポートへのアクセスがコンテナ内のPostgreSQL(5432番)に転送されます。ローカルにすでにPostgreSQLがインストールされていてポートが競合する場合は"15432:5432"のように左側を調整してください。

environment

コンテナの初回起動時に、指定したユーザーとデータベースを自動で作成してくれます。手動でCREATE USERやCREATE DATABASEを打つ必要がないのが便利なところですね。

POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DBはデータディレクトリが空の初回起動時に使われます。値を変更しても既存のVolumeが残っていると再初期化されません。作り直す場合はデータ削除を理解したうえでdocker compose down -vを実行してください。

変数名説明
POSTGRES_USER作成するロール(ユーザー)名。
POSTGRES_PASSWORDそのロールのパスワード。
POSTGRES_DB初期作成するデータベース名。
TZコンテナ内のタイムゾーン。Asia/Tokyoを指定しておくと日本環境で安心です。

volumes

ボリューム名:マウント先パスの形式で指定します。この例では名前付きVolumeのpostgres16をPostgreSQL 16のデータ保存先である/var/lib/postgresql/dataへマウントしています。

公式の16系イメージでは明示的にVolumeを指定しない場合も匿名Volumeが作られます。コンテナを作り直したときに同じデータを引き継ぎやすくするため、この記事では名前付きVolumeを指定します。

PostgreSQLコンテナを起動する

docker compose upでDBを起動する

docker-compose.yamlがあるディレクトリで以下のコマンドを実行します。

コマンド
docker compose up -d
実行結果
[+] up 1/1
 ✔ Container postgres16 Created

-dオプションはバックグラウンド実行(detached mode)の指定です。初回はPostgreSQLのイメージをDocker Hubからダウンロードするため少し時間がかかります。2回目以降はキャッシュが使われるので数秒で起動しますよ。

コンテナが起動しているか確認する

コマンド
docker compose ps
実行結果
NAME         IMAGE                COMMAND                   SERVICE    CREATED         STATUS         PORTS
postgres16   postgres:16-alpine   "docker-entrypoint.s…"   postgres   3 minutes ago   Up 3 minutes   0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp

STATUS欄がUpと表示されれば起動しています。

PostgreSQLの初期化が終わるまで少し待つ場合があります。接続できないときは次のコマンドで起動ログを確認してください。

コマンド
docker compose logs --tail=50 postgres

起動処理の末尾でdatabase system is ready to accept connectionsが表示されているか確認します。エラーがある場合はその内容を先に確認してください。

よくある起動エラーと原因

Docker Desktopが起動していない

エラー内容
Error response from daemon: …

タスクバー(Windows)またはメニューバー(Mac)のDockerアイコンを確認しアプリを起動してから再実行してください。

ポート5432が使用中

エラー内容
Error starting userland proxy: listen tcp4 0.0.0.0:5432: bind: address already in use

ローカルにPostgreSQLがインストール済みですでに5432番ポートを使っている場合に発生します。docker-compose.yamlのportsを"15432:5432"のように変更してください。

YAMLのインデントが崩れている

YAMLはインデント(スペースの数)に非常に敏感です。タブ文字は使えないため、スペース2つでインデントできているか確認してみてください。


Windowsで起動後にコンテナが応答しなくなりDocker Desktopからの停止も失敗する場合は、WSL2のメモリ上限を調べた事例が参考になります。

DockerコンテナのPostgreSQLへ接続する

ターミナルからコンテナ内のpsqlで接続する

コンテナの中に直接入ってpsqlコマンドで接続する方法です。

コマンド
docker compose exec postgres psql -U 【DBユーザー名】 -d 【DB名】
実行結果
psql (16.13)
Type "help" for help.
【DB名】=#

psqlのメタコマンドやこれからSQL・設定で見かける用語の意味を確認したい場合はPostgreSQLの用語・機能一覧も参照できます。

DBeaverやTablePlusなどGUIツールから接続する

GUIツールから接続する場合は「新しい接続」または「New Connection」から「PostgreSQL」を選択し、以下の情報を入力します。

項目値
Hostlocalhost
Port5432
Database【DB名】
Username【DBユーザー名】
Password【DBパスワード】

この表はDockerを動かしているPC上のGUIツールから接続する場合の設定です。ポート競合を避けて”15432:5432″に変更した場合はGUI側のPortも15432にします。

同じComposeネットワーク上の別コンテナから接続する場合はHostをサービス名のpostgres、Portを5432にします。別コンテナから見たlocalhostはそのコンテナ自身を指します。

GUIツールはSQL補完や視覚的なER図表示ができて便利です。DBeaverやA5:SQL Mk-2がよく聞くツールですね。


JavaアプリからPostgreSQLへ接続する場合はcurrentSchemaの指定方法も確認しておくと実務で詰まりにくいです。

データを永続化する仕組み(Volume)

コンテナ削除でもデータが消えない理由

コンテナ自身の書き込み領域はコンテナを削除すると失われます。この記事ではDBデータを独立した名前付きVolumeへ保存するため、コンテナを削除してもデータを保持できます。

docker-compose.yamlで指定したVolumeはコンテナとは独立したストレージ領域として管理されます。コンテナを削除してもVolumeは残るため、再度コンテナを作り直してもデータをそのまま引き継げます。

Docker Volumeの仕組み

docker-compose.yaml – volumes設定の該当箇所
volumes:
  - postgres16:/var/lib/postgresql/data

「Dockerが管理するpostgres16というVolumeをコンテナ内の/var/lib/postgresql/data(PostgreSQLがデータを書き込む場所)にマウントする」という意味です。

通常、Composeが作成するVolumeの実名はプロジェクト名が付きます。まず次のコマンドでVolumeの一覧を確認します。

コマンド
docker volume ls

この記事の設定では通常はプロジェクト名_postgres16という名前になります。確認した実名を指定すると、保存先などの情報を表示できます。

コマンド
docker volume inspect 【一覧で確認したVolume名】

Docker DesktopではLinux用の仮想環境内でVolumeが管理されるため、表示された保存先をWindowsのエクスプローラーから直接開けません。

Volumeを削除するとDBは初期化される

DBを完全に初期化したい場合はVolumeごと削除します。

コマンド
# コンテナとVolumeをまとめて削除する(データも消えます)
docker compose down -v

開発でよく使うDocker操作コマンド

操作コマンド補足
起動docker compose up -dバックグラウンドで起動
停止docker compose stopコンテナは残る
再起動docker compose restart現在の設定でコンテナを再起動
Compose設定変更の反映docker compose up -d変更があればコンテナを再作成
削除(データ残す)docker compose downVolumeは残る
削除(データも消す)docker compose down -v完全初期化
ログ確認docker compose logs -f postgresリアルタイム確認
状態確認docker compose ps起動中かどうか確認

POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DBはデータ保存先が空のときに初期設定へ使われます。既存Volumeを使っている場合は、Composeファイルを書き換えてコンテナを再作成しても保存済みのユーザー・パスワード・DB名は変更されません。

docker compose downだけであればVolumeは残ります。再度docker compose up -dすれば以前のデータのまま起動できます。

DockerでPostgreSQLを使うメリット・デメリット

メリット

環境が汚れない

PostgreSQLの設定ファイルや依存ライブラリがOS上に散らばりません。

再現性が高い

docker-compose.yamlを共有するだけでチーム全員が同じ環境を作れます。

バージョン切り替えが楽

バージョンごとにイメージとデータ用Volumeを分ければ複数の検証環境を管理できます。(既存データを別のメジャーバージョンへ引き継ぐ場合は移行作業が必要です。)

破棄が簡単

docker compose downでコンテナとネットワークを削除できます。名前付きVolumeに保存したDBデータは別途削除する必要があります。

デメリット

Dockerの概念を覚える必要がある

コンテナ・イメージ・Volumeなど、最初に学習コストがかかります。筆者のようにあたふたすることも。

Docker Desktop自体のリソースを消費する

特にWindowsではメモリをそれなりに使います。

本番との差異に注意

本番環境がDockerでない場合、環境差異が生まれる可能性があります。

ローカルインストールとの違い

比較項目ローカルインストールDocker
セットアップの手間OSごとに手順が異なるdocker-compose.yamlで統一
環境の汚れ残る残らない
複数バージョン共存難しい簡単
データの永続化デフォルトで永続Volume設定が必要
チーム共有手順書が必要yamlファイルを共有するだけ

迷いやすいポイント

PostgreSQL 17以降のイメージを使いたい場合は?

新しくPostgreSQL 17の環境を作る場合はimageにpostgres:17-alpineを指定しデータ用Volumeも17用に分けます。
PostgreSQL 18以降では公式イメージの保存先構成が変わるため、Volumeのマウント先は/var/lib/postgresqlにします。この記事の16用設定を使う場合は、この違いに注意してください。
すでに16で保存したデータを17や18へ移すには、バックアップ・リストアやpg_upgradeなどによる移行が必要です。

コンテナ起動時に自動でテーブルを作りたい場合は?

docker-compose.yamlと同じフォルダーにinitフォルダーを作り、その中へ実行するSQLのファイルを作成します。(今回は01-create-table.sqlとしました。)

01-create-table.sql
CREATE TABLE sample_items (
    id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name text NOT NULL
);

INSERT INTO sample_items (name) VALUES ('sample');

次にservices内のpostgresにあるvolumesを次の内容へ変更します。末尾のトップレベルのvolumes定義はそのまま使用します。

docker-compose.yaml
volumes:
      - postgres16:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d:ro

データ保存先が空の状態で起動すると/docker-entrypoint-initdb.d内のSQLが実行されます。すでにDBがあるVolumeではSQLファイルを追加して再起動しても自動実行されません。

この例のSQLを既存DBへ実行したい場合はpsqlなどから手動で実行してください。初期化をやり直すためのdocker compose down -vは保存済みデータを削除するため、データを捨ててよい検証環境でのみ使用します。

Dockerを使わずにPostgreSQLをローカルインストールした場合と接続方法は変わる?

アプリ側からの接続情報(ホスト・ポート・ユーザー・DB名・パスワード)は同じ形式です。Docker環境ではホストがlocalhost、ポートが5432(または変更した場合はそのポート)になります。別のコンテナからアクセスする場合はサービス名(postgres)をホストに指定してください。

Apple Silicon(M1/M2…)のMacでも動く?

動きます。postgres:16-alpineはlinux/amd64とlinux/arm64の両方に対応しているので特別な設定は不要です。


PostgreSQLやSQL ServerなどDB関連の記事をまとめて確認したい方はこちら。

まとめ:再現しやすいPostgreSQL開発環境ならDockerが便利

  • DockerはVMより軽量で、コンテナ単位でアプリを動かす技術だよ。
  • docker-compose.yamlにimage・ports・environment・volumesを定義するだけで環境が作れるよ。
  • docker compose up -dで起動、docker compose psで状態確認ができるよ。
  • ターミナルからはdocker exec -itでpsql接続、GUIツールはlocalhost:5432で接続できるよ。
  • Volumeを使えばコンテナを削除してもDBデータは消えないよ。
  • docker compose down -vでVolumeごと削除すればDBを完全初期化できるよ。

テーブルを作ったら、アクセスログを30分ごとに集計してみましょう。次の記事ではgenerate_seriesとLEFT JOINを使い、データがない時間帯も0件で表示するSQLを試せます。

  • URLをコピーしました!
目次