テストデータを少し入れるだけなら、どの型でも問題なく動くように見えるかもしれません。しかし、注文コードの形式が変わったり、金額を集計したり、海外拠点の時刻を扱ったり、決済レスポンスを検索したりすると、型の違いが表面化します。型を選ぶときは、値を保存できるかだけでなく、保存後にどう使うかまで考えます。

この記事は、SQLの基本を理解し、これからテーブルを設計する方に向けた入門向け記事です。架空の注文管理テーブルordersを例に、文字列、数値、日付時刻、JSONの型を用途別に検討します。型選びに関わる性質と判断理由に絞って説明します。

例では、注文コード、単価、数量、注文日時などを保存します。まずテーブルを定義し、各列の型を用途に照らして確認します。

この最初の定義には、後で見直す候補としてdouble precisionとjsonをあえて含めています。以降の章で、金額の正確さやJSON検索の必要性に応じて、型を変更する条件を確認します。

CREATE TABLE orders (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY -- 注文を一意に識別するID。値はPostgreSQLが自動で採番する。
  , order_code varchar(16) NOT NULL                  -- 注文コード。最大16文字の文字列を必ず入れる。
  , customer_memo text                               -- 顧客からのメモ。業務上の長さ制限を設けず、入力は任意。
  , unit_price numeric(12, 2) NOT NULL               -- 商品1個あたりの単価。全体で12桁、小数点以下2桁。
  , quantity integer NOT NULL                        -- 注文数量。整数値を必ず入れる。
  , total_amount double precision NOT NULL           -- 注文金額の合計。必ず入れる。
  , ordered_at timestamp without time zone NOT NULL  -- 注文日時。必ず入れる。
  , payment_payload json                             -- 決済サービスなどから返されたJSON形式のデータ。
);

1. 文字列型は上限と条件の表し方で選ぶ

1.1. char(n)を選ぶ場面は限られる

注文コードのように形式が決まった文字列には、固定長のchar(n)も候補に見えます。ただし、char(n)は入力が指定した長さに満たない場合、末尾に空白を補います。また、char同士の比較では末尾の空白を無視します。そのため、末尾の空白を値の一部として区別したい列には向きません。

CREATE TEMP TABLE order_code_char (
  code char(5) NOT NULL
);

INSERT INTO order_code_char VALUES ('hi');

SELECT code, char_length(code), octet_length(code), code = 'hi   ', code = 'hi'
FROM order_code_char;
 code  | char_length | octet_length | ?column? | ?column?
-------+-------------+--------------+----------+----------
 hi    |           2 |            5 | t        | t
(1 row)

この例では、'hi'の末尾に3つの空白を補ってchar(5)の幅で保存しています。char_length(code)は末尾の空白を数えないため2を返しますが、octet_length(code)は、このASCII文字列では5を返します。空白を含む'hi 'との比較も、含まない'hi'との比較もtrueです。固定長を指定しても、入力された文字列をそのまま区別して保存できるわけではありません。

性能面でも、char(n)を選ぶ利点はありません。公式文書の「8.3. 文字型」によると、PostgreSQLのchar(n)には固有の性能上の利点がありません。空白埋めで保存領域が増えるため、char(n)、varchar(n)、textの中では通常最も遅い型です。新規設計ではchar(n)を避け、最大長を制限するならvarchar(n)やCHECK制約を検討します。

1.2. varchar(n)は文字数の上限を型に記せる

orders.order_codeには、最大16文字を保存できるvarchar(16)を指定しています。varchar(16)は、char(n)のように後ろに空白文字を補わず、指定した文字列をそのまま保存します。初期の注文コードが次の形式なら15文字なので、後ろに空白文字が付くことなく保存できます。

CREATE TEMP TABLE orders_code_varchar (
  order_code varchar(16) NOT NULL
);

INSERT INTO orders_code_varchar VALUES ('OD-000000000001');

発番側の仕様変更で注文コードに日付が加わると、上限を超える場合があります。次の値は18文字なので、同じ列には保存できません。

INSERT INTO orders_code_varchar VALUES ('OD-20260801-000001');
ERROR:  value too long for type character varying(16)

これはvarchar(n)の長さ制限によるエラーです。公式文書の「8.3. 文字型」では、character varying(n)、つまりvarchar(n)は最大n文字を保存できる型と説明されています。通常の挿入では、超過分がすべて空白の場合を除き、上限を超える入力はエラーになります。ここでいうnはバイト数ではなく文字数です。

varchar(n)を使うときは、現在のデータが収まるかに加えて、上限の根拠を確認します。注文コードの仕様が変わったら、発番側の変更に合わせてデータベース側の上限も見直します。

1.3. 長さの上限は型か制約で表す

注文コードの上限が業務仕様として「最大18文字」と決まっているなら、varchar(18)を使えます。型定義から最大長が分かり、上限を超える入力はデータベースが拒否します。上限を変える場合は、列の型定義を変更します。

文字列型と業務上の条件を分けて定義するなら、textとCHECK制約を組み合わせる方法もあります。CHECK制約は、条件式がFALSEになる値を拒否します。条件式がNULLになる値は通過するため、NULLも拒否する場合はNOT NULL制約を併用します。次の定義では、text型の注文コードをOD-で始まる18文字以下の値に制限しています。

CREATE TEMP TABLE orders_code_text (
  order_code text NOT NULL,
  CONSTRAINT orders_code_format_check CHECK (
    order_code LIKE 'OD-%'
    AND char_length(order_code) <= 18
  )
);

CHECK制約では、長さと接頭辞の条件を同時に定義できます。上限を変えるときは、列の型を維持して制約を変更します。長さだけを型に記すならvarchar(n)、長さを含む業務条件をまとめて管理するならtextとCHECK制約、というように条件の表し方で選べます（CHECK制約）。

この使い分けは、短い文字列にはvarchar(n)、長い文字列にはtextという性能上の区別ではありません。公式文書の「8.3. 文字型」によると、長さ制限の検査や空白埋めの負担を除けば、文字列型の間に性能差はありません。orders.customer_memoのように業務上の長さ制限がない列には、textを使えます。

1.4. 保存できる文字列でもB-treeインデックスに入らない場合がある

長い文字列を保存できることと、その値全体をインデックスのキーにできることは別です。たとえばorders.customer_memoをtextで保存できても、その列にB-treeインデックスを作成できるとは限りません。B-treeは等価比較や範囲検索などに使うインデックスですが、1件のインデックスエントリにはサイズ上限があります。

PostgreSQLは、テーブルやインデックスをページ（データを格納する単位）に分けて管理します。標準的なページサイズは8 KiBです。公式文書の「B-treeインデックス」によると、1つのインデックスエントリは、1ページのおよそ3分の1（8 KiBのページでは約2.7 KiB）を超えられません。TOASTによる圧縮が適用される場合は、圧縮後のサイズが制限の対象です。そのため、テーブルには保存できても、値全体をキーにするとINSERTやCREATE INDEXがエラーで失敗します。値を切り詰めて登録することはありません。

たとえば、圧縮されにくい文字列を保存してからB-treeインデックスを作成すると、次のようなエラーが発生します。エラーメッセージのbuffer pageは、上述のページを指しています。

CREATE TEMP TABLE long_memo (
  memo text
);

INSERT INTO long_memo
SELECT string_agg(md5(random()::text), '')
FROM generate_series(1, 200);

CREATE INDEX ON long_memo (memo);
ERROR:  index row size 6416 exceeds btree version 4 maximum 2704 for index "long_memo_memo_idx"
DETAIL:  Index row references tuple (0,1) in relation "long_memo".
HINT:  Values larger than 1/3 of a buffer page cannot be indexed.
Consider a function index of an MD5 hash of the value, or use full text indexing.

この例では、文字列自体はtext列に保存できますが、値全体をB-treeのキーにできないため、CREATE INDEXが失敗しています。既にインデックスがある場合は、同じ値をINSERTした時点でインデックスへの追加に失敗します。INSERT文はエラーで取り消されるため、テーブルに行だけが残ることもありません。この単一列のtextインデックスでは、サイズ制限を回避するために値を途中で切り詰めて登録することはありません。切り詰めた部分だけを使って、異なる値を同一視する動作もありません。

この制限はtextだけでなく、大きなvarchar(n)にも当てはまります。長い文字列を検索するときは、検索方法に合ったインデックスを選びます。単語単位の検索には全文検索とGINインデックス、完全一致検索にはハッシュ値を使った式インデックスなどが候補です。ハッシュ値には衝突の可能性があるため、利用者はハッシュ値の条件に加えて元の値との比較条件も検索に含めます。PostgreSQLは、指定された元の値との比較条件を評価し、ハッシュ値が一致した候補から検索対象を絞り込みます。

2. 数値型は必要な正確さと値の範囲で選ぶ

2.1. double precisionは2進数で表せる値しか正確に扱えない

金額の計算や比較を10進数の規則どおりに行うなら、double precisionは使いません。冒頭のorders.total_amountは、必要な桁数を指定したnumericに変更します。一方、測定値や統計計算のように近似値を許容し、計算速度や表現できる値の範囲を優先する用途では、double precisionを使えます。

double precisionは小数を扱えますが、2進数で有限桁に表せない値は近似値になります。税率や割引率を使って金額を計算し、小数点以下まで正確に扱う場合には、この性質が問題になります。

numericとdouble precisionの違いは、次の計算で確認できます。どちらも0.1 + 0.2が0.3と等しいかを比較しています。

SELECT 0.1::numeric + 0.2::numeric = 0.3::numeric AS numeric_equal;
 numeric_equal
---------------
 t
(1 row)

SELECT 0.1::double precision
     + 0.2::double precision = 0.3::double precision AS double_equal;
 double_equal
--------------
 f
(1 row)

numericではtrue、double precisionではfalseになります。0.1は2進数で有限桁に表せないため、double precisionでは近似値として扱われます。一方、numericは10進数の値を正確に扱うため、この計算では期待どおりの比較結果になります（浮動小数点数データ型）。

整数だけなら、double precisionでも−2の53乗から2の53乗までの整数をすべて正確に保存できます。正数の上限は約9,000兆です。この範囲の金額を1円単位で保存するだけなら、浮動小数点表現による誤差は生じません。また、0.5のように2進数で正確に表せる小数もあります。ただし、税率や割引率を使った計算には、0.1のように近似値になる小数が含まれることがあります。整数を正確に保存できても、その後の計算まで正確とは限りません。

0.1のように2進数で有限桁に表せない小数が計算に含まれると、その値は近似になります。そのため、金額を10進数の規則で計算・比較し、丸めを管理したい要件にはdouble precisionは向きません。orders.total_amountにはnumericを使います。

2.2. 金額にはnumeric、個数には整数型を使う

