PostgreSQL の文字コードとは、データベースが文字をどのバイト列で保存し、どう数えるかを決める設定です。

  • PostgreSQL の文字コードとタイムゾーンを確かめる命令(SHOW server_encoding;・\l・SHOW timezone;)
  • initdb・createdb・pg_ctl のどこで文字コードとタイムゾーンが決まり、どこで直せるか
  • 使い捨てのテスト用 DB を手元に立てた時、当社の AI の席が実際に踏んだ赤(SQL_ASCII・9 時間のずれ・ソケット・ポート)と直し方(社の実測 2026-10-02〜2026-11-11)

当社は、結合試験のための使い捨ての PostgreSQL を、AIエージェントの席(開発の席)に自分で立てさせて試験を回しています。この頁は、PostgreSQL の公式の文書に書いてある文字コードとタイムゾーンの決まりを、その道で当社が実際に赤を出した記録と並べたものです。

PostgreSQL の文字コードの確認方法:SHOW server_encoding と \l

いま接続している DB の文字コードは、psql で次のように確かめます。\l は、クラスタの全部の DB を、文字コード(Encoding)と照合順序(Collate)の列つきで一覧にします(公式の文書)。

-- 接続中の DB の文字コード
SHOW server_encoding;

-- 全部の DB の文字コード・照合順序の一覧(psql のメタコマンド)
\l

-- 接続中のセッションのタイムゾーン
SHOW timezone;

試験の前に見るべき所は次です。server_encoding が UTF8 であること、TimeZone が CI と同じ(当社は UTC)であることです。

文字コードはいつ決まるか:initdb の既定と、createdb の -E・-T template0

文字コードは、クラスタを作る initdb の時に既定が決まります。initdb の -E(--encoding)を付けなければ、既定の文字コードはロケールから導かれます(公式の文書 initdb)。ロケールが C(LC_ALL=C)だと、既定は SQL_ASCII になります。

SQL_ASCII は他の文字コードと扱いが違います。公式の文書は、SQL_ASCII ではサーバが 0〜127 のバイトを ASCII として扱い、128〜255 のバイトは解釈せず、文字コードの変換も検査もしない、そのため非 ASCII のデータを扱う時に SQL_ASCII を使うのは賢明でない、と書いています(公式の文書 Character Set Support)。

DB ごとの文字コードは createdb(CREATE DATABASE の包み)の -E で決めます。既定の雛形の template1 と違う文字コード・ロケールで作る時は、-T template0 を指します(公式の文書 createdb・Character Set Support)。

決める所命令何が決まるか付けないと
クラスタを作る時initdb -E UTF8 --locale=C以後に作る DB の既定の文字コード・ロケール環境のロケールから導かれる(C なら SQL_ASCII)
DB を作る時createdb -E UTF8 -T template0 --locale=C <db>その DB の文字コード・ロケール雛形(template1)と同じになる
作った後に確かめるSHOW server_encoding;・\l(確かめるだけ)—

出典: PostgreSQL 公式の文書「initdb」「createdb」「Character Set Support」(2026-11-15 に確認)。

PostgreSQL のタイムゾーン:initdb が機体の時間帯を書き込む

TimeZone は、時刻を表示・解釈する時の時間帯の設定です。公式の文書は、組み込みの既定は GMT だが、ふつうは postgresql.conf で上書きされ、initdb がその機体の環境に合う設定をそこへ書き込む、と書いています(公式の文書 runtime-config-client)。つまり、日本の時間帯の Mac で initdb すると、何も言わなければサーバの既定は JST 側になります。

TimeZone は置く場所で効く範囲が変わります。

置き場命令の例効く範囲
サーバを起こす時pg_ctl -o "-c timezone=UTC" startそのサーバの既定(pg_ctl の -o は postgres へそのまま渡す引数)
DB ごとALTER DATABASE <db> SET timezone TO 'UTC';その DB へ新しく繋いだセッション
セッションごとSET timezone TO 'UTC';そのセッションだけ

出典: PostgreSQL 公式の文書「pg_ctl」「Client Connection Defaults(TimeZone)」(2026-11-15 に確認)。

使い捨てのテスト用 DB を立てる手順(initdb から pg_ctl・createdb まで)

