PostgREST: 本番環境におけるベンチマークと実際の制限

PostgREST での HTTP スループット テストは主に Postgres を測定しますが、PostgREST はほとんど測定しません。サーバーは、ベースの前にある薄い翻訳層です。実際の負荷の大部分では、応答時間は SQL クエリを生成したプロセスではなく、実行された SQL クエリによって支配されます。

PostgREST プロジェクトは、GitHub 上にこのトピックの専用リポジトリ PostgREST/postgrest-benchmark を維持しており、個別のマーケティング数値を公開するのではなく、リリースごとのスループットの変動を追跡します。ここでは実行したり再公開したりしません。その結果は、ハードウェア、回路図のサイズ、およびテストされたシナリオに依存します。正確には、図を引用する前に、当社独自の ベンチマーク プロトコル が文書化する必要がある変数です。

PostgREST の下では、実際に重要なレイヤーである同時負荷時の SQL トランザクション時間を測定する pgbench です。これは、公式の PostgreSQL ベンチマーク ツール (postgresql.org/docs/current/pgbench.html、2026 年 8 月 24 日にアクセス) です。この記事では、このプロトコルをここで再現するのではなく、本番環境における PostgREST の 4 つの具体的なアーキテクチャ上の制限について文書化します。それぞれは、Aurabase ソースコードまたは公式プロジェクトドキュメントで検証されています。

各 Aurabase Postgres エンジンプロジェクトは、クラスターと同じ場所に配置された 2 つの専用 PostgREST レプリカを受け取ります。これらをデプロイする Kubernetes マニフェストは、控えめなリソースを設定します。

これらのレプリカが実際に消費するのは CPU ではなく、Postgres プライマリへの接続です。各 PostgREST インスタンスは、テナントにデプロイされた PgBouncer プーラーを経由せずに、プライマリ (-rw) に直接接続します。この選択については、PostgREST の互換性に関する記事ですでに詳しく説明されています。: LISTEN/NOTIFY スキーマのリロード メカニズムには永続的な接続が必要であり、トランザクション モードのプーラーとは互換性がありません。この記事で追加される内容: 接続に関して、実際のコストはいくらか、そしてそのピークはどこでしょうか。

レプリカごとのこのプールのサイズ (PGRST_DB_POOL) は、プロジェクト レベルに応じて意図的に異なります。これは、各プロジェクトの PostgREST マニフェストを構築する関数 k8s_tenant.rsで検証されています。

# プライマリ上のレプリカごとの接続のフィンガープリント。
env:
  - { name: PGRST_DB_POOL, value: "PGRST_DB_POOL_VALUE" }  # 10 (専用) または 2 (共有)

専用レベルでは制約が緩和されます。プロジェクトには独自の CNPG クラスターがあり、したがって独自の max_connectionsがあり、隣接するクラスターはありません。共有レベルでは、同じ組織の複数のプロジェクトが 1 つのクラスターを共有します。このコンテキストによって、接続の予算が決定的に決まります。これについては、次のセクションで説明します。

共有 Postgres クラスターでは、同時にアクティブなプロジェクトの数を制限するのは HTTP スループットではありません。これは、使用可能な max_connectionsと比較した、PostgREST インスタンスがプライマリ上で開いた状態を保持する接続の数です。

Aurabase derives this budget directly from the actual cluster limits, checked in fleet.rs: (max_connections − réserve superuser/CNPG − connexions réservées au pooler) ÷ connexions par projet éveillé, floor at 1. The fixed reserve is 10 connections (superuser, CNPG instance manager, metrics exporter, provisioner admin margin). On the defects delivered (pool of 2 per replica, 2 replicas, or 4 connections per awakened project), the calculation gives three different budgets depending on the sizing level of the cluster.

ソース: fleet.rs::derive_wake_budget および wake_budget_for_org_plan、Aurabase コードから派生、2026 年 8 月 24 日に再読。

This budget is not a quota of owned projects: an team organization can hold 50 projects, most of which are dormant. This is a cap of concurrency: the number of projects that can hold open connections at the same time on the primary. A wake-up over budget does not fail, it is deferred until a sibling project goes back to sleep, checked in the same file. The topic of sizing max_connections itself is expanded upon in our article on tuning of max_connections, and the dedicated/mutualized tradeoff as a whole in dedicated vs. shared base.

正確な合計を要求すると、Postgres はクエリごとにフィルター処理された結果の表示行をカウントする必要が生じますが、そのコストはテーブルに応じて増加し、無料の操作ではありません。

PostgreSQL は、そのままではインデックス付きの行カウンターを維持しません。 MVCC では、行の可視性は、それを読み取るトランザクションによって異なります。したがって、正確な COUNT(*) は、事前計算された値を読み取るのではなく、候補行を訪問する必要があります。これは、Postgres エコシステムの構造上の制限として十分に文書化されており、ClickHouse のような分析ベンダーも含めて、自社の近似カウンターを Postgres のトランザクション動作と比較します。

