-- テスト用テーブル
CREATE TABLE users (
    id         SERIAL PRIMARY KEY,
    email      VARCHAR(255) NOT NULL,
    username   VARCHAR(50) NOT NULL,
    status     VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE TABLE orders (
    id          SERIAL PRIMARY KEY,
    user_id     INTEGER NOT NULL REFERENCES users(id),
    status      VARCHAR(20) NOT NULL DEFAULT 'pending',
    total       DECIMAL(10, 2) NOT NULL,
    created_at  TIMESTAMPTZ DEFAULT NOW()
);
 
-- B-Tree インデックス（デフォルト）
CREATE INDEX idx_users_email ON users (email);
 
-- ユニークインデックス（重複不可制約 + インデックスの2役）
CREATE UNIQUE INDEX idx_users_email_unique ON users (email);
 
-- 複合インデックス（列の順序が重要 — 後述）
CREATE INDEX idx_orders_user_date ON orders (user_id, created_at DESC);
 
-- 降順インデックス
CREATE INDEX idx_orders_recent ON orders (created_at DESC);
 
-- 式インデックス（関数の結果にインデックス）
CREATE INDEX idx_users_email_lower ON users (LOWER(email));
-- → WHERE LOWER(email) = 'test@example.com' で使用される
 
-- インデックスの確認
SELECT
    indexname,
    indexdef,
    pg_size_pretty(pg_relation_size(indexname::regclass)) AS size
FROM pg_indexes
WHERE tablename = 'orders';

-- インデックスなし（Sequential Scan）
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM orders WHERE user_id = 12345;
-- Seq Scan on orders  (cost=0.00..25000.00 rows=50 width=120)
--   actual time=45.2..180.5 rows=50 loops=1
--   Filter: (user_id = 12345)
--   Rows Removed by Filter: 999950
--   Buffers: shared hit=15000 read=10000
-- Planning Time: 0.1 ms
-- Execution Time: 180.6 ms
 
-- インデックス作成
CREATE INDEX idx_orders_user_id ON orders (user_id);
 
-- インデックスあり（Index Scan）
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM orders WHERE user_id = 12345;
-- Index Scan using idx_orders_user_id on orders
--   (cost=0.43..8.50 rows=50 width=120)
--   actual time=0.03..0.15 rows=50 loops=1
--   Index Cond: (user_id = 12345)
--   Buffers: shared hit=5
-- Planning Time: 0.2 ms
-- Execution Time: 0.2 ms
 
-- 結果比較:
-- Sequential Scan: 180.6 ms, 25000 buffers
-- Index Scan:      0.2 ms,   5 buffers
-- → 約900倍の高速化、I/Oが約5000分の1に削減

-- 悪い列順序
CREATE INDEX idx_orders_bad ON orders (created_at, user_id, status);
 
-- 良い列順序（等値条件を先に、範囲条件を後に）
CREATE INDEX idx_orders_good ON orders (user_id, status, created_at);
 
-- テストクエリ
EXPLAIN ANALYZE
SELECT * FROM orders
WHERE user_id = 42
  AND status = 'shipped'
  AND created_at > '2024-01-01';
 
-- idx_orders_bad の場合:
-- Index Scan using idx_orders_bad on orders
--   Index Cond: (created_at > '2024-01-01')
--   Filter: (user_id = 42 AND status = 'shipped')
--   Rows Removed by Filter: 4500  ← 多くの行をフィルタで除外
--   → created_at でしか絞れない
 
-- idx_orders_good の場合:
-- Index Scan using idx_orders_good on orders
--   Index Cond: (user_id = 42 AND status = 'shipped'
--                AND created_at > '2024-01-01')
--   Rows Removed by Filter: 0     ← 全条件がインデックスで処理
--   → 3列全てが Index Cond として使用される

-- ===== JSONB検索用GINインデックス =====
CREATE TABLE products (
    id          SERIAL PRIMARY KEY,
    name        VARCHAR(200) NOT NULL,
    price       DECIMAL(10, 2) NOT NULL,
    attributes  JSONB DEFAULT '{}'
);
 
-- GINインデックスの作成
-- jsonb_ops: @>, ?, ?&, ?| をサポート（デフォルト）
CREATE INDEX idx_products_attrs ON products USING GIN (attributes);
 
-- jsonb_path_ops: @> のみだがサイズが小さく高速
CREATE INDEX idx_products_attrs_path ON products
    USING GIN (attributes jsonb_path_ops);
 
-- JSONB の検索（GINインデックスが使用される）
SELECT * FROM products
WHERE attributes @> '{"color": "red", "size": "L"}';
 
-- キーの存在確認
SELECT * FROM products
WHERE attributes ? 'wireless';  -- 'wireless'キーが存在するか
 
-- 複数キーの存在確認
SELECT * FROM products
WHERE attributes ?& ARRAY['color', 'size'];  -- 両方のキーが存在
 
 
-- ===== 全文検索用GINインデックス =====
CREATE TABLE articles (
    id            SERIAL PRIMARY KEY,
    title         VARCHAR(500) NOT NULL,
    body          TEXT NOT NULL,
    search_vector tsvector  -- 全文検索用の事前計算カラム
);
 
-- tsvectorカラムの更新トリガー
CREATE OR REPLACE FUNCTION update_search_vector() RETURNS TRIGGER AS $$
BEGIN
    NEW.search_vector :=
        setweight(to_tsvector('english', COALESCE(NEW.title, '')), 'A') ||
        setweight(to_tsvector('english', COALESCE(NEW.body, '')), 'B');
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;
 
CREATE TRIGGER trg_articles_search
BEFORE INSERT OR UPDATE ON articles
FOR EACH ROW EXECUTE FUNCTION update_search_vector();
 
-- GINインデックスの作成
CREATE INDEX idx_articles_search ON articles USING GIN (search_vector);
 
-- 全文検索クエリ
SELECT title, ts_rank(search_vector, query) AS rank
FROM articles, to_tsquery('english', 'PostgreSQL & index') AS query
WHERE search_vector @@ query
ORDER BY rank DESC
LIMIT 10;
 
 
-- ===== 配列検索用GINインデックス =====
CREATE TABLE posts (
    id    SERIAL PRIMARY KEY,
    title VARCHAR(200) NOT NULL,
    tags  TEXT[] DEFAULT '{}'
);
 
CREATE INDEX idx_posts_tags ON posts USING GIN (tags);
 
-- 配列の包含検索
SELECT * FROM posts WHERE tags @> ARRAY['rust', 'wasm'];
-- → tagsに'rust'と'wasm'の両方を含む投稿
 
-- 配列の重複検索
SELECT * FROM posts WHERE tags && ARRAY['python', 'javascript'];
-- → tagsに'python'または'javascript'のいずれかを含む投稿

-- ===== PostGIS: 空間インデックス =====
-- PostGIS拡張のインストール
CREATE EXTENSION IF NOT EXISTS postgis;
 
CREATE TABLE stores (
    id        SERIAL PRIMARY KEY,
    name      VARCHAR(200) NOT NULL,
    location  GEOGRAPHY(POINT, 4326) NOT NULL  -- WGS84座標系
);
 
-- GiSTインデックスの作成
CREATE INDEX idx_stores_location ON stores USING GiST (location);
 
-- 半径5km以内の店舗検索
SELECT
    name,
    ST_Distance(
        location,
        ST_SetSRID(ST_MakePoint(139.7671, 35.6812), 4326)::geography
    ) AS distance_m
FROM stores
WHERE ST_DWithin(
    location,
    ST_SetSRID(ST_MakePoint(139.7671, 35.6812), 4326)::geography,
    5000  -- 5000m = 5km
)
ORDER BY distance_m;
 
-- k近傍検索（最も近い10店舗）
SELECT name, location <-> ST_SetSRID(ST_MakePoint(139.7671, 35.6812), 4326)::geography AS dist
FROM stores
ORDER BY location <-> ST_SetSRID(ST_MakePoint(139.7671, 35.6812), 4326)::geography
LIMIT 10;
 
 
-- ===== 範囲型の重複検索（予約管理） =====
CREATE TABLE reservations (
    id        SERIAL PRIMARY KEY,
    room_id   INTEGER NOT NULL,
    guest     VARCHAR(100) NOT NULL,
    check_in  DATE NOT NULL,
    check_out DATE NOT NULL
);
 
-- 範囲型のGiSTインデックス
CREATE INDEX idx_reservations_period ON reservations
    USING GiST (room_id, daterange(check_in, check_out));
 
-- 期間が重複する予約の検索
SELECT * FROM reservations
WHERE room_id = 101
  AND daterange(check_in, check_out) && daterange('2024-03-01', '2024-03-10');
-- → 3月1日〜10日と重複する予約をインデックスで効率的に検索
 
 
-- ===== 排他制約（同じ部屋の予約重複を禁止） =====
CREATE EXTENSION IF NOT EXISTS btree_gist;  -- 排他制約にB-Tree演算子を使うため必要
 
ALTER TABLE reservations ADD CONSTRAINT excl_room_period
    EXCLUDE USING GiST (
        room_id WITH =,
        daterange(check_in, check_out) WITH &&
    );
-- → 同じroom_idで期間が重複するINSERT/UPDATEを自動的に拒否

-- BRINインデックスは物理的に順序付けされたデータに最適
-- 例: ログテーブル（created_atが挿入順に増加）
CREATE TABLE access_logs (
    id         BIGSERIAL PRIMARY KEY,
    user_id    INTEGER,
    action     VARCHAR(50),
    ip_address INET,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
 
-- BRINインデックスの作成
-- pages_per_range: 何ページごとに要約情報を保持するか（デフォルト128）
CREATE INDEX idx_logs_created_brin ON access_logs
    USING BRIN (created_at)
    WITH (pages_per_range = 32);
 
-- サイズ比較（1億行のテーブルの場合の目安）:
-- B-Tree: 約2GB
-- BRIN:   約200KB（B-Treeの約1/10000）
 
-- BRINが効果的なクエリ
SELECT COUNT(*) FROM access_logs
WHERE created_at BETWEEN '2024-01-01' AND '2024-01-31';
-- → BRINが該当ページブロックだけをスキャン
 
-- BRINが効果的でないクエリ
SELECT * FROM access_logs WHERE user_id = 42;
-- → user_idは物理的な順序と相関がないため、BRINは効果なし
 
-- BRINの内部動作
-- 128ページごとに min_val, max_val を保持
-- WHERE created_at > '2024-06-01' の場合:
--   Block 0-127:   min=2024-01, max=2024-02 → スキップ
--   Block 128-255: min=2024-03, max=2024-04 → スキップ
--   Block 256-383: min=2024-05, max=2024-06 → スキャン（該当の可能性あり）
--   Block 384-511: min=2024-07, max=2024-08 → スキャン

-- 部分インデックス: WHERE句付きのインデックス
-- テーブルの一部の行だけにインデックスを作成する
 
-- アクティブユーザーのみインデックス（全体の10%）
CREATE INDEX idx_users_active_email ON users (email)
WHERE status = 'active';
-- → フルインデックスの約1/10のサイズ
-- → INSERT/UPDATE時のオーバーヘッドも約1/10
 
-- 未処理注文のみ（全体の5%）
CREATE INDEX idx_orders_pending ON orders (created_at)
WHERE status = 'pending';
-- 使用されるクエリ:
SELECT * FROM orders WHERE status = 'pending' ORDER BY created_at;
 
-- NULLでないカラムのみ（90%がNULLの場合）
CREATE INDEX idx_users_phone ON users (phone)
WHERE phone IS NOT NULL;
 
-- 条件付き一意制約（部分ユニークインデックス）
-- アクティブなユーザーの中でのみメールアドレスの一意性を保証
CREATE UNIQUE INDEX idx_users_active_email_unique ON users (email)
WHERE deleted_at IS NULL;
-- → 論理削除されたユーザーは同じメールアドレスを持てる
 
-- 部分インデックスの効果を確認
SELECT
    indexname,
    pg_size_pretty(pg_relation_size(indexname::regclass)) AS size
FROM pg_indexes
WHERE tablename = 'users';
-- idx_users_email:        120 MB  ← フルインデックス
-- idx_users_active_email:  12 MB  ← 部分インデックス（1/10）

-- カバリングインデックス: テーブルアクセスを完全に回避
-- INCLUDE句でインデックスに追加カラムを格納（検索キーとしては使わない）
 
CREATE INDEX idx_orders_covering ON orders (user_id, status)
INCLUDE (total, created_at);
 
-- このクエリは Index Only Scan で応答（テーブル読み取り不要）
EXPLAIN ANALYZE
SELECT user_id, status, total, created_at
FROM orders
WHERE user_id = 12345 AND status = 'shipped';
 
-- 出力:
-- Index Only Scan using idx_orders_covering on orders
--   (cost=0.43..5.50 rows=10 width=40)
--   actual time=0.02..0.05 rows=10 loops=1
--   Index Cond: (user_id = 12345 AND status = 'shipped')
--   Heap Fetches: 0  <-- テーブルアクセスなし！
 
-- INCLUDEとキー列の違い:
-- キー列: 検索条件として使用可能、ソートされる、B-Treeのノードに格納
-- INCLUDE列: 検索条件には使用不可、リーフノードにのみ格納
-- → INCLUDEの方がインデックスサイズが小さい（内部ノードに影響しない）
 
-- INCLUDEなしで同等の効果を得る方法（非推奨）
CREATE INDEX idx_orders_covering_old ON orders (user_id, status, total, created_at);
-- → 全列がキーになるためインデックスが大きくなり、更新コストも増加

-- 関数の結果にインデックスを作成
-- 大文字小文字を区別しないメール検索
CREATE INDEX idx_users_email_lower ON users (LOWER(email));
 
-- クエリでも同じ式を使う必要がある
SELECT * FROM users WHERE LOWER(email) = 'test@example.com';
-- → Index Scan using idx_users_email_lower
 
-- NG: 式が一致しないとインデックスが使われない
SELECT * FROM users WHERE email = 'test@example.com';
-- → Seq Scan（LOWER()がないため）
 
-- JSONBの特定キーにインデックス
CREATE INDEX idx_products_color ON products ((attributes->>'color'));
SELECT * FROM products WHERE attributes->>'color' = 'red';
 
-- 日付の年月部分にインデックス
CREATE INDEX idx_orders_yearmonth ON orders (DATE_TRUNC('month', created_at));
SELECT * FROM orders WHERE DATE_TRUNC('month', created_at) = '2024-06-01';
 
-- テキストの先頭N文字にインデックス（前方一致検索の高速化）
CREATE INDEX idx_users_name_prefix ON users (LEFT(username, 3));

-- ===== インデックスサイズの確認 =====
SELECT
    schemaname || '.' || tablename AS table_name,
    indexname,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
    idx_scan AS total_scans,           -- このインデックスが使われた回数
    idx_tup_read AS tuples_read,       -- インデックスから読まれたタプル数
    idx_tup_fetch AS tuples_fetched    -- テーブルから取得されたタプル数
FROM pg_stat_user_indexes
JOIN pg_indexes USING (indexname)
ORDER BY pg_relation_size(indexrelid) DESC
LIMIT 20;
 
 
-- ===== 未使用インデックスの検出 =====
SELECT
    indexrelname AS index_name,
    relname AS table_name,
    idx_scan AS scans,
    pg_size_pretty(pg_relation_size(indexrelid)) AS size,
    pg_size_pretty(pg_total_relation_size(relid)) AS table_size
FROM pg_stat_user_indexes
JOIN pg_statio_user_indexes USING (indexrelid)
WHERE idx_scan = 0
  AND indexrelid NOT IN (
      SELECT indexrelid FROM pg_constraint
      WHERE contype IN ('p', 'u')  -- PRIMARY KEY, UNIQUE制約は除外
  )
ORDER BY pg_relation_size(indexrelid) DESC;
 
-- 注意: 統計情報はpg_stat_reset()で初期化される
-- レプリカではインデックスが使われないため、プライマリで確認すること
 
 
-- ===== 重複インデックスの検出 =====
-- 同じ列の組み合わせで作られたインデックスを特定
SELECT
    a.indexrelid::regclass AS index1,
    b.indexrelid::regclass AS index2,
    a.indrelid::regclass AS table_name
FROM pg_index a
JOIN pg_index b ON a.indrelid = b.indrelid
    AND a.indexrelid < b.indexrelid
    AND a.indkey::text = b.indkey::text;
 
 
-- ===== REINDEX（オンライン再構築、PostgreSQL 12+）=====
-- 通常のREINDEX: テーブルへの書き込みをロック
REINDEX INDEX idx_orders_user_date;
 
-- CONCURRENTLY: ロックなしで再構築（推奨）
REINDEX INDEX CONCURRENTLY idx_orders_user_date;
 
-- テーブルの全インデックスを再構築
REINDEX TABLE CONCURRENTLY orders;
 
 
-- ===== インデックス膨張率の推定 =====
-- pgstattupleエクステンションを使用
CREATE EXTENSION IF NOT EXISTS pgstattuple;
 
SELECT
    indexrelid::regclass AS index_name,
    pg_size_pretty(pg_relation_size(indexrelid)) AS index_size,
    leaf_fragmentation
FROM pgstatindex('idx_orders_user_date');
-- leaf_fragmentation > 30% なら REINDEX を検討

-- ===== ケース1: 関数を適用している =====
-- NG: インデックスは email カラムに存在するが関数で包まれている
SELECT * FROM users WHERE UPPER(email) = 'TEST@EXAMPLE.COM';
-- → Seq Scan（式インデックスが必要）
 
-- OK: 式インデックスを作成するか、アプリ側で正規化
CREATE INDEX idx_users_email_upper ON users (UPPER(email));
 
 
-- ===== ケース2: 暗黙の型変換 =====
-- NG: user_idがINTEGERなのにTEXTで検索
SELECT * FROM orders WHERE user_id = '12345';
-- PostgreSQLでは暗黙変換で動作するが、他のDBでは問題になることがある
 
-- NG: VARCHARカラムにINTEGERで検索
SELECT * FROM products WHERE sku = 12345;
-- → 型が不一致でインデックスが使われない可能性
 
 
-- ===== ケース3: 選択率が低い（大部分の行が該当） =====
-- NG: status='active' が全体の90%を占める場合
SELECT * FROM users WHERE status = 'active';
-- → オプティマイザがSeq Scanを選択（インデックス経由より全走査が速い）
 
-- OK: 部分インデックスにして、少数派の条件で使用
CREATE INDEX idx_users_inactive ON users (email) WHERE status = 'inactive';
 
 
-- ===== ケース4: LIKE '%中間%'（中間一致・後方一致） =====
-- NG: 前方以外のLIKEはB-Treeで使えない
SELECT * FROM users WHERE username LIKE '%田中%';
-- → Seq Scan
 
-- OK: pg_trgm拡張でトライグラムインデックス
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX idx_users_name_trgm ON users USING GIN (username gin_trgm_ops);
SELECT * FROM users WHERE username LIKE '%田中%';
-- → GIN Scanで高速検索
 
-- OK: 全文検索（tsvector + GIN）
-- → 前述のコード例4参照
 
 
-- ===== ケース5: OR条件 =====
-- NG: ORでインデックスが効きにくい
SELECT * FROM orders WHERE user_id = 42 OR status = 'pending';
-- → Bitmap OR（各インデックスのビットマップを論理和）
-- → またはSeq Scan
 
-- OK: UNION ALLに書き換え
SELECT * FROM orders WHERE user_id = 42
UNION ALL
SELECT * FROM orders WHERE status = 'pending' AND user_id != 42;
 
 
-- ===== ケース6: NULL の扱い =====
-- B-TreeインデックスはIS NULLとIS NOT NULLに対応
SELECT * FROM users WHERE deleted_at IS NULL;
-- → Index Scanが使用可能（PostgreSQL 8.3+）
 
-- ただし、NULLが大多数の場合は部分インデックスが効果的
CREATE INDEX idx_users_deleted ON users (deleted_at)
WHERE deleted_at IS NOT NULL;

-- NG: 思考停止で全カラムにインデックス
CREATE INDEX idx_users_id ON users (id);           -- PKで既にある
CREATE INDEX idx_users_email ON users (email);      -- 必要
CREATE INDEX idx_users_username ON users (username); -- 検索しない場合は不要
CREATE INDEX idx_users_status ON users (status);     -- 値の種類が少ない
CREATE INDEX idx_users_created ON users (created_at); -- 検索しない場合は不要
CREATE INDEX idx_users_updated ON users (updated_at); -- 検索しない場合は不要
 
-- 問題点:
-- 1. 各INSERTで6個のインデックスを更新 → 書き込み性能30-50%低下
-- 2. ストレージ消費がテーブルの2-3倍に
-- 3. VACUUMの負荷増大
-- 4. 未使用インデックスが多くの場合50%以上
 
-- OK: 実際のクエリパターンに基づいてインデックスを作成
-- pg_stat_statementsで頻出クエリを分析
SELECT query, calls, mean_exec_time
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;
-- → 上位クエリのWHERE句/JOIN条件に必要なインデックスだけを作成

-- NG: 範囲条件の列が先、等値条件の列が後
CREATE INDEX idx_orders_bad ON orders (created_at, user_id);
 
-- このクエリでは user_id の条件がインデックスで処理されない
SELECT * FROM orders
WHERE user_id = 42 AND created_at > '2024-01-01';
-- → Index Cond: (created_at > '2024-01-01')
-- → Filter: (user_id = 42)  ← インデックス外のフィルタ
 
-- OK: 等値条件を先、範囲条件を後
CREATE INDEX idx_orders_good ON orders (user_id, created_at);
-- → Index Cond: (user_id = 42 AND created_at > '2024-01-01')  ← 全条件がインデックス内

-- NG: プロダクションで通常のCREATE INDEX
CREATE INDEX idx_orders_email ON orders (email);
-- → テーブルへの書き込みがロックされる（大テーブルでは数分〜数十分）
 
-- OK: CONCURRENTLYを使用
CREATE INDEX CONCURRENTLY idx_orders_email ON orders (email);
-- → ロックなしで構築（約2倍の時間がかかるが書き込み可能）
-- 注意: トランザクション内では使用不可
-- 注意: 構築に失敗した場合、INVALID状態のインデックスが残る
--       → DROP INDEX CONCURRENTLY で削除

CREATE TABLE events (
    id          BIGSERIAL PRIMARY KEY,
    user_id     INTEGER NOT NULL,
    event_type  VARCHAR(50) NOT NULL,
    payload     JSONB DEFAULT '{}',
    created_at  TIMESTAMPTZ DEFAULT NOW()
);
 
-- クエリ1: 特定ユーザーの最近のイベント
SELECT * FROM events
WHERE user_id = 42
ORDER BY created_at DESC
LIMIT 20;
 
-- クエリ2: 特定タイプのイベントをJSONBフィルタ付きで検索
SELECT * FROM events
WHERE event_type = 'purchase'
  AND payload @> '{"amount_gte": 10000}';
 
-- クエリ3: 日付範囲での集計
SELECT event_type, COUNT(*)
FROM events
WHERE created_at BETWEEN '2024-01-01' AND '2024-01-31'
GROUP BY event_type;

-- 遅いクエリ（100万行のテーブル）
EXPLAIN ANALYZE
SELECT o.id, o.total, u.email, u.username
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.status = 'shipped'
  AND o.created_at > '2024-06-01'
  AND u.status = 'active'
ORDER BY o.created_at DESC
LIMIT 50;
 
-- 現在の実行計画:
-- Limit  (cost=50000.00..50000.12 rows=50 width=100)
--   ->  Sort  (cost=50000.00..50100.00 rows=10000 width=100)
--         Sort Key: o.created_at DESC
--         ->  Hash Join  (cost=1000.00..49000.00 rows=10000 width=100)
--               ->  Seq Scan on orders o  (Filter: status='shipped' AND created_at > ...)
--               ->  Hash
--                     ->  Seq Scan on users u  (Filter: status='active')

# デバッグ用ユーティリティ
import logging
import traceback
from functools import wraps
 
# ロガーの設定
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s [%(levelname)s] %(name)s: %(message)s'
)
logger = logging.getLogger(__name__)
 
def debug_decorator(func):
    """関数の入出力をログ出力するデコレータ"""
    @wraps(func)
    def wrapper(*args, **kwargs):
        logger.debug(f"呼び出し: {func.__name__}(args={args}, kwargs={kwargs})")
        try:
            result = func(*args, **kwargs)
            logger.debug(f"戻り値: {func.__name__} -> {result}")
            return result
        except Exception as e:
            logger.error(f"例外発生: {func.__name__}: {e}")
            logger.error(traceback.format_exc())
            raise
    return wrapper
 
@debug_decorator
def process_data(items):
    """データ処理（デバッグ対象）"""
    if not items:
        raise ValueError("空のデータ")
    return [item * 2 for item in items]

# 設計判断の記録テンプレート
class ArchitectureDecisionRecord:
    """ADR (Architecture Decision Record) の作成"""
 
    def __init__(self, title: str):
        self.title = title
        self.context = ""
        self.decision = ""
        self.consequences = []
        self.alternatives = []
 
    def set_context(self, context: str):
        """背景と課題の記述"""
        self.context = context
        return self
 
    def set_decision(self, decision: str):
        """決定内容の記述"""
        self.decision = decision
        return self
 
    def add_consequence(self, consequence: str, positive: bool = True):
        """結果の追加"""
        self.consequences.append({
            'description': consequence,
            'type': 'positive' if positive else 'negative'
        })
        return self
 
    def add_alternative(self, name: str, reason_rejected: str):
        """却下した代替案の追加"""
        self.alternatives.append({
            'name': name,
            'reason_rejected': reason_rejected
        })
        return self
 
    def to_markdown(self) -> str:
        """Markdown形式で出力"""
        md = f"# ADR: {self.title}\n\n"
        md += f"## 背景\n{self.context}\n\n"
        md += f"## 決定\n{self.decision}\n\n"
        md += "## 結果\n"
        for c in self.consequences:
            icon = "✅" if c['type'] == 'positive' else "⚠️"
            md += f"- {icon} {c['description']}\n"
        md += "\n## 却下した代替案\n"
        for a in self.alternatives:
            md += f"- **{a['name']}**: {a['reason_rejected']}\n"
        return md

# チーム間のAPI契約定義
from dataclasses import dataclass
from typing import List, Optional
from enum import Enum
 
class Priority(Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"
 
@dataclass
class APIContract:
    """チーム間のAPI契約"""
    endpoint: str
    method: str
    owner_team: str
    consumers: List[str]
    sla_ms: int  # レスポンスタイムSLA
    priority: Priority
 
    def validate_sla(self, actual_ms: int) -> bool:
        """SLA準拠の確認"""
        return actual_ms <= self.sla_ms
 
    def to_openapi(self) -> dict:
        """OpenAPI形式で出力"""
        return {
            'path': self.endpoint,
            'method': self.method,
            'x-owner': self.owner_team,
            'x-consumers': self.consumers,
            'x-sla-ms': self.sla_ms
        }
 
# 使用例
contracts = [
    APIContract(
        endpoint="/api/v1/users",
        method="GET",
        owner_team="user-team",
        consumers=["order-team", "notification-team"],
        sla_ms=200,
        priority=Priority.HIGH
    ),
    APIContract(
        endpoint="/api/v1/orders",
        method="POST",
        owner_team="order-team",
        consumers=["payment-team", "inventory-team"],
        sla_ms=500,
        priority=Priority.CRITICAL
    )
]

-- 相関係数の確認
SELECT attname, correlation
FROM pg_stats
WHERE tablename = 'access_logs' AND attname = 'created_at';
-- correlation > 0.9 なら BRIN が有効

-- HOT Update率の確認
SELECT relname, n_tup_upd, n_tup_hot_upd,
       ROUND(100.0 * n_tup_hot_upd / NULLIF(n_tup_upd, 0), 1) AS hot_pct
FROM pg_stat_user_tables
WHERE n_tup_upd > 0
ORDER BY n_tup_upd DESC;
-- hot_pct が低い場合、fillfactor の調整を検討