当社が下の記録を踏んだ後に揃えた形です。道・ポート・DB の名前は置き換えて読んでください。

# 1. 版と拡張の揃った道を、PATH に頼らず道ごと指す
PGBIN=/opt/homebrew/opt/postgresql@17/bin

# 2. 空いているポートを自分で引き、撃つ前に空きを測る(何も出なければ空き)
PORT=<空いているポート>
lsof -iTCP:$PORT

# 3. クラスタを UTF8 で作る
$PGBIN/initdb -D "$DATA" -E UTF8 --locale=C -U postgres

# 4. UTC・TCP だけで起こす(unix ソケットを作らない)
$PGBIN/pg_ctl -D "$DATA" -l "$DATA/server.log" \
  -o "-p $PORT -c timezone=UTC -c unix_socket_directories='' -c listen_addresses=localhost" start

# 5. DB を UTF8 で作り、文字コードとタイムゾーンを確かめる
$PGBIN/createdb -h localhost -p $PORT -U postgres -E UTF8 -T template0 --locale=C testdb
$PGBIN/psql -h localhost -p $PORT -U postgres -d testdb -c 'SHOW server_encoding' -c 'SHOW timezone'
段何を防ぐか当社で起きた日
1. 道ごと指すPATH の先頭の別の版の initdb に拡張(pgvector)が無い2026-10-02
2. ポートの空きを測る他の席の postgres に気づかず台本を撃つ・他の席の DB を消す2026-10-02・2026-10-06
3・5. UTF8 で作るSQL_ASCII で日本語が列の長さを超える2026-11-07
4. timezone=UTC で起こす時刻の試験が 9 時間ずれる2026-11-09・2026-11-11
4. TCP だけで起こすmacOS でソケットの道が長すぎて起動しない2026-10-02・2026-11-11

出典: 社の実測(日付は各行)。

当社の記録:LC_ALL=C の initdb で SQL_ASCII になり、結合試験 49 件が赤

手元の試験で、使い捨ての PostgreSQL を LC_ALL=C initdb で起こしたところ、DB の文字コードが SQL_ASCII になりました。日本語が VarChar の長さを超え、結合試験 49 件が「too long for the column」で赤になりました(社の実測 2026-11-07)。

createdb -E UTF8 -T template0 --locale=C で作り直すと、236 件が全部緑になりました。コードの欠陥ではありませんでした(社の実測 2026-11-07)。SQL_ASCII はバイトを解釈しないので、日本語の 1 文字が 1 文字として数えられず、列の長さの上限に早く届いたと当社は読んでいます。

当社の記録:時刻の試験が 9 時間ずれた(pg_ctl と initdb の 2 回)

1 回目は、使い捨ての PG を pg_ctl で機体の時間帯(JST)のまま起こした時です。時刻を扱う試験 34 本・70 件が 9 時間ずれて赤になりました。node に TZ=UTC を渡すだけでは足りず、pg_ctl -o "-c timezone=UTC" で起こすと 253 件が全部緑になりました(社の実測 2026-11-09)。

2 回目は、Homebrew の postgresql@17 を initdb して建てた手元の DB です。結合試験 226 本を流すと 15 本(31 件)が赤で、時刻の比較が約 9 時間ずれていました。原因は DB の timezone が機体の JST だった事で、CI は UTC です。ALTER DATABASE <db> SET timezone TO 'UTC' で、15 本 187 件が全部緑になりました(社の実測 2026-11-11)。変更前の main の素の状態でも同じ失敗の集合が出たので、変更の回帰ではありませんでした(社の実測 2026-11-11)。

どちらも、試験を流す側の時間帯ではなく、DB の側の TimeZone が CI と違っていた形です。上の表の「サーバを起こす時」か「DB ごと」のどちらかで UTC に揃えます。

macOS でソケットの道が長すぎて pg_ctl が起きない

macOS では作業の道が長く、unix ソケットの道が 103 バイトを超えて、pg_ctl が起動しませんでした(社の実測 2026-10-02・2026-11-11)。unix_socket_directories='' でソケットを作らせず、listen_addresses=localhost で TCP だけで立てて通しました(社の実測 2026-10-02・2026-11-11)。この形で立てた DB へは、psql も試験も -h localhost と ポートで繋ぎます。

