「ローカルにPostgreSQLをインストールしたら他の開発環境と設定が干渉してしまった……」「OSが違うと手順がバラバラになってしまった……」ということ、ありますよね。
実はこの問題、Dockerを使うとほぼ解消できます。数行の設定ファイルを書くだけで、環境汚染なし・チーム間で再現性のある開発用PostgreSQL環境が数分で立ち上がりますよ。
筆者はもともとDockerを使ったことがありませんでした。この記事ではそんなDocker超初心者でも構築できた、インストールから接続確認まで順を追って解説します。
Docker Composeを使えばdocker-compose.yamlを作成してdocker compose up -dを実行するだけでPostgreSQLの開発環境を起動できます。この記事ではPostgreSQL 16を例にVolumeによるデータ永続化とpsql・GUIツールからの接続確認まで進めます。
この記事は以下の環境で動作を確認しています。
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」というアプリをインストールするのが最短ルートです。
- Docker公式サイトにアクセスします。
- OSに合わせたインストーラをダウンロードします。
- インストーラを実行し、指示に従ってDocker Desktopをセットアップします。
- Docker Desktopを起動します。
- タスクバーまたはメニューバーにクジラのアイコンが表示されれば起動完了です。
SQL Server の環境構築も同じ流れで進められます。Docker Desktop のセットアップが済んでいれば、以下の記事もあわせて参考にしてみてください。

Dockerが正常に動いているか確認する
インストール後ターミナル(PowerShellまたはTerminal.app)で以下のコマンドを実行し、バージョンが表示されれば準備完了です。
docker --versionDocker 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へ保存します。
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:16 | postgres:16-alpine | |
|---|---|---|
| ベースOS | Debian | Alpine 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 psNAME 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/tcpSTATUS欄が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」を選択し、以下の情報を入力します。
| 項目 | 値 |
|---|---|
| Host | localhost |
| Port | 5432 |
| 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の仕組み
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 down | Volumeは残る |
| 削除(データも消す) | 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や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を試せます。