10進数として正確に扱う金額には、必要な桁数を決めてnumericを使います。numeric(precision, scale)のprecisionは全体の桁数、scaleは小数点以下の桁数です。orders.unit_priceのnumeric(12, 2)は、全体で12桁、小数点以下2桁を指定しています。指定より多い小数桁の入力は、まず2桁に丸められます。丸めた後の整数部が10桁を超える値は保存できません。orders.total_amountにも同じ考え方を使えますが、合計額に必要な桁数は単価とは分けて確認します。

金額を常に円単位の整数として扱うなら、integerやbigintに保存する設計も選べます。この場合も、税率や割引率の計算で小数が出たとき、どの時点で丸めるかを決めます。orders.quantityのような個数や回数には整数型を使い、想定する値の範囲に応じてintegerかbigintを選びます。

近似値を許容できる値には、double precisionを検討します。測定値や統計計算の結果など、10進数としての厳密な一致より計算速度や表現できる値の範囲を優先する用途です。小数を含むかどうかだけでなく、どの程度の正確さが要るかでnumericと使い分けます。

2.3. 新規設計ではmoney型よりnumericを優先する

金額を保存する型にはmoneyもありますが、新規設計ではnumericを優先します。moneyの表示形式や小数部の精度は、データベースのlc_monetary設定に依存します。設定が異なるデータベースへダンプをリストアすると、ダンプに含まれるmoneyの文字列表現をリストア先のlc_monetaryで解釈できず、読み込みに失敗することがあります。読み込みに成功しても、表示形式や小数部の扱いが変わる可能性があります。また、moneyを整数で割った結果は、表現できない小数部を0方向へ切り捨てます。負数の場合も、絶対値が小さくなる方向です。そのため、moneyはデータベースの設定と、演算に組み合わせる型の規則を意識して使う必要があります（通貨型）。

moneyは既存スキーマとの互換性など、明確な理由がある場合に検討します。通貨記号を含む表示が必要なら、numericの値をto_charで整形できます（データ型書式設定関数）。たとえば、to_char(unit_price, 'L999G999G999G990D00')で通貨記号、桁区切り、小数点以下の表示形式を指定できます。ordersの金額列では、保存したnumericの値を計算や比較に使い、画面に表示するときだけto_charで表示用の文字列に変換します。

3. 日付時刻型は保存したい時刻の意味で選ぶ

orders.ordered_atの型を選ぶには、注文日時として何を記録するのかを決めます。受信した表記をそのまま残すのか、特定の地域の日付と時刻を記録するのか、注文が起きた一瞬を記録するのかで選択が変わります。ここでは文字列型、timestamp without time zone、timestamp with time zoneを比較します。

3.1. 受信した表記を残すなら文字列型を選べる

受信した表記をそのまま残す必要があるなら、文字列型を選べます。UTCとの時差を表すオフセットやタイムゾーン名、部分的な日時、仕様外の値も、監査記録として保存できます。PostgreSQLや、JDBCやODBCなどのデータベースドライバに日時として解釈・変換させず、アプリケーション側だけで解釈する方針にも合います。

ただし、文字列型では日時としての妥当性は保証されません。データベースで日時の範囲検索や演算をするなら、日付時刻型を使います。検索と受信原文の保存の両方が必要なら、検索用の日付時刻型列と原文用の文字列列を分けます。

文字列の並び順を日時順として使うには、入力形式と照合順序（文字列比較の規則）を統一します。たとえば日付をYYYY-MM-DDにそろえ、桁数、精度、表記規則を固定すれば、文字列の順序を日付順として利用できます。ただし、異なるタイムゾーンの日時を同じ列に保存すると、表記上の順序と実際の時系列が一致しない場合があります。形式と照合順序を統一するだけで目的を満たせるか確認が必要です。

3.2. timestamp without time zoneは時差を変換しない

orders.ordered_atに指定したtimestamp without time zoneは、日付と時刻を保存しますが、タイムゾーン情報は持ちません。タイムゾーン付きの文字列を入力しても、時差の部分は無視されます。次の例では、同じ入力をtimestamp with time zoneにも保存し、セッションのタイムゾーンを変えて表示を比較します。

SET TIME ZONE 'Asia/Tokyo';

CREATE TEMP TABLE orders_time (
  ts_without timestamp without time zone,
  ts_with timestamp with time zone
);

INSERT INTO orders_time VALUES
('2026-07-01 09:00:00+09', '2026-07-01 09:00:00+09');

SELECT ts_without, ts_with FROM orders_time;
     ts_without      |        ts_with
---------------------+------------------------
 2026-07-01 09:00:00 | 2026-07-01 09:00:00+09
(1 row)

SET TIME ZONE 'UTC';

SELECT ts_without, ts_with FROM orders_time;
     ts_without      |        ts_with
---------------------+------------------------
 2026-07-01 09:00:00 | 2026-07-01 00:00:00+00
(1 row)

ts_withは、Asia/Tokyoでは09:00:00+09、UTCでは00:00:00+00と表示されます。一方、ts_withoutはどちらでも09:00:00です。timestamp without time zoneでは、入力に含まれる+09を使った変換も、表示先のタイムゾーンに合わせた変換も行われません。

timestamp without time zoneが適するのは、特定の地域の日付と時刻そのものを扱う場合です。たとえば、店舗の営業開始日時やシフト開始日時なら、timestamp without time zoneを検討できます。その場合は、どの地域の日時かを店舗や拠点の情報と一緒に管理します。注文が実際に起きた時点を複数の地域から比較する用途には、次のtimestamp with time zoneが適しています。

3.3. timestamp with time zoneは同じ一瞬を保存する

timestamp with time zoneは、タイムゾーンを考慮して日時を扱います。明示的なタイムゾーンを含む入力はUTCに変換して保存し、出力時にはセッションのTimeZoneに合わせて表示します。入力時のタイムゾーン名や+09という指定自体は保存しません。

注文受付時刻、決済完了時刻、ログ発生時刻のように、同じ一瞬を複数の地域から比較するなら、timestamp with time zoneが適しています。orders.ordered_atをこの用途に使うなら、timestamp without time zoneから変更する候補になります。前節の例で表示が変わったのは、保存した一瞬はそのままに、表示先のタイムゾーンに合わせて変換したためです。

ただし、タイムゾーンのない入力をtimestamp with time zoneに渡すと、セッションのTimeZoneで解釈されます。アプリケーションの接続設定、データベースドライバによる日付時刻型への変換、取得後の表示設定が一致しないと、意図しない時刻として扱われる可能性があります。入力にタイムゾーンを含めるか、セッションのTimeZoneを固定するかを決め、取得後の表示先も明確にします。

保存したい値ごとの選択肢をまとめます。日付時刻型の仕様は、公式文書の「日付/時刻データ型」と「日付/時刻の入力」を参照してください。

4. JSON型は原文の保持と検索の必要性で選ぶ

4.1. text、json、jsonbは保存後の用途が異なる

orders.payment_payloadには、決済サービスから返されたJSON形式のデータを保存します。保存先にはtext、json、jsonbがあり、受信内容をどこまでそのまま残すか、保存後にどう検索するかで選びます。

textはJSONとして検証しないため、JSONとして不正な文字列も保存できます。NUL文字だけは保存できません。これは、PostgreSQLのtext型自体がNUL文字を保存できないためです。実装上のサイズ上限は約1GBです。JSONとしての妥当性を検証せず、受信内容を残すことが目的なら候補です。

jsonは入力がJSONとして正しいことを検証し、入力されたテキストを保存します。空白、キーの順序、重複キーも保持します。冒頭の定義のようにpayment_payloadをjsonにすると、JSONとして検証しながら受信時の表記を残せます。

jsonbは入力を解析し、分解した形式で保存します。そのため、保存後の検索や比較に向いています。入力時に変換が必要ですが、GINインデックスも利用できます。一方、空白やキーの順序は保持されず、重複キーは最後の値だけが残ります。次のSQLで、重複キーの扱いを比較できます。

SELECT '{"a": 1, "a": 2, "active": false}'::json;
               json
-----------------------------------
 {"a": 1, "a": 2, "active": false}
(1 row)

SELECT '{"a": 1, "a": 2, "active": false}'::jsonb;
            jsonb
---------------------------
 {"a": 2, "active": false}
(1 row)

jsonでは2つのaが入力どおりに残りますが、jsonbでは最後の値である2だけが残ります。受信時の表記を保持するならjson、JSONとしての検証もせず文字列を残すならtext、JSONの内容を検索・比較するならjsonbを選びます。

4.2. JSONのキーや値を検索するならjsonbを使う

決済レスポンスのトップレベルにerror_codeキーがある注文を調べるなら、orders.payment_payloadをjsonbにする方法があります。冒頭のテーブル定義どおり列がjson型の場合、次の検索を実行するとエラーが発生します。?演算子はjsonb型に対して定義されているためです。

SELECT id
FROM orders
WHERE payment_payload ? 'error_code';
ERROR:  operator does not exist: json ? unknown
LINE 3: WHERE payment_payload ? 'error_code';
                              ^
HINT:  No operator matches the given name and argument types. You might need to add explicit type casts.

列をjsonbに変更すると、同じ条件でキーの有無を調べられます。

ALTER TABLE orders
  ALTER COLUMN payment_payload TYPE jsonb
  USING payment_payload::jsonb;

SELECT id
FROM orders
WHERE payment_payload ? 'error_code';
 id
----
(0 rows)

jsonやtextで保存し、検索のたびにjsonbへ変換する方法もあります。ただし、変換が必要になり、インデックスも検索式に合わせて定義しなければなりません。

検索量が増えたら、jsonb列へのGINインデックスも検討します。GINは、JSONのキーや値などを使った検索に利用できるインデックスです。標準のGIN演算子クラスでは、キーの存在、包含、JSONPathによる検索などを扱えます。詳しくは公式文書の「JSONデータ型」と「jsonbインデックス」を参照してください。

5. まとめ: 列の用途から型を決める

ordersの各列を見直すと、値の形式だけでは型を決められないことが分かります。注文コードには長さの上限、金額には計算の正確さ、注文日時にはタイムゾーンの扱い、決済レスポンスには原文の保持と検索方法を考える必要があります。

文字列では、最大長を型に記すならvarchar(n)、業務条件を制約で管理するならtextとCHECK制約を検討します。char(n)は空白埋めと比較規則に注意が必要で、性能上の利点もないため、新規設計で選ぶ場面は限られます。また、長い文字列を保存できても、値全体をB-treeインデックスのキーにできるとは限りません。

数値では、10進数の正確さが必要ならnumeric、整数で足りるなら値の範囲に応じてintegerかbigintを選びます。double precisionは近似値を許容できる用途に使い、金額では丸める時点と規則も決めます。moneyは設定や演算規則に依存するため、新規設計で使う場合は注意が必要です。

日付時刻では、同じ一瞬を扱うならtimestamp with time zone、特定の地域の日付と時刻を扱うならtimestamp without time zoneを検討します。受信した表記を残すために文字列型を選ぶこともできますが、その場合は日時としての妥当性や比較方法を別途管理します。

