PostgreSQL MultiXact エラーの原因と対処
目次
PostgreSQLの運用で multixact "members" limit exceeded や database "xxx" must be vacuumed before N more MultiXactIds are used に遭遇すると、見慣れたトランザクションID周回(XID wraparound)とは別系統の話なので手が止まりがちです。MultiXactは共有行ロックを複数トランザクションで保持するときだけ使われる仕組みで、専用のID空間とディスク領域(pg_multixact)、専用の凍結設定を持ちます。
エラーメッセージごとの初動、原因テーブルの特定、書き込みが止まった状態からの復旧、再発防止の設計方針を順に見ていきます。
結論:MultiXact のトラブルは「共有行ロックの大量発生」と「凍結の遅れ」で説明できる
MultiXact関連の障害は、ほぼ次の2つの掛け算で起きます。
- 共有行ロックの大量発生。同じ行に複数トランザクションが
FOR KEY SHARE/FOR SHAREを取るとMultiXactIdが払い出されます。最大の発生源は外部キー制約のチェックです。親テーブルの特定の行(マスタの1行、テナントの1行など)を多数の子行INSERTが同時に参照すると、その1行のxmaxにメンバーが積み上がります。 - 凍結(freeze)の遅れ。MultiXactIdとメンバー情報は、VACUUMの凍結処理で初めて切り捨てられます。長時間トランザクション、prepared transaction、autovacuumの設定抑制、巨大テーブルでVACUUMが完走しないといった要因で凍結が追いつかないと、ID空間とディスクが減りません。
対処も2方向です。短期的にはVACUUMを強制して凍結を進め、中期的には共有ロックの発生源を減らします。autovacuum_multixact_freeze_max_age などの設定調整は、この2つを支える位置づけです。
エラーメッセージ別の対処早見表
| メッセージ | 状態 | 最初にやること |
|---|---|---|
WARNING: database "x" must be vacuumed before N more MultiXactIds are used |
MultiXactId の残り余裕が警告水準。まだ書き込みは可能 | 対象DBで freeze 設定を下げた VACUUM。原因テーブルを relminmxid で特定 |
ERROR: multixact "members" limit exceeded |
pg_multixact/members のID空間が枯渇し、共有ロック取得自体が失敗 |
HINT に出るDB OID のDBで vacuum_multixact_freeze_min_age = 0 にして VACUUM |
ERROR: database is not accepting commands that generate new MultiXactIds to avoid wraparound data loss in database "x" |
新規 MultiXactId を払い出す操作(=書き込み全般)が拒否 | 再起動より先に VACUUM を完走させる。詳細は後述の復旧手順 |
ERROR: MultiXactId NNN has not been created yet -- apparent wraparound |
SLRU の内容と制御情報の不整合。古いマイナーバージョンの既知不具合でも発生した事例がある | 書き込みを止めてバックアップを確保。マイナーバージョンを最新化し、ベンダ/コミュニティに相談 |
could not access status of transaction NNN + Could not open file "pg_multixact/members/XXXX" |
members ファイルの欠損 | 同上。手動でのファイル作成・削除は行わない |
LWLock 待機で MultiXactOffset* / MultiXactMember* 系イベントが上位 |
SLRU キャッシュの競合による性能劣化(エラーではない) | 共有ロックを取るクエリの特定。PostgreSQL 17 以降はSLRUバッファのGUCも検討 |
※待機イベント名はバージョンで改名されています(11以前は MultiXactOffsetControlLock など、13で ControlLock の接尾辞が整理、17でSLRUロックの構造自体が変更)。稼働バージョンのドキュメントで名称を確認してください。
MultiXact とは何か:xmax・pg_multixact・SLRU の関係
行ヘッダの xmax は本来「その行を削除/更新したトランザクションID」ですが、行ロックの記録にも使われます。ロック保持者が1つだけなら xmax に単なるXIDが入り、ロック専用かどうかは t_infomask のビットで区別されます。
保持者が2つ以上になると、PostgreSQLは複数のXIDとロックモードの組を1つのMultiXactIdにまとめます。xmax にそのMultiXactIdを格納し、HEAP_XMAX_IS_MULTI(0x1000)ビットを立てます。実体は2つのSLRU(simple LRU)領域に書かれます。
pg_multixact/offsets:MultiXactId → メンバー配列の開始位置。MultiXactId ごとに4バイト程度pg_multixact/members:メンバー(XID+ロックモード)の配列。メンバー1件あたり5バイト程度
MultiXactIdとメンバーには別々に上限があります。どちらも32ビットの周回カウンタなので、MultiXactIdは約43億、メンバー総数も約43億が理論上の限界で、members のディスクサイズは最大20GB規模になり得ます。multixact "members" limit exceeded はメンバー側の枯渇です。
メンバーが爆発的に増えるのは、MultiXactに追記できないためです。既にMultiXactIdが入っている行に新しいロック保持者が加わると、既存メンバーと新規メンバーの全体を持つ新しいMultiXactIdが作られます。同一行にN個の保持者が順に群がれば、消費メンバー数はNの二乗オーダーです。ホットな親行1行で members を使い切れるのはこのためです。
MultiXactが凍結対象になったのは、PostgreSQL 9.3で行ロックが細分化され(FOR KEY SHARE / FOR NO KEY UPDATE の導入)、外部キーチェックが FOR KEY SHARE を使うようになってからです。9.3〜9.4系では切り捨て処理周りの不具合修正が重なったので、古いバージョンならマイナーバージョンの状況をまず確認してください(PostgreSQL EOL対応|確認手順と移行の判断基準)。
原因の切り分け手順
手順1:クラスタ全体の MultiXact 年齢と残り余裕を確認する
どれだけ切迫しているかを数値で把握します。
SELECT datname,
datminmxid,
mxid_age(datminmxid) AS mxid_age,
(2^31)::bigint - mxid_age(datminmxid) AS remaining
FROM pg_database
ORDER BY mxid_age DESC;
SELECT next_multixact_id, next_multi_offset,
oldest_multi_xid, oldest_multi_dbid
FROM pg_control_checkpoint();
判断基準は次のとおりです。
mxid_ageがautovacuum_multixact_freeze_max_age(デフォルト4億)超 → anti-wraparound autovacuum が走っているはず。pg_stat_activityで確認し、走っていなければ理由を探す- 10億超 → 業務影響を覚悟して手動 VACUUM を並列投入する段階
- 16億前後(
vacuum_multixact_failsafe_age、PostgreSQL 14 以降のデフォルト16億)超 → VACUUM はインデックス処理やコスト遅延をスキップして凍結優先モードに入る
next_multi_offset を定期的に記録しておくと、メンバーの消費速度が分かります。1時間で数千万進むようなら設計側の対処が必須です。
手順2:原因テーブルを relminmxid から特定する
datminmxid はそのDB内の pg_class.relminmxid の最小値です。対象DBに接続して犯人を探します。
SELECT n.nspname, c.relname, c.relkind,
c.relminmxid, mxid_age(c.relminmxid) AS mxid_age,
pg_size_pretty(pg_relation_size(c.oid)) AS size
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relminmxid <> '0'::xid
ORDER BY mxid_age DESC
LIMIT 20;
TOASTテーブル(relkind = 't')も対象に入れてください。本体が小さいのにTOASTだけ古いケースがあります。上位に来たテーブルが外部キーの参照先(親)かどうかを確認します。
SELECT conrelid::regclass AS child, confrelid::regclass AS parent, conname
FROM pg_constraint
WHERE contype = 'f' AND confrelid = 'public.対象テーブル'::regclass;
子テーブルが多く、子へのINSERT/UPDATEが高頻度なら、ほぼ確定です。
手順3:pg_multixact のディスク使用量とメンバー消費量を見る
オンプレやEC2ならディレクトリを直接見ます。
du -sh $PGDATA/pg_multixact/offsets $PGDATA/pg_multixact/members
ls -l $PGDATA/pg_multixact/members | wc -l
セグメントファイルは1つ256KB固定なので、ファイル数×256KBが使用量です。数GB〜十数GBまで育っているなら、members の枯渇が近いと判断できます。マネージドサービスでディレクトリが見えない場合は、手順1の next_multi_offset の増分と mxid_age の推移で代替します。
手順4:MultiXact 系の待機イベントとロック発生元のクエリを突き止める
エラーが出ていなくても、members が肥大化するとSLRUキャッシュのヒット率が落ち、LWLock 待機が増えて全体のスループットが下がります。
SELECT wait_event_type, wait_event, count(*)
FROM pg_stat_activity
WHERE state <> 'idle' AND wait_event IS NOT NULL
GROUP BY 1, 2
ORDER BY 3 DESC;
LWLock の MultiXactOffset・MultiXactMember 系が上位に来たら、共有ロックの発生元を追います。
SELECT pid, state, wait_event_type, wait_event,
pg_blocking_pids(pid) AS blocked_by,
now() - xact_start AS xact_age,
left(query, 120) AS query
FROM pg_stat_activity
WHERE backend_type = 'client backend' AND state <> 'idle'
ORDER BY xact_age DESC NULLS LAST;
特定の行に本当にメンバーが積まれているかは、pageinspect で裏を取れます。
CREATE EXTENSION IF NOT EXISTS pageinspect;
SELECT lp, t_xmin, t_xmax, (t_infomask & 4096) <> 0 AS xmax_is_multi
FROM heap_page_items(get_raw_page('public.親テーブル', 0))
WHERE t_xmax <> 0;
-- xmax_is_multi が true の値を渡す
SELECT * FROM pg_get_multixact_members('12345');
pg_get_multixact_members() はメンバーのXIDとロックモード(keysh、sh、nokeyupd など)を返します。keysh が大量に並んでいれば外部キー起因です。
この記事のテーマをさらに学べる本
PostgreSQLの内部構造と照らし合わせながら設計・運用計画を解説しており、運用判断の土台づくりに役立ちます。
楽天ブックスで詳しく見る対処:凍結を進める・ロック競合を減らす・設定を見直す
即時対応はVACUUMによる凍結です。通常のVACUUMは vacuum_multixact_freeze_min_age(デフォルト500万)より新しいMultiXactを残すので、切迫時は明示的に下げます。
SET vacuum_multixact_freeze_min_age = 0;
SET vacuum_multixact_freeze_table_age = 0;
SET vacuum_freeze_min_age = 0;
SET vacuum_cost_delay = 0;
VACUUM (VERBOSE) public.対象テーブル;
クラスタ全体なら、vacuumdb の並列実行とMultiXact年齢による絞り込みが使えます。
vacuumdb --all --freeze --jobs=4 --min-mxid-age=200000000 --echo
設定の見直しは3点です。autovacuum_multixact_freeze_max_age(デフォルト4億)に達するとanti-wraparound autovacuumが強制起動します。members の消費が速いシステムでは1〜1.5億程度まで下げて早めに凍結させる判断もあり得ます。MultiXactメンバーの使用量が一定水準を超えると、サーバ側がこの値を内部的に引き下げてautovacuumを前倒しする仕組みもあります。凍結が追いつかない原因が単純に遅いことなら、autovacuum_vacuum_cost_delay(デフォルト2ms)を縮めるか autovacuum_max_workers を増やします。特定の親テーブルだけ厳しくしたい場合は、テーブル単位の上書きが有効です。
ALTER TABLE public.親テーブル SET (
autovacuum_multixact_freeze_min_age = 1000000,
autovacuum_multixact_freeze_max_age = 100000000,
autovacuum_vacuum_cost_delay = 0
);
PostgreSQL 17以降はSLRUのバッファ数を multixact_offset_buffers / multixact_member_buffers で設定でき、ロック構造も改善されています。MultiXact系のLWLock待機が常態化しているなら、バージョンアップが最も有効な対策になることもあります(値の範囲と既定値は使用バージョンのドキュメントで確認してください)。
書き込みが拒否された状態からの復旧手順
database is not accepting commands that generate new MultiXactIds が出ている場合、焦って再起動すると復旧が長引きます。順番は次のとおりです。
- 対象DBを確定する。エラーメッセージのDB名、または
pg_control_checkpoint()のoldest_multi_dbidをpg_database.oidと突き合わせます - 凍結の上限要因を排除する。VACUUMは実行中のトランザクションが参照しうるMultiXactを凍結できません。以下を確認し、不要なものを終了させます
SELECT pid, now() - xact_start AS age, state, left(query, 80)
FROM pg_stat_activity
WHERE xact_start IS NOT NULL AND now() - xact_start > interval '10 min'
ORDER BY age DESC;
SELECT * FROM pg_prepared_xacts; -- 放置された2相コミット
SELECT slot_name, active, xmin, catalog_xmin FROM pg_replication_slots;
- VACUUMを投入する。この状態でも読み取りとVACUUMは実行できます。手順2で特定した
relminmxidの古い順に、前述の設定を下げたVACUUMを流します - 進捗を監視する
SELECT pid, relid::regclass, phase, heap_blks_total, heap_blks_scanned
FROM pg_stat_progress_vacuum;
- 切り捨てを確認する。
datminmxidが進んだあと、pg_multixactの実ファイル削除はチェックポイント時に行われます。CHECKPOINT;を実行し、duで縮小を確認します - autovacuumは止めない。
autovacuum = offにしても周回防止のautovacuumは起動しますが、意図的な無効化は状況を悪化させます
members limit exceeded だけが出ている場合、止まるのは共有ロックを必要とする操作(外部キーを持つテーブルへのINSERT/UPDATEなど)で、書き込み全体ではありません。復旧手順は同じです。
よくある質問
MultiXact の年齢はどのビューで確認できる?
DB単位なら pg_database.datminmxid、テーブル単位なら pg_class.relminmxid です。どちらも生のIDなので、mxid_age() 関数で現在値との差に変換して判断します。クラスタ全体の最新IDとメンバー消費位置は、pg_control_checkpoint() の next_multixact_id と next_multi_offset で見られます。XID用の age() / datfrozenxid とは別系統なので、監視項目は両方を登録してください。
autovacuum_multixact_freeze_max_age は下げてもいい?
下げられます。下げるとanti-wraparound autovacuumが早く走り、pg_multixact が小さく保たれます。代償は凍結のための全ページスキャンが頻発することで、巨大テーブルではI/Oが増えます。目安としては、メンバー消費が速く(next_multi_offset が日に億オーダーで進む)既定の4億がリスクに見えるシステムで1〜2億へ。MultiXactをほとんど使わないシステムなら既定のままで問題ありません。変更前に原因テーブルだけテーブル単位で下げ、影響を見るのが安全です。
pg_multixact 配下のファイルは手動で削除できる?
削除しないでください。pg_multixact は制御ファイル上の oldest_multi_xid と整合している必要があり、手で消すと could not access status of transaction や apparent wraparound が発生し、行の可視性判定ができなくなります。縮小させる正しい方法は、VACUUMで datminmxid を進め、チェックポイントで切り捨てさせることだけです。すでに欠損が起きている場合は、まずバックアップを確保し、物理バックアップからのリストアや論理ダンプでの再構築を検討します。
OSS-DB Silver 対策テキスト(OSS教科書)
PostgreSQLの仕組みを体系的に学ぶなら、OSS-DB Silverの公式対応テキストが近道です。資格を取らなくても基礎固めに役立ちます。
再発防止:外部キー設計と VACUUM 運用で MultiXact を増やさない
設定調整は時間稼ぎで、根本は共有ロックの発生量です。実務で有効な対策は4つあります。
1. ホットな親行への外部キーを避ける
全レコードが同じ1行を参照する外部キー(ステータスマスタ、区分コード、テナント代表行など)は、MultiXactの最大の生産設備です。値域が固定なら CHECK 制約や列挙型で表現する、あるいは参照整合性をアプリ側やバッチ検証に委ねる、という割り切りが有効です。Oracleから移行した設計では外部キーを機械的に移植しがちなので、移行時にレビューしておくとよいでしょう(Oracle PostgreSQL移行の注意点|症状別の切り分けと対処)。
2. SELECT ... FOR SHARE を排他制御の代用にしない
アプリケーションレベルの排他目的なら pg_advisory_xact_lock() を使います。アドバイザリロックは行ヘッダに記録されないので、MultiXactを一切消費しません。
3. トランザクションを短くする
FKチェックで取得した FOR KEY SHARE は、トランザクション終了まで保持されます。同じ親行に群がる時間が短ければ同時保持者が減り、メンバー数も大きく下がります。1トランザクションで大量の子行をINSERTする処理は、親行ごとにまとめる、コミット単位を分けるだけで改善することがあります。
4. 監視項目に MultiXact を加える
mxid_age(datminmxid)、next_multi_offset の増加率、pg_multixact のディスク使用量を定期取得し、閾値アラートを設定します。XIDの年齢だけ監視してMultiXactを見ていない構成は珍しくありません。VACUUMが完走しているかの確認方法とあわせ、日常の点検項目に落とし込んでおくと、警告が出てから慌てずに済みます(PostgreSQLが遅い・詰まる原因|VACUUMと実行計画、ロック)。
さらに学ぶには
MVCC・凍結・ロックの内部構造をまとめて押さえると、MultiXactも「行ヘッダに何が記録されるか」の一例として整理できます。体系的に学ぶための教材はこちらです。