PostgreSQL接続（pgaudit）

pgAudit を通じた PostgreSQL データベースアクセスの観測に関する詳細なコネクターガイド — ログ形式の設定、ストリーミングインジェスト、帰属、生成されるアクセスマップエッジ

pgAudit コネクターは PostgreSQL の構造化監査ログをテイルし、監査されたデータアクセスごとに1つのアクセスマップエッジを出力します。読み取り/書き込みモードは pgAudit のクラス（READ、WRITE、DDL）からそのまま取得されます — SQL テキストから推論されることはありません。コネクターはログファイルに対する読み取り専用であり、データベースへの接続を開くことはありません。

一般的なソースモデルと設定構造についてはソースの接続から始めてください。このページでは PostgreSQL 側の前提条件、完全な設定サーフェス、帰属メカニクス、本番エステートの運用上の考慮事項をカバーします。

PostgreSQL の前提条件

コネクターは pgAudit の出力を読み取るため、PostgreSQL がそれを生成するよう設定されている必要があります。拡張機能をインストールし（Debian/Ubuntu の場合 apt install postgresql-<version>-pgaudit）、shared_preload_libraries 経由でロードし、再起動後、観測したい各データベースで CREATE EXTENSION pgaudit を実行してください。

有用な出力のための最小限の postgresql.conf 設定:

shared_preload_libraries = 'pgaudit'
pgaudit.log = 'read, write'       # READ と WRITE でデータアクセスをカバー
log_destination = 'jsonlog'        # ストリーミングには推奨。csvlog も動作
logging_collector = on
log_directory = '/var/log/postgresql'
log_filename = 'postgresql.json'

shared_preload_libraries の後は再起動が必要です。残りは reload（SELECT pg_reload_conf()）で適用されます。クエリを実行し、ログに pgAudit エントリが表示されることを確認して検証してください — エントリの message フィールドに pgAudit の構造化行（クラス、コマンド、オブジェクト名）が含まれています。標準の PostgreSQL メッセージのみが表示される場合、拡張機能がロードされていないか設定されていません。

設定

コネクターは OLIVARES_SOURCES_CONFIG JSON ファイルの kind: "pgaudit" で選択されます。完全な例:

{
  "sources": [
    {
      "name": "prod-postgres",
      "kind": "pgaudit",
      "tenant": "acme",
      "config": {
        "log_path": "/var/log/postgresql/postgresql.json",
        "format": "jsonlog",
        "follow": "true",
        "shared_accounts": "app_pool,reporting"
      }
    }
  ]
}

すべての config 値は文字列です。キーは pgAudit コネクターが所有しています:

log_path（必須） — PostgreSQL ログファイルへの絶対パス。コネクターはこのファイルを読み取ります。慣例によるログファイルの検出は行いません。
format — csvlog または jsonlog。デフォルトは csvlog。コネクターが使用するパーサーを制御します。PostgreSQL が実際に書き込んでいる log_destination と一致する必要があります。
follow — "true" の場合、ファイルを継続的にテイルします（ストリーミングモード）。これは jsonlog にのみ適用されます。csvlog ファイルは CSV レコードが改行をまたぐ可能性があるため、ストリーミングテイルが信頼できないバッチとして読み取られます。下記のバッチ vs ストリーミングを参照してください。
shared_accounts — 複数の呼び出し元間でプールまたは共有されている PostgreSQL ロールまたは application_name 値のカンマ区切りリスト。これらのいずれかに帰属するアクセスは意図的に approximate としてマークされます。下記の帰属と共有アカウントを参照してください。

これら4つ以上の config キーを創作しないでください。コネクターの config サーフェスは意図的に狭い — ログファイルを読み取るだけであり、PostgreSQL を管理しません。

帰属と共有アカウント

アクセスマップは「どのエージェントがこれを行ったか」に答える必要があります。pgAudit ログエントリは PostgreSQL ロール（ユーザー）と、設定されている場合はセッションの application_name を持ちます。コネクターは両方を使用してエッジのオリジンを構築します。

エージェントごとのIDが firm なエッジを獲得します。 各エージェントが接続に個別の application_name を設定する（または専用のロールを使用する）場合、コネクターは各アクセスを明確に帰属させ、エッジは firm になります。