JSONでは、受信文字列を検証せずに残すならtext、JSONとして検証して入力テキストを保持するならjson、内容を検索・比較するならjsonbが候補です。決済レスポンスを記録として残すのか、内容を使って注文を検索するのかで、適する型が変わります。

テーブルを設計するときは、列ごとに保存する値と用途を確かめます。拒否する入力、必要な計算、検索条件が明確になれば、型を選ぶ理由も定まります。

UPDATE accounts SET balance = balance - 100 WHERE id = 1;

こういうときに原因の一つとして早めに確認しておきたいものがロック待ちです。ロック待ちとは、あるトランザクションが更新中の行などを、別のトランザクションが同時に変更しようとして、先のトランザクションが終わるまで待っている状態です。PostgreSQLはデータの矛盾を防ぐため、同じ行を複数の処理が同時に勝手に書き換えられないようにします。そのため、後から実行したUPDATEは、必要なロックを取得できるまで待つことがあります。

本記事では、同じ行へのUPDATEによってロック待ちが起きる状況を作り、どこを確認すれば原因を切り分けられるのかを説明します。

対象読者は、PostgreSQLを使い始めたアプリケーション開発者や運用初心者です。SQLは書けるものの、トランザクション、ロック、MVCC、監視ビューの関係をまだ整理できていない人を想定しています。

実験の前に

この実験では、psqlのセッションを3つ使います。

• セッションA:先に行を更新して、ロックを保持する
• セッションB:同じ行を更新しようとして待つ
• セッションC: PostgreSQLの状態を確認する

ここで、実験に入る前にトランザクションについて簡単に整理します。

トランザクションとは、複数のSQL操作をひとまとまりの処理として扱う仕組みです。たとえば、口座Aから100円を引き、口座Bに100円を足す処理を考えます。この2つの更新は、片方だけの成功は許されません。引き落としだけ成功して、入金が失敗すると、データの整合性が崩れるためです。そこで、PostgreSQLでは、関連するSQLを1つのトランザクションとして扱えます。

BEGINを実行すると、トランザクションが始まります。

BEGIN;

トランザクション内で実行した変更は、COMMITするまで確定しません。

COMMIT;

COMMITは、トランザクション内で行った変更を確定する操作です。COMMIT すると、他のセッションからもその変更が見えるようになります。一方、変更を取り消したい場合はROLLBACKを実行します。

ROLLBACK;

ROLLBACKは、トランザクション内で行った変更を取り消す操作です。ROLLBACKすると、そのトランザクションで実行した更新はなかったことになります。

本記事のロック待ちを理解するうえで重要なのは、次の点です。トランザクション中にUPDATE文の実行が終わっていても、COMMITまたはROLLBACKを実行するまで、トランザクションは終わりません。そして、トランザクションが終わるまで、更新に関係するロックが保持されることがあります。つまり、次のような状態が問題になります。

BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
-- COMMITもROLLBACKもしていない

この状態では、UPDATE 自体は終わっています。しかし、トランザクションはまだ終わっていません。そのため、別のセッションが同じ行を更新しようとすると、先のトランザクションが終わるまで待つことがあります。

本記事では実験を通して、この「トランザクションが終わっていないために、別の更新が待たされる状態」を意図的に作ります。つまり、単に UPDATEを実行するだけでなく、BEGINでトランザクションを開始し、あえて COMMITせずに残す操作が重要になります。

以降の実験では、セッションAがトランザクションを開いたまま行を更新し、セッションBが同じ行を更新しようとして待つ、という流れを何度か使います。

実験の準備

まず、検証用のテーブルを作ります。ここでは、口座残高を表すaccountsテーブルを使います。

-- accountsテーブルを作成
CREATE TABLE accounts (
  id integer PRIMARY KEY
  , owner_name text NOT NULL
  , balance integer NOT NULL
);

-- データを2件登録
INSERT INTO accounts (id, owner_name, balance)
VALUES
  (1, 'alice', 1000),
  (2, 'bob', 2000);

初期状態を確認します。

SELECT * FROM accounts ORDER BY id;
 id | owner_name | balance
----+------------+---------
  1 | alice      |    1000
  2 | bob        |    2000
(2 rows)

以降は各実験を始める前に、セッションAとセッションBで次を実行しておくと安全です。

-- 各実験の前にROLLBACKを実行してトランザクションを終了しておく
-- Session A/B
ROLLBACK;

すでにトランザクションが終わっている場合は、警告が出ることがあります。その場合でも、この実験では問題ありません。

合わせて、セッションAと セッションBのPIDも確認しておきます。

-- セッションA
SELECT pg_backend_pid();
 pg_backend_pid
----------------
             52
(1 row)


-- セッションB
SELECT pg_backend_pid();
 pg_backend_pid
----------------
             57
(1 row)

実験1:同じ行をUPDATEすると片方が待つ

この実験で確認すること

この実験では、同じ行を2つのトランザクションからUPDATEすると、後から実行した UPDATEが待たされることを確認します。ポイントは、先にUPDATEしたセッションがCOMMITするまで、後続の UPDATEが進めないことです。

手順1:セッションAでトランザクションを開始する

まず、セッションAでトランザクションを開始します。

-- Session A
BEGIN;

この時点で、セッションAはトランザクションの中に入ります。まだデータは更新していません。

手順2:セッションAでid = 1の行を更新する

続けて、セッションAでid = 1の行を更新します。

-- Session A
UPDATE accounts SET balance = balance - 100 WHERE id = 1;

このUPDATE自体はすぐに終わります。ただし、まだCOMMITしていません。そのため、セッションA のトランザクションは開いたままです。

ここが重要です。UPDATE文の実行が終わっていても、トランザクションが終わっていなければ、PostgreSQL はその更新に関係するロックを保持し続けます。

手順3:セッションBで同じ行を更新する

次に、セッションBでもトランザクションを開始します。

-- Session B
BEGIN;

そのあと、セッションBで同じid = 1の行を更新します。

-- Session B
UPDATE accounts SET balance = balance - 50 WHERE id = 1;

このUPDATEは応答が返ってきません。アプリケーションから見ると、「UPDATEが終わらない」状態に見えます。

なぜ待つのか

セッションAは、id = 1の行を先に更新しました。しかし、まだCOMMITも ROLLBACKもしていません。この状態で、セッションBが同じ行を更新しようとすると、PostgreSQLはセッションB の更新をすぐには進めません。セッションAの更新が確定するのか、取り消されるのかがまだ分からないからです。そのため、セッションBはセッションA のトランザクションが終わるのを待ちます。この待ちが、ロック待ちです。

この実験で分かったこと

同じ行を同時に更新しようとすると、後から実行したUPDATEが待つことがあります。ただし、画面上で UPDATEが返ってこないだけでは、SQLの処理が重いのか、ロックを待っているのかは分かりません。

次は、PostgreSQLの中でその待ち状態を確認します。

実験2: pg_stat_activityで何を待っているかを確認する

この実験で確認すること

この実験では、待っているセッションが本当にロック待ちなのかを確認します。使うのは、pg_stat_activityです。pg_stat_activity は、PostgreSQLに接続している各セッションの状態を確認できるビューです。

確認するSQL

セッションCから、次のSQLを実行します。

-- Session C
SELECT
  pid
  , state
  , wait_event_type
  , wait_event
  , xact_start
  , query_start
  , query
FROM
  pg_stat_activity
WHERE
  datname = current_database()
  AND pid <> pg_backend_pid()
  AND query LIKE '%UPDATE accounts%'
ORDER BY
  query_start;
 pid |        state        | wait_event_type |  wait_event   |          xact_start           |          query_start          |                           query
-----+---------------------+-----------------+---------------+-------------------------------+-------------------------------+-----------------------------------------------------------
  52 | idle in transaction | Client          | ClientRead    | 2026-06-15 05:57:26.539576+00 | 2026-06-15 05:57:26.541089+00 | UPDATE accounts SET balance = balance - 100 WHERE id = 1;
  57 | active              | Lock            | transactionid | 2026-06-15 05:57:31.885276+00 | 2026-06-15 05:57:31.886839+00 | UPDATE accounts SET balance = balance - 50 WHERE id = 1;
(2 rows)

まず確認する列

ここで最初に確認する列は、次の3つです。

• state
• wait_event_type
• wait_event

stateは、そのセッションの大まかな状態を示します。ここでは、pid = 57のセッションBは state = 'active'になっています。これは、PostgreSQLがそのSQLを処理中として扱っているという意味です。ただし、active
だからといって、CPUを使って計算し続けているとは限りません。何かを待っていても、SQLの実行中であれば
activeと表示されることがあります。

そこで、wait_event_typeとwait_eventを合わせて確認します。

結果の読み方

セッションBの行を確認すると、次のようになっています。

wait_event_type = Lock
wait_event      = transactionid

wait_event_type = Lockは、ロックを待っていることを示します。wait_event = transactionid は、別のトランザクションが終わるのを待っていることを示します。この例では、セッションBがセッションAのトランザクション終了を待っています。

つまり、セッションBのUPDATEは、検索や計算に時間がかかっているのではありません。ロック待ちで止まっています。

この実験で分かったこと

UPDATEが返ってこないときは、まずpg_stat_activityを確認します。特に、state
だけで判断しないことが重要です。wait_event_typeと
wait_eventを合わせて確認すると、そのセッションが何を待っているのかを確認できます。

次は、どのセッションが待たせているのかを確認します。

実験3: pg_blocking_pids()で待たせている相手を探す

この実験で確認すること

この実験では、待っているセッションを止めている相手を特定します。待っている側を、ここではウェイターと呼びます。待たせている側を、ここではブロッカーと呼びます。

PostgreSQLでは、pg_blocking_pids()を使うと、当該PIDのブロッカーPIDを確認できます。

確認するSQL

セッションCで次のSQLを実行します。pg_blocking_pids()は引数に指定したPIDのブロッカーPIDの配列を返します。

-- Session C
WITH activity AS (
  SELECT
    pid
    , state
    , wait_event_type
    , wait_event
    , pg_blocking_pids(pid) AS blocking_pids
    , query
  FROM
    pg_stat_activity
  WHERE
    datname = current_database()
    AND pid <> pg_backend_pid()
)
SELECT
  *
FROM
  activity
WHERE
  query LIKE '%UPDATE accounts%'
ORDER BY
  pid;
 pid |        state        | wait_event_type |  wait_event   | blocking_pids |                           query
-----+---------------------+-----------------+---------------+---------------+-----------------------------------------------------------
  57 | active              | Lock            | transactionid | {52}          | UPDATE accounts SET balance = balance - 50 WHERE id = 1;
  52 | idle in transaction | Client          | ClientRead    | {}            | UPDATE accounts SET balance = balance - 100 WHERE id = 1;

結果の読み方

pid = 57の行を確認すると、blocking_pidsが{52}になっています。これは、pid = 57 のセッションが、pid = 52のセッションで待たされているという意味です。

この例では、次の関係になります。

