Skip to content
Aurabase Logo
aurabase

GraphQL

Postgres extension pg_graphql, opt-in per project and disabled by default. Once enabled, it exposes the same schema as your REST API — inheriting RLS and roles with no separate GraphQL authentication — via dedicated `/graphql` routes or the generic RPC proxy.

Explanation5 min readLevel intermediateRevised on Nov 11, 2026

A second way to query the same schema, not a separate service#

GraphQL is powered directly by the Postgres pg_graphql extension inside your tenant database, generating a GraphQL schema from your SQL tables, views, and relationships. Enabling it adds a second query surface over the same Postgres schema as your REST API — inheriting the exact same RLS policies and roles, without a separate GraphQL server or auth layer.

Info

Disabled by default for all projects. Aurabase activates pg_graphql only on explicit opt-in per project. See the official pg_graphql docs for full query, filter, cursor pagination, and mutation syntax.

An SQL resolver exposed on /graphql and /rpc/graphql#

Enabling GraphQL on a project installs pg_graphql and creates "<project_schema>".graphql(query, variables, operationName, extensions) in a single transaction. On a project subdomain, requests to POST /graphql, POST /graphql/v1, POST /v1/graphql, POST /v1/graphql/v1, and POST /v1/db/{project_id}/graphql (as well as POST /v1/db/{project_id}/rpc/graphql) are routed to pg_graphql and return the standard { "data": ..., "errors": ... } GraphQL JSON payload directly without the REST { data, meta } wrapper.

cycle of an activationtext
ACTIVATION  ────▶  POST .../graphql/enable or aura projects graphql-enable
ENQUEUE     ────▶  job "graphql_enable" queued (idempotent, no-op if already enabled)
DDL         ────▶  CREATE EXTENSION pg_graphql + wrapper function + GRANTs, 1 single transaction
FLAG        ────▶  projects.graphql_enabled = true, set only after full transaction commit
QUERY       ────▶  POST /graphql or /v1/db/{project_id}/graphql (returns raw GraphQL JSON)
Tip

The activation transaction is atomic: if any step (extension, wrapper function, or GRANTs) fails, everything rolls back and graphql_enabled stays false.

What activation sets up#

  • Automatically generated schema. pg_graphql introspects your Postgres schema and exposes each table as a Relay GraphQL type (&lt;table&gt;Collection, edges, node) with SQL snake_case columns inflected to camelCase by default — no SDL to write by hand.
  • SECURITY INVOKER — Inherited RLS. The wrapper function runs with the privileges of the caller (aura_anon / aura_authenticated / aura_service_role), enforcing the exact same RLS policies as REST requests.
  • Three settings you can change, applied atomically. introspection (off by default: { __schema { ... } } is refused with Unknown field "__schema", so GraphiQL and Apollo codegen cannot discover the schema until you turn it on), max_rows (rows returned per collection, 1 to 10000, default 1000) and inflect_names (created_at → createdAt, on by default). The pg_graphql COMMENT ON SCHEMA … @graphql(...) recipe does not work from a project (your role does not own the schema, and /raw refuses E'…' literals): use aura projects graphql-config or PATCH …/graphql/config instead, see Tune the settings.
  • Opt-in activation, idempotent. POST .../graphql/enable (console JWT) or aura projects graphql-enable --wait (CLI) dispatches the provisioning job and, with --wait, returns once GraphQL is actually enabled; never turned on automatically.
  • Available on all Postgres tiers. Works whether your project runs on an organization Postgres cluster or a dedicated Enterprise cluster; validated end-to-end (extension, RLS wrapper, real query).
  • Postgres projects only. A MongoDB project refuses activation (GRAPHQL_UNSUPPORTED_ENGINE).

Activate, then query#

graphql-enable.shbash
# Idempotent: a repeated call on an already enabled project is a no-op.
# --wait returns once GraphQL is actually enabled (the activation is a background job).
aura projects graphql-enable <project_id> --wait
Tip

Activation responds with the updated project (graphql_enabled: true). Notice column inflection (created_at → createdAt): see the official pg_graphql API reference for filters, orderBy, cursor pagination (first/after), and mutations (insertInto<Table>Collection).

Tune the settings: introspection, max rows, name inflection#

pg_graphql reads its settings from a comment on your project's schema. Only the schema owner can write it, so the platform does it for you, in one transaction, when you ask. A change is idempotent (asking for what is already applied does nothing) and bounded (max_rows outside 1–10000 is refused before anything is queued).

graphql-config.shbash
# Show the settings in effect
aura projects graphql-config <project_id>

# Turn introspection on (GraphiQL, graphql-codegen, Apollo), wait until it is applied
aura projects graphql-config <project_id> --introspection on --wait

# Cap collections at 100 rows and keep SQL names as they are
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait

state tells the truth about the change: pending while it is being applied (with pending_config), failed if it could not be (the settings in config are then still the ones in effect), applied otherwise. GraphQL must be enabled first (GRAPHQL_NOT_ENABLED otherwise), and a second change while one is pending answers GRAPHQL_CONFIG_PENDING: retry in a few seconds.

Introspection exposes your schema

With introspection on, anyone who holds the project's public key can list every table and column that GraphQL exposes (RLS still protects the rows). Turn it on for development, and off again for production if the shape of your schema is sensitive.

Points of attention#

Naming inflection and schema reloads

By default, pg_graphql inflects SQL snake_case names to GraphQL camelCase (created_at becomes createdAt, table blog_posts becomes blogPostsCollection). After DDL changes, PostgREST reloads its schema cache within seconds so both /graphql and /rpc/graphql expose updated fields.

To go further#