コンテンツへスキップ
オーラベースのロゴ
オーラベース

グラフQL

Postgres 拡張機能 pg_graphql、プロジェクトごとにオプトインされ、デフォルトでは無効になっています。有効にすると、専用の /graphql ルートまたは汎用 RPC プロキシを介して、REST API と同じスキーマが公開され、個別の GraphQL 認証を必要とせずに RLS とロールを継承します。

解説5 分 読み取りレベル 中間2026/11/11 に改訂

このページは自動翻訳されました。英語版が正式です。

別のサービスではなく、同じスキーマをクエリする 2 番目の方法#

GraphQL は、テナント データベース内の Postgres pg_graphql 拡張機能によって直接利用され、SQL テーブル、ビュー、リレーションシップから GraphQL スキーマを生成します。これを有効にすると、REST API と同じ Postgres スキーマ上に 2 番目のクエリ サーフェスが追加され、別個の GraphQL サーバーや認証レイヤーを必要とせずに、まったく同じ RLS ポリシーとロールが継承されます。

情報

すべてのプロジェクトでデフォルトでは無効になっています。 Aurabase は、プロジェクトごとの明示的なオプトインで pg_graphql のみ をアクティブにします。完全なクエリ、フィルター、カーソルのページネーション、およびミューテーション構文については、公式の pg_graphql ドキュメントを参照してください。

/graphql および /rpc/graphql で公開される SQL リゾルバー#

プロジェクトで GraphQL を有効にすると、pg_graphql がインストールされ、単一のトランザクションで "<project_schema>".graphql(query, variables, operationName, extensions) が作成されます。プロジェクトのサブドメインでは、 POST /graphql、 POST /graphql/v1、 POST /v1/graphql、 POST /v1/graphql/v1、および POST /v1/db/{project_id}/graphql ( POST /v1/db/{project_id}/rpc/graphql) へのリクエストは pg_graphql にルーティングされ、REST { data, meta } ラッパーを使用せずに標準の { "data": ..., "errors": ... } GraphQL JSON ペイロードを直接返します。

活性化のサイクルtext
ACTIVATION  ────▶  POST .../graphql/enable または aura プロジェクトgraphql-enable
ENQUEUE     ────▶  ジョブ「graphql_enable」がキューに入れられました (冪等、すでに有効になっている場合は操作なし)
DDL         ────▶  CREATE EXTENSION pg_graphql + ラッパー関数 + GRANT、1 つの単一トランザクション
FLAG        ────▶  project.graphql_enabled = true、トランザクション全体のコミット後にのみ設定されます
QUERY       ────▶  POST /graphql または /v1/db/{project_id}/graphql (生の GraphQL JSON を返します)
ヒント

アクティブ化トランザクションはアトミックです。いずれかのステップ (拡張機能、ラッパー関数、または GRANT) が失敗すると、すべてがロールバックされ、 graphql_enabled は falseのままになります。

アクティベーションの設定内容#

  • 自動的に生成されたスキーマ。 pg_graphql は、Postgres スキーマをイントロスペクトし、各テーブルを Relay GraphQL タイプ (&lt;table&gt;Collection、 edges、 node) として公開します。SQL snake_case 列はデフォルトで camelCase に変換されます。手動で記述する SDL はありません。
  • SECURITY INVOKER — RLSを継承しました。 ラッパー関数は呼び出し元 (aura_anon / aura_authenticated / aura_service_role) の権限で実行され、REST リクエストとまったく同じ RLS ポリシーを適用します。
  • 変更できる 3 つの設定は、アトミックに適用されます。 introspection (デフォルトでオフ: { __schema { ... } } は Unknown field "__schema"で拒否されるため、GraphiQL と Apollo codegen はそれをオンにするまでスキーマを検出できません)、max_rows (コレクションごとに返される行数、1 ~ 10000、デフォルトは 1000)、および inflect_names (created_at → createdAt、デフォルトでオン)。 pg_graphql COMMENT ON SCHEMA … @graphql(...) レシピはプロジェクトからは機能しません (ロールがスキーマを所有しておらず、/raw は E'…' リテラルを拒否します): 代わりに aura projects graphql-config または PATCH …/graphql/config を使用してください。 設定を調整するを参照してください。
  • オプトインのアクティブ化、冪等。 POST .../graphql/enable (コンソール JWT) または aura projects graphql-enable --wait (CLI) はプロビジョニング ジョブをディスパッチし、 --waitを使用すると、GraphQL が実際に有効になると戻ります。自動的にオンになることはありません。
  • すべての Postgres 層で利用可能です。 プロジェクトが組織の Postgres クラスターまたは専用のエンタープライズ クラスターで実行されるかどうかに関係なく機能します。エンドツーエンドで検証済み (拡張機能、RLS ラッパー、実際のクエリ)。
  • Postgres プロジェクトのみ。 MongoDB プロジェクトがアクティブ化を拒否しました (GRAPHQL_UNSUPPORTED_ENGINE)。

アクティブ化してからクエリを実行する#

graphql-enable.shbash
# 冪等: すでに有効になっているプロジェクトに対して呼び出しを繰り返しても何も行われません。
# --wait は、GraphQL が実際に有効になると戻ります (アクティブ化はバックグラウンド ジョブです)。
aura projects graphql-enable <project_id> --wait
ヒント

アクティベーションは、更新されたプロジェクト (graphql_enabled: true) で応答します。列の語形変化 (created_at → createdAt) に注意してください。フィルター、 orderBy、カーソル ページネーション (first/after)、および変更 (insertInto<Table>Collection) については、公式 pg_graphql API リファレンス を参照してください。

設定を調整します: イントロスペクション、最大行数、名前の語形変化#

pg_graphql は、プロジェクトのスキーマのコメントから設定を読み取ります。スキーマ所有者のみがそれを書き込むことができるため、ユーザーが要求すると、プラットフォームが 1 つのトランザクションでそれを実行します。変更は冪等性 (すでに適用されているものを要求しても何も行われません) であり、制限があります (1 ~ 10000 以外のmax_rows は、何かがキューに入れられる前に拒否されます)。

graphql-config.shbash
# 有効な設定を表示する
aura projects graphql-config <project_id>

# イントロスペクションをオンにして (GraphiQL、graphql-codegen、Apollo)、適用されるまで待ちます
aura projects graphql-config <project_id> --introspection on --wait

# コレクションを 100 行に制限し、SQL 名をそのまま維持します
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait

state は、変更についての真実を伝えます。適用されている間は pending ( pending_configを使用)、適用できなかった場合は failed ( config の設定が引き続き有効です)、それ以外の場合は applied です。最初に GraphQL を有効にする必要があります (そうでない場合はGRAPHQL_NOT_ENABLED)。保留中の 2 番目の変更は GRAPHQL_CONFIG_PENDINGと応答します。数秒以内に再試行してください。

イントロスペクションによりスキーマが明らかになります

introspection をオンにすると、プロジェクトの公開キーを保持する人は誰でも、GraphQL が公開するすべてのテーブルと列をリストできます (RLS は引き続き行を保護します)。開発の場合はこれをオンにし、スキーマの形状が機密性の高い場合は実稼働の場合は再度オフにします。

注意点#

ネーミングの変化とスキーマのリロード

デフォルトでは、 pg_graphql は SQL snake_case 名を GraphQL camelCase に反映します (created_at は createdAtになり、テーブル blog_posts は blogPostsCollectionになります)。 DDL が変更されると、PostgREST は数秒以内にスキーマ キャッシュを再ロードするため、/graphql と /rpc/graphql の両方が更新されたフィールドを公開します。

さらに進むには#