Docker ComposeでPostgreSQLコンテナを作成する

本日(2026年4月14日)の進捗は以下の通りです。

• Docker Compose上でPostgreSQLコンテナの作成に成功
• ローカルPCからコンテナにアクセスし、VSCodeからSQLのクエリの実行に成功

また、本記事の構成は、作業内容に基づいて以下のようにします。

1. compose.yamlファイルの作成
2. dockerコンテナの実行
3. ローカルPCからPostgreSQLコンテナに接続
4. VSCodeからクエリを実行

Docker ComposeにしてもPostgreSQLにしても、初めての事ばかりでした。なので、折角覚えたことをとりこぼさないように、一旦ここまでで出てきた内容を自分用にアウトプットしたいと思います。

この記事は自分用に執筆しておりますので、見づらい点が多々あります点ご了承下さい。

compose.yamlファイルの作成

作業内容

まずは、compose.yamlファイルにPostgreSQLのイメージをビルドするための記述を追加しました。

compose.yaml

services:
  db:
    image: postgres:16-alpine
    restart: always
    # set shared memory limit when using docker compose
    shm_size: 128mb
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_volume:/var/lib/postgresql/data
    ports:
      - "5432:5432"
volumes:
  postgres_volume

解説

compose.yamlファイルの内容の解説。

• image: postgres:16-alpine
  • PostgreSQLのバージョン16の、軽量バージョンを指定
• shm_size: 128mb
  • コンテナが利用できる**共有メモリ(Shared Memory)**のサイズを指定する設定
  • メモリ領域の確保:PostgreSQLが複数のプロセス間で高速にデータをやり取りするために使用するメモリ領域の容量を定義している
  • デフォルト制限の回避:Dockerのデフォルト設定は多くの場合64MBで、複雑なクエリを実行した際にメモリ不足でエラーが発生することがあるため、余裕を持たせるために128MB以上に拡張するのが一般的である
• environment
  • PostgreSQLを使用するために必要な、ユーザー名やパスワードを定義している
  • compose.yamlファイルに直接書かず、同じディレクトリの.envファイルから読み込ませることで漏洩リスクを回避する
• volumes
  • データの永続化:downでコンテナを消してもデータを残しておくために、ホストPCのディレクトリ(またはDockerボリューム)とコンテナを紐づけている
• ports
  • ローカルPCのポート:コンテナのポート で接続を定義している
  • ホストPCのGUIツール(VSCodeなど)から接続するために必要な設定

dockerコンテナの実行

作業内容

composeファイルを編集した後、dockerイメージをビルドし、コンテナを動かすために以下のコマンドを実行した。

$ docker compose up -d

一度実行したコンテナを削除して作り直すには、以下のコマンドを実行する。

$ docker compose down

そして、またdocker compose upコマンドを実行する。

解説

dockerコマンドに関しておさらい。

$ docker compose up

compose.yamlファイルから、イメージをビルドしてコンテナを起動するためのコマンド。

-dフラグを付けなかった場合、コンテナはフォアグラウンドで実行され、サーバーのログがリアルタイムで表示され続ける。

一方、-dを付けると、コンテナはバックグラウンドで実行され、ターミナルの操作が引き続き可能になる。

$ docker compose down

作成したコンテナ自体を完全に削除するコマンド。
compose.yamlの内容を編集し、docker compose upをやり直したい時は、その都度このコマンドを実行している。

$ docker compose stop

docker compose up -dで、-dフラグを付けてコンテナを起動した時に、そのコンテナを止めたいと思った時に実行するコマンド。

サービスを一旦終了させるが、設定やデータは保持される。次にupした時は最初から起動する。

stopで留めたサービスを再開したい時は、docker compose startを実行する。

ローカルPCからPostgreSQLコンテナに接続

作業内容

次は、いよいよローカルPCからdockerコンテナ上のPostgreSQLに接続した。

$ docker compose exec db psql -U <POSTGRES_USER> -d <POSTGRES_USER>

コマンドを実行したところ、ローカルPCのターミナルからPostgreSQLに接続できたことが確認できた。

解説

コマンドの内容について

• docker compose exec
  • docker compose upで起動中のコンテナ内で、新たなコマンドを一時的に実行するためのサブコマンド
  • docker compose exec <service name> bashでコンテナ内部に入れる(<servise name>は今回はdb)
• psql
  • PostGreSQLにCLIでログインするためのSQLコマンド
  • -Uでユーザ名、-dでデータベース名、-hでホスト名(localhost等)を指定

VSCodeからクエリを実行

作業内容

ターミナルからSQLコマンドを叩くよりも、VSCodeの拡張機能を使用した方が、補完機能等もあって遥かに作業がしやすい。
docker compose upでサービスを起動させたのち、VSCodeにて以下の手順を踏んだ。

• PostgreSQL拡張機能を追加
  • これでVSCodeからデータベースにアクセス可能になる
• コンテナ上のPostgreSQLに接続
  • VSCodeの左側に"Database"アイコンが表示されるのでクリックし、Create Connectionをクリック
  • Nameは任意の接続名を入力、その他必要な情報を入力してSaveボタンをクリック

接続に成功したのち、試しに少しだけSQLのクエリ文を作って、実行してみた。

VSCodeでSQLに接続した後、論理データベースの中にQueryという名前のディレクトリがあるので、そこにqueryファイルを作成。

そこへSQL文を書いてRunをクリックすると、データベースが操作できる。

結果

無事、Docker Composeのコンテナ上にて、PostgreSQLを使用することができる環境を作ることができました。

downを実行しても、登録したデータが消えなかったので、データの永続化にも成功しています。

今後は、SQLの扱い方について覚えたり、PostgreSQLを使ったアプリケーションの開発に取り組んでいきたいと思います。