ポストgreSQL 内部構造探求：学習ノートとコード検証記録

ポストgreSQL の内部構造（Internals）を深く理解するための学習ノートです。著者の学習へのコミットメントを保証し、読んだ内容を内面化するために記述されました。広瀬弘之氏による素晴らしい参照資料に基づいています。

元の情報は InterDB の PostgreSQL 解説 を元としています。

1. データベースクラスタの論理的構造

クラスタの定義

• 意味: 「複数のノード」という意味ではなく、単一の PostgreSQL インスタンスによって管理されるデータベースのグループを指します。
• データベース: テーブル、インデックス、ビューなどのオブジェクトの集合体です。また、データベース自体も OID（Object ID） で識別される一種のオブジェクトです。

組み込みオブジェクトと OID の割り当てルール

PostgreSQL では、OID はオブジェクトに自動的に割り当てられます。

template1

template0

postgres

• OID 1〜16383: 初期化オブジェクト用または予約済みです。
• 共有カタログ: クラスタ全体で共有されるため、

  pg_database

  はクラスタに 1 つだけ存在します。

システムカタログ（内部構造）の役割

すべてのオブジェクトは独自の OID で識別され、システムテーブル（カタログ）に格納されています。代表的なテーブルと目的は以下の通りです。

• pg_class

  : テーブル、ビュー、インデックスなどの「関係（Relation）」を格納します。

• pg_database

  : クラスタ内のすべてのデータベース情報を格納します（共有）。

• pg_index

  : インデックスに関する情報を格納します（汎用的な情報ではなく、詳細データ用）。

事実:

pg_class

pg_index

拡張機能と OID

• 例:

  pgvector

  のような拡張機能をインストールすると、自動的に

  pg_extension

  に追加され、新しい OID が生成されます。
• 履歴:
  • PG <= 8.0: すべてのテーブルに OID が割り当てられた。
  • 8.1 ~ 12: オートOID は「オプション（Opt-in）」になり、

    WITH OIDS

    で有効化する必要があった。
  • PG >= 12: この機能は完全に削除された。

2. データベースクラスタの物理構造

データディレクトリとパス

PostgreSQL クラスタは、データディレクトリに全データを格納します。このパスは環境変数

$PGDATA

• デフォルト場所:

  /var/lib/pgsql/data

  または

  /var/lib/postgresql/<version>/main

• 初期化ツール:

  initdb

  がディレクトリを作成・設定する役割を担います。

ファイルシステムの構成:

$PGDATA/
├── base/           # データベースごとに 1 つ (base/{OID})
│   └── {OID}/      # テーブル & インデックスの物理ファイル
├── global/         # クラスタ全体のカタログ（例：pg_class のデータ）
├── pg_wal/         # WAL セグメントファイル（復元用）
├── pg_xact/        # トランザクションコミット状態 (clog)
├── pg_tblspc/      # テーブルスペースへのシンボリックリンク
├── PG_VERSION      # 現在のメジャーバージョン番号
└── postgresql.conf # メイン設定ファイル

OID と物理ファイル名の関係：Relfilenode

PostgreSQL では、論理 ID（OID）と物理ファイル名（

relfilenode

• パスの形式:

  base/{Database_OID}/{Table_RelFileNode}

• 同一性:

  CREATE TABLE

  直後は、テーブルの OID とファイル名（Relfilenode）は一致します。

確認手順例

1. テーブル作成後の状態：

   SELECT oid, relname, relfilenode, relkind 
   FROM pg_class WHERE relname IN ('orders', 'orders_pkey');
   -- 結果: orders (OID: 16386) のファイル名も base/.../16386 となる
   

2. VACUUM FULL

   による変化：

   • VACUUM

     は空きスペース整理を行い、物理ファイルを再配置します。
   • 結果: OID は変更されないが（永続 ID）、Relfilenode（ファイル名）は変化する。

16386

16386

16397

base/{DB}/16386

base/{DB}/16397

3. テーブルスペース（Tablespaces）の仕組み

ユーザーはデータ格納場所を別のディレクトリに設定できます。

• pg_default: 通常のオブジェクト用（デフォルト）。
• pg_global: クラスタ全体で共有されるオブジェクト用。
• 命名テーブルスペース: ユーザーが定義した別空間。

シンボリックリンクによる管理

PostgreSQL は、実パスを直接使わず、

pg_tblspc/

# 外部ディレクトリの作成
mkdir -p /Users/burak/pg-tblspc-extra

# テーブルスペースの定義
CREATE TABLESPACE extra_space LOCATION '/Users/burak/pg-tblspc-extra';

# 内部マッピング確認
ls -la $PGDATA/pg_tblspc/16401 -> /Users/burak/pg-tblspc-extra

• グローバルテーブルスペース:

  global/{relfilenode}

  に格納。