共有ロールは approximate に縮退します。 複数のエージェントがコネクションプール、共通のサービスアカウント、または汎用の application_name を共有している場合、コネクターは呼び出し元を分離できません。そのIDを通じたすべてのアクセスは approximate としてマークされ、製品は区別できないエージェントを区別できるふりをするのではなく、そう公開します。shared_accounts が存在するのはこのためです: プールされたIDを事前に宣言することで、コネクターにそれらを即座に approximate としてマークするよう指示します。

ガバナンスへの影響は直接的です: approximate なエッジは firm な最小権限の発見事項を支持できません。データベースアクセスに対するエージェントごとのガバナンスが必要な場合は、エージェントごとのクレデンシャルまたは application_name 値を発行してください。完全な帰属モデルについては忠実度を参照してください。

カバレッジティア

pgAudit は clean カバレッジです。READ、WRITE、DDL クラスは権威的です — PostgreSQL の監査サブシステムがステートメントを分類し、コネクターはその分類をそのまま取得します。推論、SQL パース、ヒューリスティックはありません。

エッジの mode は R（読み取り）、RW（WRITE および DDL クラスの readwrite）、またはクラスが指示する通りです。コネクターは pgAudit が報告したものをアップグレードまたはダウングレードしません。clean が lossy や opaque なソースとどう比較されるかは忠実度 — カバレッジを参照してください。

バッチ vs ストリーミング

csvlog — バッチ。CSV レコードは改行をまたぐことがあります（埋め込み改行を持つクエリはマルチライン行を生成）。そのため、ストリーミングテイルではレコードを確実に分割できません。コネクターはファイルを完全なバッチとして読み取ります。ソースエントリに poll_seconds を設定して間隔での再実行を制御してください。
jsonlog + follow: "true" — ストリーミング。各 JSON エントリは単一行であるため、テイルは安全です。コネクターはファイルを開いたまま保持し、PostgreSQL が書き込むとエッジを出力します。

ほぼリアルタイムのエッジには jsonlog + follow が推奨設定です。定期的な監査や低ボリュームのデータベースには csvlog バッチで十分です。

エッジの形

コネクターがパースする各 pgAudit ログエントリは、以下のフィールドを持つ1つのアクセスマップエッジを生成します:

オリジン — PostgreSQL ロール。存在する場合は application_name で修飾。例: reporting_agent または app_pool/invoice-service。
リソース — 完全修飾オブジェクト: database.schema.table。例: prod.public.orders。
モード — R（pgAudit クラス READ から）または RW（pgAudit クラス WRITE または DDL から）。
帰属 — オリジンが単一のエージェントIDに解決される場合は firm、shared_accounts エントリに一致するか曖昧な場合は approximate。
ソース — このコネクターインスタンスを名前で識別。

エッジは SQL テキスト、行データ、クエリパラメータを含みません。IDが特定のモードでオブジェクトにアクセスしたという構造的な事実のみを記録します。

運用上の注意事項

ログローテーション。 PostgreSQL がログファイルをローテーション（log_rotation_age または log_rotation_size 経由）する場合、コネクターは現在のファイルを指している必要があります。ローテーションがアクティブファイルの名前を変更する場合、follow テイルは古いファイルディスクリプターが尽きるまで読み続けて停止します。安定したシンボリックリンクまたはコネクターが追跡できる命名規則に log_path を向けてください。コネクター自体はローテーションを管理しません。

高ボリュームのエステート。 pgAudit は、特に pgaudit.log = 'all' の場合、忙しいデータベースで大量のログボリュームを生成できます。必要なクラスに pgaudit.log をスコープし（通常は read, write）、カバレッジを失わずにノイズを減らすために pgaudit.log_relation によるデータベースごとまたはロールごとのフィルタリングを検討してください。

複数の PostgreSQL インスタンス。 各インスタンスには OLIVARES_SOURCES_CONFIG に個別の name と独自の log_path を持つ独自のソースエントリが必要です。マルチインスタンス検出はありません — 各ソースは正確に1つのログファイルを監視します。

パーミッション。 コレクタープロセスには PostgreSQL ログファイルへの読み取りアクセスが必要です。データベース接続、PostgreSQL ロール、データベースサーバーへのネットワークアクセスは不要です。ファイルシステムの読み取りパーミッションが唯一の要件です。

PostgreSQL の接続（pgaudit）