WSL2 × DockerでPostgreSQL環境を構築し、Pythonで接続確認するまで

Last updated at 2025-11-01Posted at 2025-10-17

1. はじめに

WSL2上に構築したDocker環境を活用して、PostgreSQLコンテナを立ち上げ、VSCode（Python）から接続確認するまでの手順を整理します。
本記事は、データ分析環境の基盤構築を目的としています。特に、JSONデータをPostgreSQLに保存・加工・分析する準備として、環境構築の最終確認までを扱います。
Docker Engineの構築手順については、以下の記事をご参照ください：

なぜ WSL2 × Docker × PostgreSQL 構成にしたか

Docker
- Dockerを使って構築してみたかった
- docker-compose.yml による構成管理で、環境の再構築が1コマンドで完了する
PostgreSQL
- JSONB型やON CONFLICT句など、構造化・重複除外・加工に強いRDBMS
- 半構造化データを、加工・分析可能な形で蓄積できる
業務で使用しており学習コストが無駄にならない

2. 前提条件

WSL2 + Docker Engineが構築済みであることを前提とします：

WSL2（Ubuntu）環境が構築済み
Docker EngineがWSL2上で動作している
VSCodeがインストール済み（WSL拡張あり）
Python環境が整っている（pipが使える）

確認コマンド例：

docker --version
python3 --version
pip3 list

3. docker-compose.yml の作成と起動

プロジェクトルートに以下のdocker-compose.ymlを作成します：

services:
  postgres:
    build: .  #Dockerfileの場所を指定
    container_name: postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: your_pass
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=ja_JP.UTF-8"
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

コンテナを終了するたびにデータが揮発してしまわないように、DBファイルのパス(/var/lib/postgresql/data)をvolumeにマウントして永続化します
環境変数について
- POSTGRES_PASSWORD
  必須項目。スーパーユーザのパスワード。練習用なら、これだけ設定しとけば十分
- POSTGRES_USER
  スーパーユーザのユーザ名。指定しなかった場合はデフォルトpostgresになる
- POSTGRES_DB
  デフォルトで作成されるDB名。指定しなかった場合はデフォルトpostgresなる
- POSTGRES_INITDB_ARGS:ロケール指定
  - --encoding=UTF8：日本語を含む多言語に対応
  - --locale=ja_JP.UTF-8：日本語の照合順・日付表記に対応
5432:5432 でローカルから接続可能

docker-compose.ymlと同じ場所に、Dockerfileを作成し下記のように設定します。

FROM postgres:16

RUN apt-get update && \
    apt-get install -y locales && \
    sed -i -e 's/# ja_JP.UTF-8 UTF-8/ja_JP.UTF-8 UTF-8/' /etc/locale.gen && \
    locale-gen

ENV LANG=ja_JP.UTF-8
ENV LANGUAGE=ja_JP:ja
ENV LC_ALL=ja_JP.UTF-8

postgresqlのバージョンは16を利用して作成しました
locale-genにより ja_JP.UTF-8を有効化

起動コマンド

docker compose up -d --build  # Dockerfileを使ってビルド＆起動

起動確認

docker compose ps

コンテナ名が postgres で起動していれば成功です。

4. PostgreSQLへの初期接続確認（psql）

コンテナに入って psql で接続確認します：

docker exec -it postgres psql -U postgres -d postgres

datacollateとdatctypeの設定値が反映されていることを確認します。

postgres=# 
SELECT datcollate, datctype
FROM pg_database
WHERE datname = CURRENT_DATABASE();

※PostgreSQL 16以降では SHOW lc_collate や SHOW lc_ctype が使えなくなりました

テーブル作成例

postgres=# 
CREATE TABLE watched_history_raw (
    id SERIAL PRIMARY KEY,
    title_url TEXT NOT NULL,
    watched_at TIMESTAMP NOT NULL,
    raw_json JSONB NOT NULL,
    UNIQUE(title_url, watched_at)
);

この構成では：

title_url + watched_at を重複除外キーとし
raw_json に元データ（履歴JSON）を保持します
分析用の加工テーブルは別途設計予定です

psqlクライアントの終了

postgres=# \q

この操作により、

psqlクライアントが終了し、PostgreSQLとの接続が切断されます
コンテナ内で psqlを起動していた場合は、シェル（bash）に戻ります

5. Pythonで接続確認

PythonからPostgreSQLに接続するには、psycopg2-binary をインストールします：

pip3 install psycopg2-binary

接続確認コード

src/connect_postgres.py

import psycopg2

conn = psycopg2.connect(
    dbname="postgres",
    user="postgres",
    password="your_pass",
    host="localhost",
    port="5432"
)

cur = conn.cursor()
cur.execute("SELECT tablename FROM pg_tables WHERE schemaname='public'")
print(cur.fetchall())

cur.close()
conn.close()

テーブルが表示されれば接続成功です

6. おわりに

本記事では、WSL2上のDocker Engineを活用してPostgreSQL環境を構築し、VSCode（Python）から接続確認するまでの手順を整理しました。
次回は、JSONデータを1件ずつ挿入し、重複除外・加工テーブル設計・WordCloud分析などに展開していく予定です。