ウェイター（待っている側）:     pid = 57
ブロッカー（待たせている側）:   pid = 52

つまり、pid = 57のSQLだけを確認しても原因は分かりません。次に確認すべきなのは、ブロッカーのpid = 52の状態です。

実験4: idle in transactionはロックを保持し得る状態

この実験で確認すること

この実験では、idle in transactionの意味を確認します。idle in transactionは、トランザクションの中にいるが、現在はSQL を実行していない状態です。何もしていないように見えても、トランザクションが終わっていなければ、ロックを保持していることがあります。

状況の確認

ここまでの状態では、セッションAがid = 1の行を更新し、まだCOMMITしていません。セッションB は、同じ行を更新しようとして待っています。

セッションCから次のSQLを実行します。実験3のSQLに表示列(xact_start, state_change)を追加しています。

-- Session C
WITH activity AS (
  SELECT
    pid
    , state
    , wait_event_type
    , wait_event
    , pg_blocking_pids(pid) AS blocking_pids
    , xact_start
    , state_change
    , query
  FROM
    pg_stat_activity
  WHERE
    datname = current_database()
    AND pid <> pg_backend_pid()
)
SELECT
  *
FROM
  activity
WHERE
  query LIKE '%UPDATE accounts%'
ORDER BY
  xact_start NULLS LAST;
 pid |        state        | wait_event_type |  wait_event   | blocking_pids |          xact_start           |         state_change          |                           query
-----+---------------------+-----------------+---------------+---------------+-------------------------------+-------------------------------+-----------------------------------------------------------
  52 | idle in transaction | Client          | ClientRead    | {}            | 2026-06-15 05:57:26.539576+00 | 2026-06-15 05:57:26.542127+00 | UPDATE accounts SET balance = balance - 100 WHERE id = 1;
  57 | active              | Lock            | transactionid | {52}          | 2026-06-15 05:57:31.885276+00 | 2026-06-15 05:57:31.886842+00 | UPDATE accounts SET balance = balance - 50 WHERE id = 1;
(2 rows)

結果の読み方

pid = 52のセッションは、state = 'idle in transaction'になっています。

これは、次の状態を意味します。

トランザクションはまだ開いている
ただし、現在はSQLを実行していない

また、この行ではwait_event_type = Client、wait_event = ClientReadになっています。これは、PostgreSQL がクライアントから次の命令を待っていることを示します。つまり、セッションAはデータベース内部でロックを待っているのではなく、クライアント側から次の SQL、COMMIT、またはROLLBACKが送られるのを待っている状態です。

この状態でも、セッションAはロックを解放していません。ロックは、トランザクションがCOMMITまたは ROLLBACKで終わるまで保持されます。そのため、セッションBは待ち続けます。

なぜ問題になりやすいのか

idle in transactionは、アプリケーションの作りによって長引くことがあります。

たとえば、次のような処理です。

• トランザクションを開始したあとに、外部APIの応答を待つ
• トランザクションを開始したあとに、ユーザー入力を待つ
• 例外が発生したのに、ROLLBACKしないまま接続を残す

これらは、ロックを保持したまま待ち時間を伸ばす原因になります。

実務で確認する列

実務でidle in transactionを見つけたときは、すぐにセッションを終了する前に、まず次の列を確認します。

• xact_start
• state_change
• query
• application_name
• client_addr

特に
xact_start
が古い場合は、長時間トランザクションが開いたままになっている可能性があります。ただし、セッションを強制終了すると、アプリケーション側ではエラーになります。注文更新や残高更新の途中であれば、業務処理にも影響します。そのため、まずはどのアプリケーション、どの接続元、どの処理がトランザクションを開いたままにしたのかを特定することが重要です。

timeout設定について

idle in transactionを長時間残したくない場合は、idle_in_transaction_session_timeout を使う方法もあります。この設定は、トランザクション内で何もしていないセッションを、指定時間後に切断します。ただし、切断された側のアプリケーションにはエラーとして見えます。本番環境で使う場合は、事前に影響を確認する必要があります。

この実験で分かったこと

idle in transaction
は、何もしていない安全な状態とは限りません。トランザクションが終わっていなければ、ロックを保持し続けることがあります。ロック待ちを調べるときは、待っている側だけでなく、待たせている側の
stateとxact_startを確認します。

次は、通常のロック待ちとデッドロックの違いを確認します。

実験5:通常のロック待ちとデッドロックは違う

この実験で確認すること

ここまでの実験では、セッションBがセッションAを一方的に待っていました。この場合、セッションAがCOMMITまたは ROLLBACKすれば、セッションBは進めます。これは通常のロック待ちです。

一方で、デッドロックは違います。デッドロックは、複数のトランザクションが互いに相手を待ってしまい、どちらも先へ進めなくなる状態です。

実験前の準備

セッションAとセッションBの両方でROLLBACKを実行し、前の実験の状態を終わらせます。

-- Session A / Session B
ROLLBACK;

手順1:セッションAがid = 1を更新する

-- Session A
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;

セッションAは、id = 1の行を更新します。まだCOMMITはしません。

手順2:セッションBがid = 2を更新する

-- Session B
BEGIN;
UPDATE accounts SET balance = balance - 50 WHERE id = 2;

セッションBは、id = 2の行を更新します。こちらも、まだCOMMITはしません。

この時点では、セッションAとBは別々の行を更新しているため、互いに待っていません。

手順3:セッションAがid = 2を更新しようとする

次に、セッションAがid = 2の行を更新しようとします。

-- Session A
UPDATE accounts SET balance = balance + 100 WHERE id = 2;

id = 2は、すでにセッションBが更新しています。そのため、セッションAはセッションBのトランザクション終了を待ちます。

この時点では、まだデッドロックではありません。セッションAが、セッションBを一方的に待っているだけです。

手順4:セッションBがid = 1を更新しようとする

最後に、セッションBがid = 1の行を更新しようとします。

-- Session B
UPDATE accounts SET balance = balance + 50 WHERE id = 1;

id = 1は、すでにセッションAが更新しています。そのため、セッションBはセッションAのトランザクション終了を待ちます。

これで、次の状態になります。

セッションAは、セッションBを待っている
セッションBは、セッションAを待っている

これがデッドロックです。

デッドロック時のエラー

PostgreSQLはデッドロックを検出すると、どちらか一方のトランザクションを中止します。

エラーの例です。

ERROR:  deadlock detected
DETAIL:  Process 57 waits for ShareLock on transaction 2317; blocked by process 52.
Process 52 waits for ShareLock on transaction 2318; blocked by process 57.
HINT:  See server log for query details.
CONTEXT:  while updating tuple (0,1) in relation "accounts"

このエラーが出たあとは、エラーになったトランザクションはそのまま続けられません。次の実験へ進む前に、セッションAとBの両方で ROLLBACKを実行します。

-- Session A / Session B
ROLLBACK;

通常のロック待ちとの違い

通常のロック待ちは、ブロッカー側が終われば解消します。一方、デッドロックでは、互いに相手を待っています。そのままではどちらも進めません。

そのため、PostgreSQL はどちらか一方を中止して、待ち続ける状態を解消します。どちらのトランザクションが中止されるかをアプリケーション側で決め打ちしてはいけません。 デッドロックで失敗した場合は、失敗したSQLだけを再実行するのではなく、トランザクション全体を最初からやり直す必要があります。

デッドロックを減らす考え方

複数行を更新する処理では、更新する順序をそろえることが基本です。たとえば、ある処理はid = 1のあとに id = 2を更新し、別の処理はid = 2のあとにid = 1を更新すると、デッドロックが起きやすくなります。

更新順序を決められるなら、常に同じ順序で更新します。たとえば、常にidの小さい順に更新するなどが考えられます。

lock_timeoutについて

通常のロック待ちが長すぎる場合の安全装置として、lock_timeoutがあります。

SET lock_timeout = '3s';

lock_timeoutは、ロックを取得できない状態が指定時間を超えたときに、そのSQL をエラーにします。これは、デッドロックを検出する設定ではありません。ロック待ちが長くなりすぎたSQLを失敗させるための設定です。また、statement_timeout との関係にも注意が必要です。statement_timeoutは、SQL全体の実行時間に対する制限です。lock_timeout
は、ロック取得待ちに対する制限です。statement_timeoutが
lock_timeout以下に設定されていると、ロック待ち専用のエラーより先に statement_timeoutが発生します。ロック待ちを切り分けたい場合は、両者の値を分けて設定します。

この実験で分かったこと

通常のロック待ちは、ブロッカー側が終われば解消します。一方、デッドロックは、互いに相手を待つため、そのままでは解消しません。PostgreSQL はどちらか一方のトランザクションを中止します。アプリケーションでは、デッドロックやロックタイムアウトで失敗した場合に、トランザクション全体をやり直せるようにしておく必要があります。

次は、書き込みではなく、読み取りがどう見えるのかを確認します。

実験6:通常のSELECTは止まらない

この実験で確認すること

ここまでの実験では、UPDATE同士の待ちを見てきました。では、あるセッションが行を更新してまだ COMMITしていないとき、別のセッションがその行をSELECTするとどうなるのでしょうか。

FOR UPDATEなどを付けない通常のSELECTは、多くの場合、更新中の行を待たずに結果を返します。これは、PostgreSQL が、読み取り時点で見えてよい行の版を選んで読みます。この仕組みをMVCC (Multi-Version Concurrency Control) と呼びます。日本語では、多版型同時実行制御と呼ばれます。

以降では、「見えてよい行の版を読む仕組み」を簡単に説明します。

実験前の準備

セッションAとセッションBの両方でROLLBACKを実行します。

-- Session A / Session B
ROLLBACK;

手順1:セッションAでid = 1を更新する

まず、更新前の値を確認します。

-- Session A
SELECT id, owner_name, balance FROM accounts WHERE id = 1;
 id | owner_name | balance
----+------------+---------
  1 | alice      |    1000
(1 row)

セッションAでトランザクションを開始します。

-- Session A
BEGIN;

次に、id = 1の残高を999に更新します。

-- Session A
UPDATE accounts SET balance = 999 WHERE id = 1;

ここでも、まだCOMMITはしません。つまり、セッションAの変更はまだ確定していません。

手順2:セッションBで通常のSELECTを実行する

セッションBから、BEGINでトランザクションを開始して、同じ行を読み取ります。

-- Session B
BEGIN;
SELECT id, owner_name, balance FROM accounts WHERE id = 1;
 id | owner_name | balance
----+------------+---------
  1 | alice      |    1000
(1 row)

セッションBのSELECTはロック待ちになりません。また、セッションAが更新したbalance = 999も見えません。セッションB からは、最後にCOMMIT済みの値である1000が見えます。

なぜ止まらないのか

セッションAのUPDATEは、まだCOMMITされていません。もし、セッションBから未コミットの 999が見えてしまうと、あとからセッションAが ROLLBACKしたときに困ります。存在しなかった変更を読んだことになるからです。そのため、PostgreSQLは通常の SELECTに対して、未コミットの変更を見せません。代わりに、読み取り時点で見えてよい、古い行の版を返します。

