Postgres: Streaming Subscriptions

Introduction

A streaming subscription streams the response according to the cursor provided by the user while making the subscription. Streaming subscriptions can be used to subscribe only to the data which has been newly added to the result set.

This is different from a live query subscription where only the latest value is returned to the client.

Supported from

Streaming subscriptions are supported in Hasura GraphQL Engine versions v2.7.0-beta.1 and above.

How it works?

In streaming subscriptions, the server maintains a cursor value with a subscription and after streaming each batch, the value of the cursor is updated. Ideally, the cursor chosen should represent unique and sortable values so that each row is sent exactly once to a subscriber. Hasura does not require sticky sessions for streaming subscriptions.

Streaming subscriptions work well with other Hasura features like permissions and relationships and also leverage the power of subscriptions multiplexing.

Configuration details

In the case of streaming subscriptions, the multiplexed batch size can be configured via HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_BATCH_SIZE and the refetch interval can be configured via HASURA_GRAPHQL_STREAMING_QUERIES_MULTIPLEXED_REFETCH_INTERVAL.

Use cases

• Subscribe to the undelivered messages in a chat application

Bugs and limitations

Care needs to be taken when a streaming subscription query uses a cursor on a non-UNIQUE column. On Postgres and Citus, data will be returned correctly, however some responses may be larger than the requested batch size (this is because we use FETCH FIRST n WITH TIES internally).

Warning

On other Postgres-like databases where streaming subscriptions are supported but WITH TIES is not, like Cockroach, a cursor on a non-unique column may lead to some rows being skipped when the column data contains duplicates.