GraphQL API

Apollo Federation

The GraphQL API can be an Apollo Federation v2 subgraph, so an Apollo router or gateway can compose it with other services. It is opt-in: with PGRST_GRAPHQL_FEDERATION unset or false, Federation metadata is inert and the generated SDL is unchanged.

PGRST_GRAPHQL_FEDERATION=true
PGRST_GRAPHQL_TYPE_PREFIX=billing   # optional

With it on, the schema gains:

• _service { sdl }, the subgraph SDL a router composes from, and _entities(representations:), which resolves entities by key.
• The Federation v2 directives. A table’s primary key is its @key.
• The root type names a router expects — Query, Mutation and Subscription — instead of Hasura’s query_root family.

Shared entities

When another subgraph owns the same entity, mark the table as shared in PGRST_GRAPHQL_METADATA:

{
  "tables": {
    "public.users": {
      "federation": { "shared": true }
    }
  }
}

A shared table keeps its unprefixed object type, so two subgraphs can both contribute to it. Its non-key columns, computed fields, relationships and relationship aggregates are marked @shareable, so another subgraph may resolve the same fields; key columns are shareable through @key already.

Type prefix

PGRST_GRAPHQL_TYPE_PREFIX prefixes generated types and root fields, so several Postrust subgraphs over different databases do not collide when composed. A shared entity is the exception for its object type only: with the prefix billing, the table above is still users @key(...), while its root fields and helper types are billing_users, billing_users_bool_exp and billing_users_aggregate.

Keys as ID

When the other subgraphs, or the router’s clients, expect a key as ID, declare it with column_types as described under the shape of the schema above: "column_types": { "id": "ID" }. A key exposed as ID accepts GraphQL’s string or integer spelling in a representation and is normalised to the column’s integer, text or UUID type.

How _entities matches

Representations are checked against each key field’s GraphQL type before any query runs: a field exposed as Int requires a JSON integer, a field exposed as ID accepts either the string or the integer spelling, and a bigint or numeric key accepts a number or the exact decimal string its scalar serialises to. An invalid key is a GraphQL error, without a trip to the database.

Each type’s representations are then resolved in one query, and PostgreSQL decides what matches. A key that PostgreSQL considers equal but spells differently — an uppercase UUID, a citext value in another case, a timestamptz with a different offset — finds its row. A key that matches nothing is a null in its position rather than an error for the whole list. Select permissions apply to _entities exactly as to any other read.

Two subgraphs behind a router

PostgreSQL as an Apollo Federation subgraph walks through two databases, a Postrust subgraph over each and Apollo Router in front, with row-level security deciding what each caller sees through the router. It runs as examples/federation.

A working subgraph

scripts/apollo-federation runs Postrust as the Products subgraph from Apollo’s subgraph compatibility suite, over a PostgreSQL loaded with that suite’s data. The part that matters is the environment:

products:
  environment:
    DATABASE_URL: postgres://postgres:postgres@database:5432/federation
    PGRST_DB_SCHEMAS: public
    PGRST_DB_ANON_ROLE: postgres
    PGRST_GRAPHQL_FEDERATION: "true"
    PGRST_GRAPHQL_METADATA: /config/graphql-metadata.json
    PGRST_SERVER_PORT: 4001

and the metadata, which names the types the way the target schema does and exposes the keys as ID:

{
  "tables": {
    "public.products": {
      "name": "Product",
      "column_types": { "id": "ID" },
      "roots": { "select_by_pk": "product" }
    },
    "public.product_dimensions": {
      "name": "ProductDimension",
      "federation": { "shared": true }
    }
  }
}

Start it with docker compose -f scripts/apollo-federation/compose.yaml up --build --wait from the repository root, then resolve a product as an entity, the way a router would:

curl http://localhost:4001/v1/graphql \
  -H 'content-type: application/json' \
  --data '{"query":"query { _entities(representations: [{__typename: \"Product\", id: \"apollo-federation\"}]) { ... on Product { id sku } } }"}'

A router is given the subgraph at /v1/graphql and reads its SDL from _service. The fixture’s README also shows how to run Apollo’s suite against it locally; the same suite runs in CI, and a required-capability failure fails the build.

Not supported yet: keys other than the primary key (so no repeatable or nested keys), extended and external fields, @requires, @provides, @override, @tag, @inaccessible, @composeDirective, @interfaceObject and federated tracing. The fixture keeps them in its target schema on purpose, so they show in the suite’s report as optional failures. The suite’s @shareable check fails too, because it looks for @shareable on the type and Postrust puts it on each non-key field; the two compose the same way.