PostgreSQLのデフォルト設定では、各SQLを実行するたびに、その時点で COMMIT済みのデータを読みます。この設定を、トランザクション分離レベルの
Read Committed
と呼びます。トランザクション分離レベルとは、あるトランザクションから、他のトランザクションの変更をどこまで見せるかを決める設定です。

SELECT FOR UPDATEは待つ

ただし、すべてのSELECTが待たないわけではありません。SELECT FOR UPDATE は、読み取った行をあとで更新する前提でロックしようとします。

-- Session B
SELECT id, owner_name, balance FROM accounts WHERE id = 1 FOR UPDATE;

この場合は、セッションAのトランザクション終了を待ちます。通常の SELECTは、見えてよい行の版を読めるため、止まらないことが多いです。一方、SELECT FOR UPDATE は行をロックしようとするため、更新中の行と競合します。

この実験で分かったこと

PostgreSQLでは、未コミットの変更は通常のSELECTから見えません。この実験では、通常の SELECTは、更新中の行を待たずに、見えてよい行の版を読みます。一方、SELECT FOR UPDATE は行をロックしようとするため、対象の行が他のトランザクションで更新中の場合は、待つことがあります。

次は、ロック待ちしていたUPDATEが再開したときに、どの条件で更新されるのかを確認します。

実験7: UPDATEは待ったあとにWHEREを再確認する

この実験で確認すること

この実験では、ロック待ちしていたUPDATEが再開したときの動きを確認します。重要なのは、ロック待ちしていた UPDATEが、ロック待ちの前に見えていた古い行をそのまま更新するわけではない、という点です。

PostgreSQLのデフォルト設定では、ロック待ちが終わったあと、更新後の行に対してWHERE条件をもう一度確認します。

実験前の準備

セッションAとセッションBの両方でROLLBACKを実行します。

-- Session A / Session B
ROLLBACK;

手順1:セッションAがid = 1を更新する

まず、更新前の値を確認します。

-- Session A
SELECT id, owner_name, balance FROM accounts WHERE id = 1;
 id | owner_name | balance
----+------------+---------
  1 | alice      |    1000
(1 row)

セッションAでトランザクションを開始します。

-- Session A
BEGIN;

次に、id = 1の残高を1000にします。ここでは、同じ行を更新中の状態にするため、id = 1の残高を 1000に更新します。値は変わりませんが、UPDATEは実行されるため、この行はセッションA のトランザクションが終わるまで、他の更新と競合する状態になります。

-- Session A
UPDATE accounts SET balance = 1000 WHERE id = 1;

まだCOMMITはしません。

手順2:セッションBが条件付きUPDATEを実行する

セッションBでトランザクションを開始します。

-- Session B
BEGIN;

次に、残高が500以上の場合だけ、50減らすUPDATEを実行します。

-- Session B
UPDATE accounts
SET balance = balance - 50
WHERE id = 1
  AND balance >= 500
RETURNING *;

このUPDATEは待ちます。 セッションAが同じid = 1の行を更新して、まだCOMMITしていないからです。

手順3:セッションAが残高を400にしてCOMMITする

セッションBが待っている間に、セッションAで同じ行の残高を400にします。

-- Session A
UPDATE accounts SET balance = 400 WHERE id = 1;

そのあと、セッションAのトランザクションを確定します。

-- Session A
COMMIT;

これで、セッションBの待ちが解除されます。

セッションBの結果

セッションBのUPDATEは再開します。ただし、セッションB は、ロック待ちの前に見えていた行をそのまま更新するわけではありません。セッションAがCOMMITした後の行に対して、WHERE 条件をもう一度確認します。

この時点で、id = 1のbalanceは400です。セッションBの条件は次のとおりでした。

WHERE id = 1
  AND balance >= 500

balance = 400なので、balance >= 500は成り立ちません。そのため、セッションBのUPDATEは0 行更新になります。

 id | owner_name | balance
----+------------+---------
(0 rows)

この動きが重要な理由

アプリケーションで避けたいのは、先にSELECTで値を確認し、その結果だけを前提にして、あとから無条件に UPDATEする書き方です。

BEGIN;
SELECT balance FROM accounts WHERE id = 1;

UPDATE accounts
SET balance = balance - 500
WHERE id = 1;
COMMIT;

この書き方では、SELECTしてから UPDATEするまでの間に、別のトランザクションが同じ行を更新する可能性があります。つまり、アプリケーションが事前に見た残高と、実際に UPDATEする時点の残高が同じとは限りません。

残高不足を防ぎたいなら、更新してよい条件をUPDATEのWHEREに入れます。

BEGIN;
UPDATE accounts
SET balance = balance - 500
WHERE id = 1
  AND balance >= 500;
COMMIT;

このSQLは、UPDATEする時点のbalanceが500以上の場合だけ、残高を減らします。1行更新されれば成功です。0 行なら、残高不足として扱えます。

分離レベルを上げる場合

トランザクション分離レベルをRepeatable Readや
Serializable
に上げる方法もあります。ただし、その場合は競合する更新を検出して、トランザクションがエラーになることがあります。分離レベルを上げる場合は、失敗した SQLだけでなく、トランザクション全体を最初から再試行できる設計が必要です。

この実験で分かったこと

ロック待ちしていたUPDATEは、ロック待ちが終わったあとに WHERE条件を再確認します。そのため、並行更新に強い処理にしたい場合は、事前のSELECT結果だけに頼らず、UPDATE のWHEREに更新条件を入れることが重要です。

実務での切り分け手順

ここまでの実験で、ロック待ちの見方を段階的に確認しました。実務でも、まず見るところは同じです。

UPDATEが返ってこないときは、最初にpg_stat_activityを確認します。ここで見るのは、待っているセッションの state、wait_event_type、wait_eventです。wait_event_typeが Lockであれば、そのセッションはロック待ちしている可能性が高いです。

次に、pg_blocking_pids()を使って、そのセッションを待たせているPIDを確認します。待っているSQL だけを見ても、原因は分かりません。重要なのは、待っている（ウェイター）側と、待たせている（ブロッカー）側を分けて見ることです。

待たせている（ブロッカー）側のPIDが分かったら、もう一度
pg_stat_activity
を確認します。特に、state、xact_start、state_change、application_name、client_addr、query を見ます。state = 'idle in transaction'で、xact_start が古い場合は、トランザクションを開いたまま放置している可能性があります。ただし、すぐにセッションを終了すればよいとは限りません。まず、どのアプリケーション、どの接続元、どの処理がトランザクションを開いたままにしているのかを確認します。

再発を減らす設計

ロック待ちそのものは、PostgreSQLの異常ではありません。同じ行を同時に更新しようとすれば、待つことがあります。

問題になるのは、待たせているトランザクションが長く残り、他の処理を止め続けることです。

ここでは、再発を減らすための基本的な考え方を整理します。

トランザクションを短くする

更新や明示的なロックを取得したあとは、できるだけ早くCOMMITまたはROLLBACKします。トランザクション中に外部API 呼び出し、ユーザー入力待ち、重いファイル処理などを入れると、ロックを持ったまま待ち時間が伸びます。また、例外が発生した場合は、必ず ROLLBACKします。

更新順序をそろえる

複数行を更新する処理では、更新順序をそろえます。ある処理はid = 1のあとにid = 2を更新し、別の処理は id = 2のあとにid = 1を更新すると、デッドロックが起きやすくなります。順序を決められるなら、常に同じ順序で更新します。

lock_timeoutを検討する

長時間待たせたくない処理では、lock_timeoutを検討します。

SET lock_timeout = '3s';

これは、ロックを取得できない状態が指定時間を超えたら、そのSQL をエラーにする設定です。ただし、エラーになった場合にアプリケーション側でどう扱うかを決めておく必要があります。

log_lock_waitsを確認する

本番環境では、log_lock_waitsも確認対象になります。log_lock_waitsを有効にすると、deadlock_timeout を超えたロック待ちをログに出せます。常にpg_stat_activityを手動で見続けるのではなく、ログから、どのSQL がいつ、どの程度ロック待ちしたのかを後から確認できます。

アプリケーションで再試行を考える

デッドロックやロックタイムアウトで失敗した場合、失敗したSQL だけを途中から再実行するのは危険です。基本は、トランザクション全体を最初からやり直します。ただし、無制限に再試行し続けるのではなく、再試行回数には上限を設けます。

UPDATEのWHEREに条件を入れる

並行更新で条件が変わる処理では、事前のSELECT結果だけに頼らないようにします。たとえば、残高が足りる場合だけ引き落とすなら、条件を UPDATEのWHEREに入れます。

BEGIN;
UPDATE accounts
SET balance = balance - 500
WHERE id = 1
  AND balance >= 500;
COMMIT;

以上、UPDATEが返ってこない状況を、同じ行への更新、ロック待ち、待たせているトランザクション、通常の SELECTの見え方に分けて確認しました。

ロック待ちそのものは、PostgreSQL の異常ではありません。同じデータを同時に矛盾なく更新するために必要な動きです。問題になるのは、ロックを持ったトランザクションが長く残り、他の処理を止め続けることです。

UPDATEが返ってこないときは、待っているSQLだけを見るのではなく、PostgreSQLの中で何を待っているのかを確認します。そのうえで、pg_blocking_pids() を使い、待たせている相手を探します。

待っている側と、待たせている側を分けて見る。この見方を持っておくと、ロック待ちを原因の一つとして落ち着いて切り分けられます。

pgvectorのインストールとセットアップ

PostgreSQLにpgvectorをインストールします。OSはRocky Linux release 9.6、PostgreSQLは公式リポジトリからインストールしたバージョン16.1を使います。PostgreSQLを動作させるPATH等の環境変数は設定済みで、すでにPostgreSQLインスタンスは起動済みとします。

pgvectorはPostgreSQLの公式リポジトリ経由でPostgreSQL 16用のpgvector_16をパッケージからインストールします。

# dnf install pgvector_16

続けて、testデータベースにpgvectorを登録します。

$ psql -U postgres -d test
psql (16.1)
Type "help" for help.

test=# CREATE EXTENSION vector;
CREATE EXTENSION
test=# \dx
                             List of installed extensions
  Name   | Version |   Schema   |                     Description
---------+---------+------------+------------------------------------------------------
 plpgsql | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector  | 0.5.1   | public     | vector data type and ivfflat and hnsw access methods

ベクトル列の作成とベクトルデータの挿入

ベクトルデータを格納する列を作成します。pgvectorを登録すると、vector型が使えます。

test=# CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));

vector(3)は3次元のベクトル、つまり、ベクトル空間を形成する基底ベクトルの個数が3つであることを意味します。ここでは3次元に指定していますが、最大で16000次元まで指定できます。
異なる次元のベクトルを同じ列に保存したい場合は（vector(3)ではなく）vectorを使用できます。ただしその場合、式に対するインデックスや部分インデックスを使って同じ次元数の行にしかインデックスを作成できません。