# 大規模なテーブルではコストがかかります: フィルタリングされた結果の MVCC スキャンを強制します
curl "https://<gateway>/v1/db/<project_id>/orders?status=eq.paid" \
  -H "apikey: <clé>" -H "Prefer: count=exact"

# PostgREST によって文書化された、より安価な代替手段
  -H "Prefer: count=planned"   # プランナーによる見積り
  -H "Prefer: count=estimated" # しきい値を超えて計画されている、正確に下回っている

PostgREST は、これら 3 つのカウント戦略をネイティブに文書化しています (postgrest.org、2026 年 8 月 24 日にアクセス)。 exact 戦略では、スキャンの価格で合計を保証します。 planned は、クエリ プランナーからほぼ無料の見積もりを返します。 estimated は、しきい値に基づいて 2 つを自動的に切り替えます。この選択は表面的なものではありません。数百万行のテーブルで count=exact を必要とするページネーションでは、ユーザーが最後のページを参照しない場合でも、各ページでこのスキャンの費用が発生します。

正確な合計を明示的に要求しない限り、行キャップにより、本文またはヘッダーに何も示されずに PostgREST 応答が切り詰められることがあります。想定ではなく、専用の Aurabase インスタンス上で実際の条件で測定しました。

PGRST_DB_MAX_ROWS=5を含む 10 行のテスト テーブルでは、PostgREST v12.2.3 は、次の 2 つのまったく異なる状況でまったく同じ Content-Range ヘッダーをレンダリングします。

count=exactがないと、5 行の応答は、実際に 5 行しか含まれないテーブルと区別がつきません。 Content-Range: 0-4/* は、適用される制限ではなく、表示される行を記述します。この場合、実際の上限はどこにも表示されず、Aurabase SDK の PostgREST パスで直接測定されます。

PostgREST は、起動時に Postgres スキーマをメモリに保持します。 DDL (テーブルの作成、列の追加) の後、新しいルートが応答する前にこのキャッシュをリロードする必要があります。このリロードは非同期です。

このウィンドウに到着する書き込みは、テーブルが実際に Postgres 側に存在する場合でも、一時的な 404 (キャッシュがまだ最新ではない) を受け取る可能性があります。 Aurabase ゲートウェイは、 postgrest_proxy.rsで検証された制限付き再試行ループでこれを吸収します。最大 8 回の試行、増加するバックオフ (試行ごとに 250 ミリ秒と 100 ミリ秒)、最悪の場合は累積 3.5 秒です。このメカニズムは書き込みにのみ影響し、読み取りには影響しません。

セルフホスト型 PostgREST デプロイメントの場合、レッスンは一般化されます。アプリケーション内の各 DDL パスは、プロセスへの NOTIFY または SIGUSR1 シグナルを介してリロードをトリガーする必要があります。それ以外の場合、移行により、展開直後に断続的なエラーに見せかけた p99 レイテンシ スパイクが発生します。

ここに記載されている 4 つの制限には 1 つの共通点があります。分離された HTTP スループット テストでは何も見られませんが、4 つすべてが PostgREST デプロイメントが運用環境に拡張されるかどうかを決定します。

• 接続バジェット: テナントあたりのスループットに関係なく、共有クラスター上で同時にアクティブになるテナントの数を制限します。
• 正確な COUNT のコスト: 負荷ではなくテーブルとともに増加します。 planned/estimatedでバイパスされます。
• サイレント切り捨て: 正しく構成された行キャップでも、不十分にインストルメントされたページングが中断される可能性があります。
• スキーマのリロード: 各移行後のレイテンシ ウィンドウ。リロード信号が適切に配線されている場合は制限され、それ以外の場合は無制限です。

セルフホスト型 PostgREST、Hasura スタイルの GraphQL レイヤー、またはカスタム API のいずれを選択する場合でも、これら 4 つの軸は、個別の req/s 数値よりも優れた比較ポイントとなります。 PostgREST vs Hasura vs カスタム APIの比較を参照してください。データベースの前に立つプーラーの選択も同様に重要です。比較 PgBouncer vs Supervisor vs PgCat では、PostgREST がトランザクション モードでプーラーを通過できない理由を詳しく説明しています。

PostgREST は、HTTP 負荷だけで壊れることはほとんどありません。そのためには、そのアーキテクチャが単純すぎます。本番環境で何が中断されるかは、本番環境の周囲にあるものです。つまり、そのレプリカが開いたままにする接続の数、正確な総コストはいくらかです。これには、切り捨てが表示されたままになるかどうか、および移行後のウィンドウの持続時間も含まれます。

これら 4 つの制限は Aurabase に固有のものではありません。セルフホスト型または管理型のすべての PostgREST デプロイメントに適用されます。このコードが示しているのは、マルチテナント展開によって、実稼働環境でそれらが驚くべきものになるのではなく、どのように明示的にされるかということです。