ポートの取り違えで、他の席の DB に触れた

ポート 55432 に、止まった別の席が残した postgres が居ました。自分の pg_ctl は起動に失敗し、それに気づかないまま、他の席の DB に準備の台本を撃ちました(消してはいません)。同じ日、PATH の先頭の pg16 の initdb には pgvector が無く、拡張が見つかりませんでした(社の実測 2026-10-02)。そこで、撃つ前に lsof -iTCP:<port> で空きを測る事と、/opt/homebrew/opt/postgresql@17/bin の initdb と pg_ctl を道ごと指す事を決めました(社の実測 2026-10-02)。

その 4 日後、別の席が使い捨て PG を作る時にポートを取り違え、さらに別の席の使い捨て DB を DROP しました(本番ではありません)。再発を防ぐ決まりは、空いているポートを自分で引いて作る事と、DROP の前にそれが自分の作った DB かを確かめる事です(社の実測 2026-10-06)。使い捨て DB のつもりで他人の試験 DB に SQL を当てた話は、prisma migrate の頁にも書いています。

手元の赤を「直しの赤」と切り分ける

上の赤は、どれもコードの直しとは関係の無い、手元の DB の立て方の赤でした。当社は、手元で赤が出たら次の 2 つのどちらかで切り分けます(社の実測 2026-11-07・2026-11-09)。

  • 変更前の main で、同じ式を撃つ(対照)。同じ失敗の集合が出れば、直しの赤ではない
  • DB を UTF8・UTC で起こし直して、もう一度流す

そして、赤の本文(「too long for the column」や、ずれた時刻の値)を読むまで原因を決めつけません(社の実測 2026-11-07・2026-11-09)。CI でだけ揺れる赤の見分け方は flaky test の頁に、本番の控えの取り方は pg_dump の頁にまとめています。

よくある質問

PostgreSQL の文字コードを確認するには?

psql で SHOW server_encoding; を撃つと、接続中の DB の文字コードが出ます。\l を撃つと、全部の DB の文字コードと照合順序が一覧で出ます(PostgreSQL 公式の文書)。

SQL_ASCII の DB を UTF8 に変えられる?

文字コードは DB を作る時に決まるので、createdb -E UTF8 -T template0 で UTF8 の DB を作り直します。当社の使い捨ての試験 DB はこれで作り直し、236 件が全部緑になりました(社の実測 2026-11-07)。

PostgreSQL のタイムゾーンを UTC にするには?

サーバの既定なら postgresql.conf か pg_ctl -o "-c timezone=UTC"、DB ごとなら ALTER DATABASE <db> SET timezone TO 'UTC'、セッションだけなら SET timezone TO 'UTC' です。確かめるのは SHOW timezone; です(PostgreSQL 公式の文書)。

initdb のタイムゾーンはどこから来る?

initdb が、その機体の環境に合う TimeZone を postgresql.conf に書き込みます(PostgreSQL 公式の文書)。日本の時間帯の機体で建てた DB は JST 側になり、UTC の CI と時刻の比較が約 9 時間ずれる事があります(社の実測 2026-11-11)。

pg_ctl が macOS で起動しないのは?

当社の場合は、作業の道が長く unix ソケットの道が 103 バイトを超えていました。unix_socket_directories='' と listen_addresses=localhost で TCP だけで立てて通しました(社の実測 2026-10-02・2026-11-11)。

出典

  1. PostgreSQL Documentation「Character Set Support」https://www.postgresql.org/docs/current/multibyte.html (2026-11-15 に確認)
  2. PostgreSQL Documentation「initdb」https://www.postgresql.org/docs/current/app-initdb.html (2026-11-15 に確認)
  3. PostgreSQL Documentation「pg_ctl」https://www.postgresql.org/docs/current/app-pg-ctl.html (2026-11-15 に確認)
  4. PostgreSQL Documentation「createdb」https://www.postgresql.org/docs/current/app-createdb.html (2026-11-15 に確認)
  5. PostgreSQL Documentation「Client Connection Defaults(TimeZone)」https://www.postgresql.org/docs/current/runtime-config-client.html (2026-11-15 に確認)
  6. 社の実測 2026-10-02・2026-10-06・2026-11-07・2026-11-09・2026-11-11