また、vector型の各要素はPostgreSQLのreal型と同様の単精度浮動小数点数で格納されます。より高精度のベクトルデータ格納したい場合は、vector型ではなく、double precision[]やnumeric[]型が使えます。ただし、高精度の値を格納はできますが、pgvectorが提供する機能を使う場合はvector型にキャストする必要があり、格納したデータの検索時に精度値が喪失します。

test=# CREATE TABLE items2 (id bigserial PRIMARY KEY, embedding double precision[]);

データがvector型に変換可能であり、かつ、想定の次元数であることを保証するためにチェック制約を追加してもよいでしょう。

test=# ALTER TABLE items2 ADD CHECK (vector_dims(embedding::vector) = 3);

次に、作成した列にベクトルデータを挿入します。vector型は以下のようにARRAYキーワードを使った配列や、[要素1,要素2,…]といった典型的な配列を表す文字列定数を解釈できます。
なお、vector型ではなく、double precision[]やnumeric[]型を定義した場合は、ベクトルデータをPostgreSQLの配列リテラル定数で格納できます。

test=# INSERT INTO items (embedding)
SELECT
  ARRAY[
  random() * 1000, -- 最初の次元のランダム値
  random() * 1000, -- 二番目の次元のランダム値
  random() * 1000  -- 三番目の次元のランダム値
]
FROM
  generate_series(1 , 10000);

itemsテーブルに、乱数を使った3次元のベクトルデータを10000行挿入しました。

test=# SELECT * FROM items LIMIT 5;
 id |            embedding
----+---------------------------------
  1 | [747.1946,30.812382,226.11743]
  2 | [389.10852,188.70128,151.08716]
  3 | [176.6698,954.8121,233.49654]
  4 | [295.3235,539.09283,721.9699]
  5 | [786.6494,895.81323,160.88304]
(5 rows)

最近傍検索の実行

最近傍検索を実行して、特定のベクトルに最も近いデータのトップ3を検索します。

test=# SELECT * FROM items ORDER BY embedding <#> '[10.0, 2, 0.3]' LIMIT 3;
  id  |            embedding
------+---------------------------------
 7945 | [998.16565,992.58215,926.16675]
 4633 | [996.8208,985.77405,989.8139]
 3345 | [997.30383,966.3805,949.19257]
(3 rows)

<#>演算子はベクトル間の負の内積を表す演算子です。似ているベクトルデータほど小さい数値となります。これは<#>演算子が昇順のインデックススキャンのみに対応しているためです。昇順ソートで最近似のベクトルデータをインデックスを効かせて取り出せます。

提供される演算子と関数

pgvectorは2つのベクトルの乗算、減算、乗算、ユークリッド距離、内積、コサイン距離等の演算子が用意されています。

同様の機能を持った関数もあります。

また、avg(vector) および sum(vector) でベクトルデータの平均と合計を算出する集約関数もあります。

ベクトルデータのインデックス

デフォルトのpgvectorは最近傍検索を行うので、リコール率（近傍アイテムを取りこぼさない確率）は100%ですが、線形探索のために速度が問題になる場合があります。
そのため、pgvectorには近似最近傍検索を用いた、IVFFlatとHNSWの2種類のインデックスが追加できます。ただし、正確な最近傍検索でないので高速にデータを取得できますが、実行時間・メモリ・精度のトレードオフが発生します。

IVFFlatはHNSWよりもインデックス構築時間は短く、メモリ使用量は少ないですが、ベクトルデータがある程度テーブルに格納されていないとインデックスが構築できません。また、速度とリコールのトレードオフが大きく、速度を重視するとリコールが下がりやすくなり、データの取りこぼしが発生しやすくなります。
一方、HNSWはIVFFlatよりもインデックス構築時間は長く、メモリ使用量は多くなりますが、テーブルにトレーニングデータを格納しておく必要はありません。また、速度とリコールのトレードオフが少なく、速度を重視してもリコール率の低下が見られず、両者のバランスが取れています。

また、2000次元以上のベクトルをインデックス化することはpgvector 0.5.1時点ではできません。ベクトルデータを次元削減して対応する必要があります。

ここではHNSWインデックスを構築します。

HNSWインデックス

インデックスの構築はCREATE INDEX文で行います。
利用できる演算子クラスは以下です。

演算子クラス説明vector_cosine_opsコサイン距離vector_ip_ops内積vector_l2_opsユークリッド距離

たとえば、以下でitemsテーブルのembedding列にコサイン距離に基づくHNSWインデックスを構築します。

test=# CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);

HNSWインデックのスオプション

CREATE INDEX文にWITH句を加えてHNSWインデクスのインデックスパラメータを指定できます。

パラメータ説明m層ごとの最大接続数（デフォルトは16）ef_constructionグラフ構築用の動的候補リストのサイズ（デフォルトは64）

test=# CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);

m、ef_constructionの値が高いほど、インデックスの構築時間、挿入速度を犠牲にしてリコールが向上します。また、ef_constructionはm*2未満だとエラーとなります。

HNSWインデックのクエリオプション

SET文で検索用の動的候補リストのサイズを指定します。デフォルトは40です。

SET hnsw.ef_search = 100;

高い値はリコールを向上させますが、速度を犠牲にします。

トランザクション内でSET LOCALを使用して、単一のクエリに設定します。

test=# BEGIN;
test=# SET LOCAL hnsw.ef_search = 100;
test=# SELECT ...
test=# COMMIT;

HNSWインデックのス作成進行状況

PostgreSQL 12以上であればインデックス作成の進行状況を、たとえば以下のSQL文で、インデックスを作成中のバックエンド毎に確認できます。

test=# SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;

HNSWインデックスの場合、pg_stat_progress_create_indexのphase列はinitializing（初期化中）またはloading tuples（タプルの読み込み中）が表示されます。

終わりに

pgvectorは、PostgreSQLの拡張機能としてベクトルデータの効率的な管理と類似性検索を可能にします。この記事では、pgvectorのインストールから設定、ベクトルデータの操作方法、最近傍検索の実行、さらにはインデックスの構築と最適化について解説しました。
pgvectorは近年目覚ましい技術発展を遂げている、大規模言語モデルによる文書生成にも利用可能です。大量のテキストデータに含まれるパターンや構造をベクトルデータとして抽出し、それを効率的に検索・分析することで文書の自動生成において重要な役割を果たします。
データベース技術やAI分野に関心がある方は、ぜひpgvectorを使ってみてください

PITRとはバックアップ／リストア方式の一つで、過去の指定した時点の状態に復元することが可能です。PITRは、データベースクラスタの物理コピー（ベースバックアップと呼びます）を取得し、以降のデータ変更が書き出される WALファイルを継続的に保存する（保存したものをWALアーカイブやアーカイブログと呼びます）ことで実現されます。現在稼働しているデータベースクラスタを障害やオペレーションミスから復旧したい場合には、保存していたベースバックアップにWALアーカイブを適用することで、ベースバックアップ取得時点からWALアーカイブが適用できる限りの任意の時点に復元することができます。

PITR は PostgreSQL のバックアップ方式としてよく用いられる手法ですが、DB 管理者が考慮すべきことや操作手順が増え、運用管理の手間が増えます。例えば、PITR の運用はベースバックアップの世代管理や、溜まり続ける古いアーカイブログファイルの削除は PostgreSQL の本体機能として備わっておらず、DB 管理者がそのような処理を行うスクリプトを用意しなければなりません。バックアップからのリカバリ作業も DB 管理者が手動で煩雑な手順を実施する必要があります。

Barman を利用すると、PITR に関する種々の操作を Barman のコマンド経由で簡単にできるようになります。また、Barman は複数のデータベースクラスタの PITR を一元管理できます。逆に言えば、PITR の世代管理やアーカイブログのパージ、リカバリ操作を自動で行えるようなスクリプトを既に自前で作成し運用している場合や、管理するデータベースクラスタが多くない場合は、Barman に利点を見出すことは少ないでしょう。

Barman 主な特徴は以下の通りです。

• PostgreSQL の PITR（ベースバックアップと WAL アーカイビング）を基にしている。
• ベースバックアップは ssh + rsync や pg_basebackup が使える。
• WAL アーカイビングは archive_command やストリーミングレプリケーションプロトコルが使える。
• フルバックアップのインクリメンタルバックアップができる。
• バックアップ・WAL の取得前後にフックスクリプトを呼び出せる。
• ネットワーク制限・データ転送の圧縮・WAL の圧縮・並行ジョブの実施によってワークロードを調整できる。
• 複数のデータベースクラスタのバックアップを Barman でまとめて管理できる。
• 世代管理などのバックアップポリシーを規定できる。

本文書では、Barman のインストールと基本的な使い方の解説をします。また、執筆時点で最新のBarmanバージョン 2.5 を基準に記載しています。

Barman のシステム要求

Barman 導入のための要件はドキュメントによると以下の通りです。

対応 OS: Linux/Unix
使用言語: Python 2.6 or 2.7
Python modules:
argcomplete
argh >= 0.21.2 <= 0.26.2
argparse (Python 2.6 only)
psycopg2 >= 2.4.2
python-dateutil <> 2.0
setuptools
対応 PostgreSQL: 8.3 以上
ただし、全ての機能を使いたい場合は 9.5.5 以上
オプション: rsync >= 3.0.4 (optional for PostgreSQL >= 9.2)

Barman は Windows には非対応ですが、Docker を通して Windows 上で動作させることは可能です。

Barman のインストールとセットアップ

この記事では 2 台の仮想マシン barman と pgsql01 を用い、barman サーバに Barman をインストールし、pgsql01 サーバには PostgreSQL 10 がセットアップ済みであるものとします。

それでは Barman を yumを使ってインストールいきます。

Barman の yumインストールは、EPEL リポジトリと PGDGリポジトリ（PostgreSQL の公式 yumリポジトリ）が登録されている必要があります。PGDGリポジトリはバックアップ対象の PostgreSQL と同一メジャーバージョンのリポジトリを選択するとよいです。異なるメジャーバージョンの PostgreSQL をバックアップ対象とする場合は、最も新しいメジャーバージョンの PGDG リポジトリを選択するとよいです。Barman は PGDGリポジトリから PostgreSQL の共有ライブラリをインストールしますが、共有ライブラリは後方互換性が保たれているからです。

（PGDGリポジトリのインストール）
[root@barman ~]# yum --assumeyes install epel-release https://download.postgresql.org/pub/repos/yum/10/redhat/rhel-7-x86_64/pgdg-centos10-10-2.noarch.rpm

その後、Barman と PostgreSQL をインストールします。PostgreSQL（のクライアントアプリケーション）は Barman のバックアップ・リカバリ処理時に必要となります。

（barmanパッケージのインストール）
[root@barman ~]# yum --assumeyes install barman postgresql10

