Postgres: Subscriptions¶

Introduction¶

A GraphQL subscription is essentially a query where the client receives an update whenever the value of any field changes upstream.

Subscriptions are supported for all kinds of queries. All the concepts of queries hold true for subscriptions as well.

Implementation¶

The Hasura GraphQL engine subscriptions are actually live queries, i.e. a subscription will return the latest result of the query being made and not necessarily all the individual events leading up to the result. By default, updates are delivered to clients every 1 sec.

See more details on subscriptions execution and performance.

Convert a query to a subscription¶

You can turn any query into a subscription by simply replacing query with subscription as the operation type.

Use cases¶

• Subscribe to the latest value of a particular field
• Subscribe to changes to a table’s entries
• Subscribe to the latest value of some derived data

Communication protocol¶

Hasura GraphQL engine uses the GraphQL over WebSocket Protocol by the apollographql/subscriptions-transport-ws library and the GraphQL over WebSocket Protocol by the graphql-ws library for sending and receiving events. The support for graphql-ws is currently considered as BETA. The graphql-engine uses the Sec-WebSocket-Protocol header to determine the server Implementation that’ll be used. By default, the graphql-engine will use the apollographql/subscriptions-transport-ws implementation.

// Create a WebSocket link:
const wsLink = new WebSocketLink({
  uri: `<graphql-endpoint>`,
  options: {
    reconnect: true,
    connectionParams: {
      headers: {headers-object}
    }
  }
});

Cookies and WebSockets¶

The Hasura GraphQL engine will read cookies sent by the browser when initiating a WebSocket connection. The browser will send the cookie only if it is a secure cookie (secure flag in the cookie) and if the cookie has a HttpOnly flag.

Hasura will read this cookie and use it as headers when resolving authorization (i.e. when resolving the auth webhook).