• デフォルトテーブルスペース:

  base/{DB_OID}/{relfilenode}

  に格納。
• 命名テーブルスペース:

  pg_tblspc/{SpcOid}/PG_xx_yyy/{DB_OID}/{relfilenode}

  のようなマッピングが内部で行われる。

注意: インデックスは通常、親テーブルと同じテーブルスペースを使う（

USING INDEX TABLESPACE

4. ヒープテーブルの構造とページ管理

PostgreSQL はデータを ページ化 して格納しています。

• ページサイズ: デフォルト 8KB（コンパイル時に変更可）。
• ページの構成:
  1. ヘッダー: チェックサム、フラグ、空き領域情報など。
  2. ラインポインタ: タプルの位置を示すインデックス（Offset）。
  3. タプル: 実際のデータ行（ページの最後から配置される）。

PageHeader とヘッダーの値

pageinspect

• lower

  : ラインポインタ開始位置のオフセット（例：28 オフセット）。

• upper

  : タプルデータ開始位置のオフセット（例：8072 オフセット）。
• 有効領域:

  upper - lower

  で計算される空きサイズ。

ctid: 物理的な行の住所

任意の行を物理的に特定するためのシステムカラム

ctid

ctid = (page_number, offset_in_page)

5. TOAST（大属性ストレージ技術）

PostgreSQL は、1 ページを超えるような大きな値（

text

bytea

• 閾値: データサイズが 2KB を超えると TOAST 化されます。
• 仕組み: メインテーブルには「TOAST テーブル内の OID ポインタ」のみを格納し、本体データは別の

  pg_toast

  テーブルに置きます。

TOAST テーブルの構成

pg_toast

pg_toast_16483

• chunk_id: データブロック ID。
• chunk_seq: チャンク内のシーケンス番号。
• chunk_data: 実際のデータバイト列（圧縮された場合がある）。

メインテーブルと TOAST テーブルの関連性

メインテーブルの行ヘッダーには、外部データを指すポインタが格納されます。

typedef struct varatt_external {
    int32      va_rawsize;        // 元のデータサイズ（含ヘッダー）
    uint32     va_extinfo;        // 保存されたサイズ（圧縮情報含む）
    Oid        va_valueid;        // TOAST テーブル内の値の ID
    Oid        va_toastrelid;     // TOAST テーブルの OID
} varatt_external;

確認クエリ例: TOAST 化された行（例:

id=2

SELECT 
  id, 
  length(data) AS logical_bytes,
  pg_column_toast_chunk_id(data) AS va_valueid -- TOAST テーブル内の OID
FROM toast_demo 
WHERE id = 2;
-- 結果: chunk_id=16492 (TOAST テーブル内の特定レコードを指す)

6. タプルの書き込みと読み取り

ページへの書き込みロジック

新しい行が追加される際、以下の処理が行われます。

1. ラインポインタ更新:

   pd_lower

   を更新し、空き領域を示す。
2. タプル配置: データを

   upper

   領域に書き込む（整列のためパディングがかかる）。
3. WAL レコード: 変更内容は WAL に記録される（

   pd_lsn

   で管理）。

追加の影響

新しい行を追加すると、既存のラインポインタやタプルの物理オフセットがシフトする可能性があります。これは

page_header

lower

upper

読み取り戦略

• 全ページスキャン (Seq Scan): インデックスがない場合、全てのページのタプルを順次確認します。
• インデックス利用 (Index Scan):

  WHERE data = '...'

  のような条件がある場合、B-tree インデックスを先に検索し、該当するページとオフセットだけを抽出して読み込みます。

-- インデックス利用例
SELECT * FROM sampletbl WHERE data = 'CCCCCCCCC';
-- 実行: 
-- 1. B-Tree で 'CCCCCCCCC' の位置を探す (Index Scan)
-- 2. インデックスのレコードからページ番号とオフセットを取得する
-- 3. 該当ページをロードし、その位置のタプルを読み取る

まとめ

このノートでは PostgreSQL 1.1-1.4 章（The Internals of PostgreSQL）の内容を検証しました。

1. 論理構造: OID で識別されるオブジェクトとシステムカタログ（

   pg_class

   ,

   pg_database

   など）の役割を理解した。
2. 物理構造:

   $PGDATA/base/{DB}/relfilenode

   形式のパス管理と、

   VACUUM FULL

   を通じた Relfilenode の再割り当てを確認した。
3. テーブルスペース: シンボリックリンクによるマッピング機構を実践で確認した。
4. ページ構造: ヘッダー、ラインポインタ、タプルの物理配置と

   ctid

   を確認した。
5. TOAST: 2KB 以上のデータを外部テーブルへ退避する仕組みと

   varatt_external

   構造体を理解した。

今後も内部構造の深い掘り下げ記事を予定しています。