インストールが完了すると、barman ユーザと barman グループが自動作成されます。barman ユーザのホームディレクトリは /var/lib/barman になります。しかし、barman ユーザを利用すると、バックアップファイルやリカバリ先の所有者権限が barman ユーザとなってしまいます。ここでは、PostgreSQL に合わせて postgresユーザを利用していきます。

（barmanユーザが作られていることを確認する）
[root@barman ~]# id barman
uid=997(barman) gid=995(barman) groups=995(barman)
[root@barman ~]# grep barm /etc/passwd
barman:x:997:995:Backup and Recovery Manager for PostgreSQL:/var/lib/barman:/bin/bash

まずは Barman 自体と、管理対象のサーバ情報を設定します。設定ファイルは INI 形式です。Barman 自体のグローバル設定は /etc/barman.conf で行います。[barman] セクション以下に各パラメータを設定することになります。Barman 実行ユーザを postgres とし、Barman のホームディレクトリを postgres ユーザのホームディレクトリとする以外は、デフォルトのままとしておきます。

（barmanのグローバル設定を変更する）
[root@barman ~]# vi /etc/barman.conf
barman_user = postgres
barman_home = /var/lib/pgsql

Barman の管理対象となる PostgreSQL サーバの情報は、/etc/barman.d 以下にサーバ単位でファイルを作成します。ファイル名は任意で構いませんが、PostgreSQL サーバ名と合わせておくと識別しやすいです。 ファイルの内容は、一意なセクションが一つのバックアップ設定となります。たとえば、以下では、pgsql01 サーバに対して、[ssh-pgsql01] セクションと [streaming-pgsqo01] セクションという 2 つのバックアップ設定を設定しています。Barman の公式ドキュメントではこのセクションにサーバ名を指定し、barman コマンドの < server_name > 引数で使うことが記載されていますが、とくにセクションとサーバ名を合わせる必要はありません。あくまで、一つのセクションが一つのバックアップ設定です。

（barman個別設定を追加する）
[root@barman ~]# cat << EOT > /etc/barman.d/pgsql01.conf
> [ssh-pgsql01]
> ssh_command = ssh -q postgres@pgsql01
> conninfo = host=pgsql01 user=postgres dbname=postgres
> backup_method = rsync ; ベースバックアップは rsync で行なう
> archiver = on ; archive_command による WAL アーカイビング
>
> [streaming-pgsql01]
> conninfo = host=pgsql01 user=postgres dbname=postgres port=5433
> backup_method = postgres ; ベースバックアップは pg_basebackup で行なう
> streaming_archiver = on ; ストリーミングレプリケーションプロトコルによる WAL アーカイビング
> slot_name = barman ; レプリケーションスロットを使う（streaming_archiver = on の場合に推奨）
> EOT

その他のパラメータについては man 5 barman コマンドで調べることができます。

/etc/barman.d 以下にテンプレートファイルが用意されているので、それを流用してもよいです。なお、barman 実行ユーザが $HOME/.barman.conf を所有していると、そちらが優先されます。

パスワード無しの SSH 接続設定

ベースバックアップの取得に SSH と rsync を用いる場合は Barman 実行ユーザと PostgreSQL 実行ユーザが両方向にパスワード無しで SSH 接続できるようにしておく必要があります。以下のように SSH 鍵の作成と、公開鍵の配布を行います。事前に（セキュリティ上の制約があるならば、一時的に） barman 実行ユーザと PostgreSQL 実行ユーザにパスワードを設定し、パスワード認証で SSH 接続ができるようにしておく必要があります。

（パスワード入力無しでssh接続できるようにする）
[postgres@barman ~]$ ssh-keygen -t rsa
[postgres@barman ~]$ ssh-copy-id postgres@pgsql01
/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/var/lib/pgsql/.ssh/id_rsa.pub"
/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
Warning: Permanently added 'pgsql01,192.168.1.12' (ECDSA) to the list of known hosts.
postgres@pgsql01's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'postgres@pgsql01'"
and check to make sure that only the key(s) you wanted were added.

[postgres@pgsql01 ~]$ ssh-keygen -t rsa
[postgres@pgsql01 ~]$ ssh-copy-id postgres@barman
/bin/ssh-copy-id: INFO: Source of key(s) to be installed: "/var/lib/pgsql/.ssh/id_rsa.pub"
/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to filter out any that are already installed
/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you are prompted now it is to install the new keys
Warning: Permanently added 'barman,192.168.1.11' (ECDSA) to the list of known hosts.
postgres@barman's password:

Number of key(s) added: 1

Now try logging into the machine, with: "ssh 'postgres@barman'"
and check to make sure that only the key(s) you wanted were added.

ここまでで barman のインストールと設定ができました。

archive_command による WALアーカイブと SSH + rsync によるベースバックアップ

それでは /etc/barman.d/pgsql01.conf の [ssh-pgsql01] セクションで定義したバックアップを試していきましょう。

barman の check サブコマンドで指定のバックアップ設定が正しいかどうか確認します。また、これによってバックアップに必要なディレクトリが自動作成されます。この操作は新しいバックアップ設定を追加する都度、必須です。WAL archive と PostgreSQL 以外は全て OK となることを確認してください。なお、出力結果に「ssh output clean: FAILED (the configured ssh_command must not add anything to the remote command output)」た含まれる場合は、当該のバックアップセクションの ssh_command パラメータに設定した ssh コマンドに -q オプションを加えると、出力を抑制できます。

（barmanバックアップ設定が正しいか確認する）
[postgres@barman ~]$ barman check ssh-pgsql01
Server ssh-pgsql01:
WAL archive: FAILED (please make sure WAL shipping is setup)
PostgreSQL: FAILED
directories: OK
retention policy settings: OK
backup maximum age: OK (no last_backup_maximum_age provided)
compression settings: OK
failed backups: OK (there are 0 failed backups)
minimum redundancy requirements: OK (have 0 backups, expected at least 0)
ssh: OK (PostgreSQL server)
not in recovery: OK
archiver errors: OK

続けて PostgreSQLサーバで WALアーカイビングが行われるように postgresql.conf を設定します。

（postgresql.confファイル）
#wal_level = replica
archive_mode = on
archive_command = 'rsync -a %p postgres@barman:/var/lib/pgsql/ssh-pgsql01/incoming/%f'

なお、archive_command に指定するアーカイブWAL の出力先は barmanコマンドで確認できます。サブコマンド show-server の引数に確認したいバックアップ設定セクション名を指定すると、設定地を確認できます。

（ssh-pgsql01 の incoming_wals_directory設定を確認する）
[postgres@barman ~]$ barman show-server ssh-pgsql01 | grep incoming_wals_directory
incoming_wals_directory: /var/lib/pgsql/ssh-pgsql01/incoming

また、Barman と PostgreSQL 間のクライアント認証を trust接続にしておきます。これは本記事の試験用の設定であってパスワード認証にすることもできます。

host all all samenet trust
host replication all samenet trust

設定が完了したら PostgreSQL を起動します。

[postgres@pgsql01 ~]$ pg_ctl -w start

pgbenchコマンドでデータを生成して barman サーバに WALアーカイビングが行われることを確認します。合わせて、Barman がテーブルスペースもバックアップできることを確認するため、テーブルスペースも作成しておきます。

（テーブルスペース作成し、pgbenchでデータ生成する）
[postgres@pgsql01 ~]$ mkdir /tmp/ssh_tbls
[postgres@pgsql01 ~]$ psql << EOQ
> CREATE TABLESPACE ssh_tbls LOCATION '/tmp/ssh_tbls';
> CREATE DATABASE bench TABLESPACE ssh_tbls;
> EOQ
[postgres@pgsql01 ~]$ pgbench -i -s 10 bench

#### #### #### ####

[postgres@barman ~]$ find ssh-pgsql01 -name ???????????????????????? -ls
101300493 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:06 ssh-pgsql01/incoming/000000010000000000000001
101300494 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000002
101300495 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000003
101300496 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000004
101300497 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000005
101300498 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000006
101300499 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000007
101300500 16384 -rw------- 1 postgres postgres 16777216 Oct 25 11:08 ssh-pgsql01/incoming/000000010000000000000008

barmanサーバに WAL がアーカイブされています。PostgreSQL 側で設定したアーカイブ先は /var/lib/pgsql/ssh-pgsql01/incoming ですが、自動で /var/lib/pgsql/ssh-pgsql01/wals 以下にタイムライン ID + xlogID というディレクトリ毎に分けて格納されるようです。

barman からオンラインでベースバックアップを取得します。動作検証のため、バックアップを取るときに PostgreSQLサーバでは pgbenchコマンドを適当に 60 秒ほど実行させてトランザクションが発生している状態にしておきます。

[postgres@pgsql01 ~]$ pgbench -T 60 bench

#### #### #### ####

[postgres@barman ~]$ barman backup --immediate-checkpoint ssh-pgsql01
Starting backup using rsync-exclusive method for server ssh-pgsql01 in /var/lib/pgsql/ssh-pgsql01/base/20181025T111311
Backup start at LSN: 0/A000070 (00000001000000000000000A, 00000070)
This is the first backup for server ssh-pgsql01
WAL segments preceding the current backup have been found:
000000010000000000000001 from server ssh-pgsql01 has been removed
000000010000000000000002 from server ssh-pgsql01 has been removed
000000010000000000000003 from server ssh-pgsql01 has been removed
000000010000000000000004 from server ssh-pgsql01 has been removed
000000010000000000000005 from server ssh-pgsql01 has been removed
000000010000000000000006 from server ssh-pgsql01 has been removed
000000010000000000000007 from server ssh-pgsql01 has been removed
000000010000000000000008 from server ssh-pgsql01 has been removed
000000010000000000000009 from server ssh-pgsql01 has been removed
Starting backup copy via rsync/SSH for 20181025T111311
Copy done (time: 5 seconds)
This is the first backup for server ssh-pgsql01
Asking PostgreSQL server to finalize the backup.
Backup size: 193.0 MiB
Backup end at LSN: 0/1527D560 (000000010000000000000015, 0027D560)
Backup completed (start time: 2018-10-25 11:14:59.514997, elapsed time: 7 seconds)
Processing xlog segments from file archival for ssh-pgsql01
00000001000000000000000A.00000070.backup
000000010000000000000015

出力結果から、rsync と SSH によってベースバックアップが /var/lib/pgsql/ssh-pgsql01/base/20181025T111311 に取得され、不要となったアーカイブログが自動で削除されていることが読み取れます。また、テーブルスペースも格納されています。

（テーブルスペースの確認）
[postgres@pgsql01 ~]$ oid2name -s
All tablespaces:
Oid Tablespace Name
------------------------
1663 pg_default
1664 pg_global
16384 ssh_tbls

#### #### #### ####

[postgres@barman ~]$ ls ssh-pgsql01/base/20181025T111311/
16384 backup.info data

