Overview

DipDup provides seamless integration with Hasura GraphQL Engine to expose your data to the client side. It's a powerful tool that allows you to build a GraphQL API on top of your database with minimal effort. It also provides a subscription mechanism to get live updates from the backend. If you don't plan to use GraphQL, you can skip this section.

Before starting to do client integration, it's good to know the specifics of Hasura GraphQL protocol implementation and the general state of the GQL ecosystem.

Queries

By default, Hasura generates three types of queries for each table in your schema:

• Generic query enabling filters by all columns
• Single item query (by primary key)
• Aggregation query (can be disabled in config)

All the GQL features such as fragments, variables, aliases, and directives are supported, as well as batching.
Read more in Hasura docs.

It's important to understand that a GraphQL query is just a POST request with JSON payload, and in some instances, you don't need a complicated library to talk to your backend.

Pagination

By default, Hasura does not restrict the number of rows returned per request, which could lead to abuses and a heavy load on your server. You can set up limits in the configuration file. See hasura page. But then, you will face the need to paginate over the items if the response does not fit the limits.

Subscriptions

From Hasura documentation:

Hasura GraphQL engine subscriptions are live queries, i.e., a subscription will return the latest result of the query and not necessarily all the individual events leading up to it.

This feature is essential to avoid complex state management (merging query results and subscription feed). In most scenarios, live queries are what you need to sync the latest changes from the backend.

If the live query has a significant response size that does not fit into the limits, you need one of the following:

• Paginate with offset (which is not convenient)
• Use cursor-based pagination (e.g., by an increasing unique id).
• Narrow down request scope with filtering (e.g., by timestamp or level).

Ultimately you can get "subscriptions" on top of live quires by requesting all the items having ID greater than the maximum existing or all the items with a timestamp greater than now.

Websocket transport

Hasura is compatible with graphql-ws library, which is a standard for GraphQL over WebSockets. It's a simple protocol that allows you to establish a persistent connection with the server and receive updates in real-time.

Please note, that subscriptions-transport-ws library is deprecated a long time ago and should not be used in new projects.

Mutations

The purpose of DipDup is to create indexers, which means you can consistently reproduce the state as long as data sources are accessible. It makes your backend "stateless", meaning tolerant to data loss.

However, you might need to introduce a non-recoverable state and mix indexed and user-generated content in some cases. DipDup allows marking these UGC tables "immune", protecting them from being wiped. In addition to that, you will need to set up Hasura Auth and adjust write permissions for the tables (by default, they are read-only).

Lastly, you will need to execute GQL mutations to modify the state from the client side. Read more about how to do that with Hasura.