DockerでPostgreSQL環境構築【docker-compose対応】

はじめに

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

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

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

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

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

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

• OSにPostgreSQLの設定ファイルが散らばらない。（環境が汚れない）
• docker compose up の一コマンドで起動・停止が完結する。
• チームメンバーと同じ docker-compose.yaml を共有するだけで環境が揃う。
• 「やっぱりバージョン変えたい」という時にイメージ名を書き換えるだけで対応できる。

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

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

今回は以下の構成でPostgreSQL環境を作ります。「最小構成」と書きましたが開発用途には十分な構成です。

alpineとは超軽量なLinuxディストリビューションです。多くのDocker公式イメージがAlpineベースをよく出しています。イメージのダウンロードが速い、コンテナ起動が速いため今回は通常のPostgreSQLではなくalpine版で構築しています。

完成後にできること

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

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

Dockerとは何か（仮想マシンとの違い）

Dockerは「コンテナ型仮想化技術」を使ったアプリケーション実行環境です。仮想マシン（VMwareやVirtualBoxなど）と混同されることが多いのですが、動作の仕組みが根本的に違います。

開発用DBを動かすくらいであればDockerコンテナの軽さと手軽さがとてもよく合います。

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

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

• イメージ
  アプリケーションの「設計図」です。PostgreSQL公式イメージにはPostgreSQLが動くために必要なものがすべて詰まっています。
• コンテナ
  イメージを実際に起動した「実行中の箱」です。イメージ1つから何個でもコンテナを作れます。
• Docker Compose
  複数のコンテナをまとめて定義・管理するためのツールです。docker-compose.yaml に設定を書いておけば、コマンド一発で環境が立ち上がります。

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

なぜ開発用DBはDockerで動かすのが定番なのか

現場のSEやバックエンドエンジニアの間では次の理由から開発用DBをDockerで動かすのがすっかり当たり前になってい、るようです。今まで使ってなかったやつがここにいますが。

1. 環境の再現性が高い
   docker-compose.yamlさえあれば誰がどのPCで動かしても同じDB環境になります。
2. 本番環境と切り離せる
   ローカルのDBを壊しても本番には一切影響しません。
3. 複数バージョンの共存が簡単
   例えばPostgreSQL 14と15を同時に動かすこともコンテナを分ければ簡単に可能です。

開発環境の準備（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）が必要になる場合があります。インストーラが案内してくれるので指示に従って有効化してください。

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

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

docker --version

# 以下実行結果
Docker version 29.2.1, build a5c7197


# または


docker compose version

# 以下実行結果
Docker Compose version v5.0.2

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

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

今回使用するdocker-compose.yaml（最小構成）

作業用のディレクトリを1つ作り、その中に以下の内容で docker-compose.yaml を作成します。

services:
  postgres:
    image: postgres:16-alpine
    container_name: postgres16
    restart: unless-stopped

    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppassword
      POSTGRES_DB: appdb
      TZ: Asia/Tokyo

    ports:
      - "5432:5432"

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

volumes:
  postgres16:

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

docker-compose.yamlの各設定内容

image

Docker Hub上の公式PostgreSQLイメージを指定しています。postgres:16 と書けばPostgreSQL 16系の最新パッチバージョンが自動的に使われます。postgres:latest と書いてしまうと将来的に意図しないメジャーバージョンアップが起きることがあるため、バージョンを明示するのがおすすめです。

今回は公式イメージの Alpine Linuxベースの軽量版 を選びました。通常の postgres:16 と比べるとこんな感じです。

container_name

コンテナに名前をつけておくと docker stop postgres16 のように名前で操作できて便利です。省略するとランダムな名前が自動生成されます。

restart

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

ports

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

environment

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

volumes

ボリューム名:ボリュームのパス の形式で書きます。この設定を行わないとコンテナを削除した際にDBのデータも削除されてしまいます。

Dockerが管理するボリューム内（ここではpostgres16） にデータが保存されるようになり、コンテナを削除してもデータは消えなくなります。

なお、ボリュームパスに /var/lib/postgresql/data を指定していますが、これは公式PostgreSQLイメージが参照しようとするパスのようなので変更しないほうがいいみたいです。

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欄が running または Up と表示されれば起動しています。

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

Docker daemonが起動していない

Error response from daemon: ...

Docker Desktopが起動していない場合に発生します。タスクバー（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” のように変更してください。

docker-compose.yml のスペルミス

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

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

ホストのターミナルからコンテナ内のpsqlを実行する方法

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

docker exec -it postgres16 psql -U appuser -d appdb

# 以下実行結果
psql (16.13)
Type "help" for help.

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

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

接続情報（ホスト・ユーザー・DB名）

GUIツールはSQL補完や視覚的なER図表示ができて便利です。A5:SQL Mk-2やDBeaverは無料で使えるのでおすすめです。

データを永続化する仕組み（Volume）

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

Dockerコンテナはそのままでは「使い捨て」です。コンテナを削除するとその中のデータもすべて消えてしまいます。これを防ぐのがDocker Volumeの役割です。

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

Docker Volume「pgdata」の仕組み

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

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

Volumeの実体はホストマシン上のDockerが管理する領域に保存されます。場所を直接気にする必要はほとんどありませんが、docker volume inspect pgdata で確認できます。

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

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

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

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

コンテナを停止する

docker compose stop

コンテナを停止しますがコンテナ自体は残ります。次回は docker compose start で再開できます。

コンテナを再起動する

docker compose restart

設定変更を反映したいときや、コンテナの動作がおかしいと感じたときに使います。

コンテナを削除する

# コンテナのみ削除（Volumeは残る）
docker compose down

# コンテナとVolumeをまとめて削除（DBデータも消える）
docker compose down -v

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

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

メリット

• 環境が汚れない
  PostgreSQLの設定ファイルや依存ライブラリがOS上に散らばらない。
• 再現性が高い
  docker-compose.yaml を共有するだけでチーム全員が同じ環境を作れる。
• バージョン切り替えが楽
  イメージ名を変えるだけで複数バージョンを使い分けられる。
• 破棄が簡単
  docker compose down 一発でDB環境ごと削除可能。

デメリット

• Dockerの概念を覚える必要がある
  コンテナ・イメージ・Volumeなど、最初に学習コストがかかります。筆者のようにあたふたすることも。
  今回は登場しませんでしたが、すこし込み入った使い方をしたい場合は Dockerfile というもうちょっと覚えるものが増えてしまいます。
• Docker Desktop自体のリソースを消費する
  特にWindowsではメモリをそれなりに使います。
• 本番との差異に注意
  本番環境がDockerでない場合、環境差異が生まれる可能性があります。

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

まとめ：開発用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を完全初期化できるよ。

Docker初心者が次に覚えると良いこと

Dockerに慣れてきたら、次のステップとして以下を覚えると開発がさらに楽になります。

• Dockerログ確認
  docker compose logs -f db でPostgreSQLのログをリアルタイム確認できます。エラーの原因特定に役立ちますよ。
• コンテナネットワーク
  バックエンドアプリのコンテナとDBコンテナを同じネットワークに置くことで、アプリ側から db という名前でPostgreSQLに接続できるようになります。
• DB初期化SQLの自動実行
  docker-compose.yaml でマウントする設定を追加すると、コンテナ初回起動時にSQLファイルを自動実行してテーブル作成などができます。