barman コマンドからも list-backup サブコマンドにバックアップ設定を渡すと指定の設定で取得したバックアップ情報を確認することができます。バックアップ情報のうち、「20181025T111311」といったタイムスタンプは barman の各種コマンドで指定する < backup_id > で使われます。

（list-backup サブコマンドによる確認）
[postgres@barman ~]$ barman list-backup ssh-pgsql01
ssh-pgsql01 20181025T111311 - Thu Oct 25 11:14:00 2018 - Size: 385.0 MiB - WAL Size: 0 B (tablespaces: ssh_tbls:/tmp/ssh_tbls)
[postgres@barman ~]$ barman list-backup --minimal ssh-pgsql01
20181025T111311

パラレルジョブによるリカバリ

それでは取得したバックアップをリカバリしてみます。ここでは並列処理でのリカバリを試すことにします。リカバリ先は pgsql01 サーバですが、既存のデータベースクラスタはそのままにしておき、異なるデータベースクラスタのパスとテーブルスペースのパスを使うようにリカバリします。

--remote-ssh-command オプションを指定しないと barmanコマンドを実行したサーバでリカバリがされます。--jobs オプションでリカバリ時の並列度を指定することができます。並列度は Barman の設定ファイルでも指定可能です。なお、並列処理が有効となるのはバックアップ方法（設定ファイルの backup_method）に rsync を指定した場合のみです。

[postgres@barman ~]$ barman recover --jobs 4 --remote-ssh-command 'ssh postgres@pgsql01' --tablespace ssh_tbls:/tmp/ssh_tbls_recover ssh-pgsql01 20181025T111311 /var/lib/pgsql/10/data_recover
{{ 前略 }}

IMPORTANT
These settings have been modified to prevent data losses

postgresql.conf line 218: archive_command = false

Recovery completed (start time: 2018-10-25 14:11:10.084191, elapsed time: 17 seconds)

Your PostgreSQL server has been successfully prepared for recovery!

pgsql01 サーバにデータベースクラスタが配置されており、テーブルスペースのリンボリックリンクも正しく修正されていることが確認できます。

[postgres@pgsql01 ~]$ ls -l /var/lib/pgsql/10/data_recover/base/
total 36
drwx------. 2 postgres postgres 8192 Oct 25 11:06 1
drwx------. 2 postgres postgres 8192 Oct 25 11:06 12952
drwx------. 2 postgres postgres 8192 Oct 25 11:07 12953
[postgres@pgsql01 ~]$ ls -l /var/lib/pgsql/10/data_recover/pg_tblspc/
total 0
lrwxrwxrwx. 1 postgres postgres 21 Oct 25 14:10 16384 -> /tmp/ssh_tbls_recover

ストリーミングレプリケーションプロトコルによる WALアーカイブとベースバックアップ

今度はストリーミングレプリケーションプロトコルを使った WALアーカイブとベースバックアップを試します。
/etc/barman.d/pgsql01.conf の [streaming-pgsql01] セクションで定義したバックアップを使用します。
なお、この方法は、barman サーバ側に PostgreSQL コマンドの pg_receivewal と pg_basebackup が必要です。
事前に Barman 実行ユーザが両コマンドを使えるようにしておく必要があります。

新しいサーバ設定を実行する場合は、check サブコマンドを実行しておきます。

[postgres@barman ~]$ barman check streaming-pgsql01

先程リカバリしたデータベースクラスタ (/var/lib/pgsql/10/data_recover) のポート番号を変更し、アーカイブロギングをオフにして起動します。

（postgresql.conf設定）
port = 5433
#wal_level = replica
#archive_mode = on
#max_wal_senders = 10
#max_replication_slots = 10

PostgreSQL を起動します。

[postgres@pgsql01 ~]$ pg_ctl -w start -D 10/data_recover

ストリーミングレプリケーションプロトコルを使って WAL をアーカイビングを開始できるようにします。まず WAL の送信元に barman 向けのレプリケーションスロットを作成し、WAL アーカイブにそれを用いるようにオプション指定します。これはオンライン WAL がアーカイブされる前にそれが再利用または削除されるのを防ぐためです。

[postgres@barman ~]$ barman receive-wal --create-slot streaming-pgsql01
Creating physical replication slot 'barman' on server 'streaming-pgsql01'
Replication slot 'barman' created

レプリケーションスロットが作成されたら WAL の受信を開始します。このコマンドはフォアグランドプロセスなので、バックグラウンドに回しておきます。

（barmanによるWAL受信）
[postgres@barman ~]$ barman receive-wal streaming-pgsql01 &>/dev/null &
[1] 26697

PostgreSQL サーバで pgbench コマンドを適当に 30 秒ほど実行させてトランザクション進めます。

[postgres@pgsql01 ~]$ pgbench -T 30 -p 5433 bench

WAL がアーカイビングされています。

[postgres@barman ~]$ find streaming-pgsql01 -name ???????????????????????? -ls
802583 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/000000010000000000000016
433861 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/000000010000000000000017
433874 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/000000010000000000000018
433875 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/000000010000000000000019
433876 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/00000001000000000000001A
433877 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/00000001000000000000001B
433878 16384 -rw------- 1 postgres postgres 16777216 Oct 25 15:54 streaming-pgsql01/streaming/00000001000000000000001C

barman からベースバックアップを取得します。ストリーミングレプリケーションプロトコルを用いた WAL アーカイビングの場合、予め Barman のメンテナンスコマンドを実行していなければいけません。

[postgres@barman ~]$ barman archive-wal streaming-pgsql01
Processing xlog segments from streaming for streaming-pgsql01
00000001000000000000002B
00000001000000000000002C
00000001000000000000002D
00000001000000000000002E
00000001000000000000002F
000000010000000000000030
000000010000000000000031

これによって Barman サーバで受信した WAL アーカイブが、今度は Barman の wal ディレクトリにアーカイブされます。なお、この操作は barman cron サブコマンドでも可能です。cron サブコマンドの場合は Barman が管理している全てのバックアップを対象に WAL アーカイブのアーカイブ処理が行われます。加えて、追加の設定をしている場合は、WAL アーカイブの圧縮・ベースバックアップの世代管理・事前事後のフックスクリプト実行が行われます。/etc/crond.d/barman ファイルが Barman インストール時に用意されるので、定期実行したい場合はそのファイルを編集するとよいでしょう。

Barman のメンテナンスコマンドを実行したら、barman backup サブコマンドでベースバックアップの取得が行えます。

[postgres@barman ~]$ barman backup streaming-pgsql01
Starting backup using postgres method for server streaming-pgsql01 in /var/lib/pgsql/streaming-pgsql01/base/20181026T090225
Backup start at LSN: 0/4B5B0898 (00000001000000000000004B, 005B0898)
Starting backup copy via pg_basebackup for 20181026T090225
Copy done (time: 1 second)
Finalising the backup.
Backup size: 191.7 MiB
Backup end at LSN: 0/4D000000 (00000001000000000000004C, 00000000)
Backup completed (start time: 2018-10-26 09:02:25.064266, elapsed time: 1 second)
Processing xlog segments from streaming for streaming-pgsql01
        00000001000000000000004B

barman コマンドの list-backup サブコマンドでバックアップが取得できていることが確認できます。

（list-backup サブコマンドによる確認）
[postgres@barman ~]$ barman list-backup streaming-pgsql01
streaming-pgsql01 20181026T090225 - Fri Oct 26 09:02:27 2018 - Size: 207.7 MiB - WAL Size: 96.0 MiB (tablespaces: ssh_tbls:/tmp/ssh_tbls_recover)

任意の時点にリカバリ

それでは取得したバックアップをリカバリしてみます。PITR によって任意の時間にデータベースをリカバリしてみます。リカバリ先は pgsql01 サーバですが、既存のデータベースクラスタはそのままにしておき、異なるデータベースクラスタのパスを使うようにリカバリします。
先程ベースバックアップを取得したので、PostgreSQL サーバで pgbench を実行してトランザクションを進めます。

[postgres@pgsql01 ~]$ pgbench -T 30 -p 5433 bench

ベンチマークテーブルの pgbench_history テーブルに格納されているタイムスタンプを確認して、リカバリする時刻を決定します。

（ベンチマークの開始と終了時刻を確認）
[postgres@pgsql01 ~]$ psql -p 5433 bench
bench=# select min(mtime), max(mtime) from pgbench_history;
            min             |            max
----------------------------+----------------------------
 2018-10-26 09:02:57.827964 | 2018-10-26 09:03:27.823867
(1 row)

ここでは、リカバリ時刻を 2018-10-26 09:03:15 として、barman コマンドの recover サブコマンドでリカバリします。

[postgres@barman ~]$ barman recover --remote-ssh-command 'ssh postgres@pgsql01' --tablespace ssh_tbls:/tmp/ssh_tbls_recover02 --target-ti
me '2018-10-26 09:03:15' streaming-pgsql01 20181026T090225 /var/lib/pgsql/10/data_recover02
Starting remote restore for server streaming-pgsql01 using backup 20181026T090225
Destination directory: /var/lib/pgsql/10/data_recover02
Doing PITR. Recovery target time: '2018-10-26 09:03:15+00:00'
Using safe horizon time for smart rsync copy: 2018-10-26 08:11:09+00:00
        16384, ssh_tbls, /tmp/ssh_tbls_recover02
Copying the base backup.
Copying required WAL segments.
Generating recovery.conf
Identify dangerous settings in destination directory.

IMPORTANT
These settings have been modified to prevent data losses

postgresql.conf line 219: archive_command = false

Recovery completed (start time: 2018-10-26 09:07:15.312212, elapsed time: 21 seconds)

Your PostgreSQL server has been successfully prepared for recovery!

リカバリしたデータベースクラスタ (/var/lib/pgsql/10/data_recover02) のポート番号を変更して起動し、pgbench_history テーブルに格納されているタイムスタンプの最大値を確認します。

（postgresql.conf設定）
port = 5434

#### #### #### ####

（PostgreSQL の起動）
[postgres@pgsql01 ~]$ pg_ctl -w start -D 10/data_recover02

#### #### #### ####

（ベンチマークテーブルのタイムスタンプを確認）
[postgres@pgsql01 ~]$ psql -p 5434 bench
psql (10.5)
Type "help" for help.

bench=# select min(mtime), max(mtime) from pgbench_history;
            min             |            max
----------------------------+---------------------------
 2018-10-26 09:02:57.827964 | 2018-10-26 09:03:14.99833
(1 row)

問題なく、指定の時刻までリカバリができています。

まとめ

以上、PostgreSQL の PITR 補助ツールの Barman を使って基本的なバックアップとリカバリの動作を確認しました。
複数のデータベースインスタンスの PITR を一元管理できる、煩雑な PITR 操作を簡単にできるといった点に魅力を感じるようでしたら、一度試してみてはいかがでしょうか。

Barman は以下の公式サイトから入手可能です。

[Barman]
https://www.pgbarman.org/

同サイトにマニュアルページもあります。

[Barman Manual]
http://docs.pgbarman.org/release/2.5/