こんにちは。テックリードの私だ。
開発現場において、データベースのGUIクライアント選定と環境構築は、チーム全体の生産性を左右する極めて重要なファクターだ。「新しいPCに変えるたびに接続設定が吹き飛ぶ」「チームメンバーごとに異なるバージョンのクライアントを使っていて挙動が違う」「ローカルのPostgreSQLに繋がらないと嘆く若手が続出する」――そんな不毛な時間に別れを告げよう。
今回は、Docker環境でpgAdmin 4をサクッと立ち上げ、ローカルのPostgreSQLコンテナとシームレスに連携させる方法を解説する。単にコンテナを上げるだけではない。プロの開発現場で即座に使える、設定の永続化、ネットワークブリッジの極意、そして開発スピードを爆発的に高める実践知を余すところなく伝授しよう。
—
1. 为什么是 Docker + pgAdmin 4 ？（なぜDocker版なのか）
デスクトップアプリ版のpgAdmin 4を直接OSにインストールするのは、今やアンチパターンだと言っていい。バージョンアップのたびに挙動が変わり、MacとWindowsで微妙に動作が異なる地獄を生み出す。
Dockerでコンテナ化するメリットは以下の3点に集約される。
1. 環境の完全なポータビリティ: `docker-compose up` の一発で、チーム全員の環境に全く同じpgAdminが立ち上がる。
2. ホストOSの汚染防止: アンインストールも `docker-compose down -v` で一瞬。ゴミを残さない。
3. ネットワークの完全制御: 同一Dockerネットワーク上のPostgreSQLコンテナへ、コンテナ名（サービス名）ベースで名前解決しながら安全に接続できる。
—
2. 実践！本番クオリティの `docker-compose.yml`
まずは、実務でそのまま使える堅牢な `docker-compose.yml` を提示する。セキュリティ、データの永続化、ヘルスチェックの観点を盛り込んだベストプラクティス構成だ。
version: ‘3.8’
services:
# —————————————————————–
# PostgreSQL Database Service
# —————————————————————–
postgres:
image: postgres:15-alpine
container_name: pg_local_db
restart: unless-stopped
environment:
POSTGRES_USER: app_user
POSTGRES_PASSWORD: secure_password123
POSTGRES_DB: app_development
ports:
- “5432:5432”
volumes:
- pgdata:/var/lib/postgresql/data
# 初期化スクリプトを配置したい場合はここにマウント
# – ./init:/docker-entrypoint-initdb.d
networks:
- db-net
healthcheck:
test: [“CMD-SHELL”, “pg_isready -U app_user -d app_development”]
interval: 5s
timeout: 5s
retries: 5
# —————————————————————–
# pgAdmin 4 Service
# —————————————————————–
pgadmin:
image: dpage/pgadmin4:7.8
container_name: pg_local_admin
restart: unless-stopped
environment:
PGADMIN_DEFAULT_EMAIL: admin@example.com
PGADMIN_DEFAULT_PASSWORD: admin_secure_password
# セッションタイムアウトの設定（秒）: デフォルトは短いので長めに調整（例: 24時間）
PGADMIN_CONFIG_SESSION_EXPIRY_TIME: 86400
# サーバーモードで複数のユーザースペースを分離する場合に設定
PGADMIN_CONFIG_SERVER_MODE: ‘True’
ports:
- “5050:80”
volumes:
# pgAdminの設定やサーバー定義を永続化（これが消えると設定が吹き飛びます）
- pgadmin-data:/var/lib/pgadmin
# チームで共有するサーバー定義JSONをマウントする場合（後述）
# – ./servers.json:/pgadmin4/servers.json
networks:
- db-net
depends_on:
postgres:
condition: service_healthy
volumes:
pgdata:
driver: local
pgadmin-data:
driver: local
networks:
db-net:
driver: bridge
この設定のキモ（プロの知見）
- `depends_on` と `healthcheck` の組み合わせ: 単に `depends_on: – postgres` と書くだけでは、PostgreSQLプロセスが起動しただけで、コネクションを受け付ける準備（データベースの初期化完了）ができていないうちにpgAdminが立ち上がり、接続エラーで慌てる原因になる。`healthcheck` を挟むことで、DBが完全に受付可能になってからpgAdminを起動させることが可能だ。
- ボリュームのマウント (`pgadmin-data`): pgAdmin内の接続情報やクエリ履歴は、コンテナ内（`/var/lib/pgadmin`）に保存される。ここを名前付きボリュームで永続化しておかないと、コンテナを再作成した瞬間にすべてが消滅する。
—
3. チーム開発で爆速共有！ `servers.json` による自動プロビジョニング
「Dockerで立ち上がったのはいいけれど、毎回ポチポチとホスト名、ポート、ユーザー名、パスワードを入力してサーバー登録するのは面倒くさい」――その通り。プロのプロジェクトでは、サーバー接続情報をJSONで定義し、コンテナ起動時に自動でインポートさせる。
プロジェクトのルートディレクトリに `servers.json` を配置しよう。
{
“Servers”: {
“1”: {
“Name”: “Local-Postgres-Docker”,
“Group”: “Development Servers”,
“Host”: “postgres”,
“Port”: 5432,
“MaintenanceDB”: “app_development”,
“Username”: “app_user”,
“PassFile”: “/pgadmin4/pgpass”,
“SSLMode”: “prefer”,
“Color”: “#336791”
}
}
}
> テックリードのワンポイント:
> `Host` に注目してほしい。`localhost` ではなく、Dockerのネットワーク上のサービス名である `postgres` を指定している。これにより、コンテナ間の名前解決が確実に行われる。
さらに、パスワードをハードコードせずに安全に渡すために、パスファイル（`pgpass`）を組み合わせるか、環境変数経由で自動読み込みさせる設定を `docker-compose.yml` の `volumes` に追加することで、開発者はブラウザを開いた瞬間から、一切の手間なくデータベースを叩き始めることができる。
—
4. 開発スピードを劇的に高める pgAdmin 4 の実践テクニック
無事にpgAdminが起動したら（ブラウザで `http://localhost:5050` にアクセス）、以下のテクニックを駆使して作業効率を極限まで高めてほしい。
① 隠れたキーボードショートカット
GUIツールはマウスに手を伸ばした瞬間から生産性が落ちる。クエリツールを開いたら、以下のショートカットを指に覚え込ませろ。
- F5: クエリの実行（選択範囲のみ実行も可能）
- Shift + Alt + Up / Down: 行の複製
- Ctrl + Space: SQLのオートコンプリート（補完候補の表示）
- Ctrl + Shift + U: 選択範囲を大文字に変換
② 巨大なダンプデータのインポート・エクスポートはGUIを使うな
数GBある本番のバックアップデータをpgAdminのGUI経由でインポートしようとすると、ブラウザのタイムアウトやメモリ不足で絶望する。GUIはあくまで「確認・軽微な修正・アドホックなクエリ実行」用と割り切れ。
データ移行やバックアップは、Dockerコンテナに対して直接CLIから叩くのがプロの鉄則だ。
コンテナ内へのデータインポート（例）
docker exec -i pg_local_db psql -U app_user -d app_development < backup.sql
バックアップのエクスポート
docker exec -t pg_local_db pg_dump -U app_user app_development > backup.sql
—
5. まとめ
Docker環境でのpgAdmin 4の構築は、単なる「ツールを入れる作業」ではない。チーム全員の開発環境を完全に同期させ、オンボーディングコストをゼロにするための重要なインフラ設計である。
今回紹介した `docker-compose.yml` をあなたのプロジェクトのルートに放り込み、`docker-compose up -d` を叩いてみてほしい。その瞬間に、環境差異というエンジニアの永遠の敵から解放されるはずだ。
さあ、エディタを開き、最高のクエリを書こう。