Skip to main content

Serving GraphQL

It is common (although not required) for squids to serve GraphQL APIs. Historically, the most common way to do that was to persist the squid data to PostgreSQL, then attach OpenReader to it. Although this is still supported, we encourage using PostGraphile or Hasura in new PostgreSQD-based projects. See OpenReader's limitations if you're curious about our motivation.

PostGraphile​

PostGraphile is an open-source tool that builds powerful, extensible and performant GraphQL APIs from PostgreSQL schemas. Its pros include:

  • aggregations;
  • reliable support for subscriptions;
  • capability for deep API customization;
  • organization of API customization code into plugins.

The recommended way of integrating PostGraphile into squid projects is by making a dedicated entry point at src/api.ts. A complete example squid implementing this approach is available in this repository.

With this entry point in place, we create a sqd command for running PostGraphile with commands.json, then use it in the deploy.api entry of Squid manifest. Although none of this is required, this makes it easier to run the squid both locally (with sqd run) and in the Cloud.

As per usual with PostGraphile installations, you can freely extend it with plugins, including your own. Here is an example plugin for serving the _squidStatus queries from the standard Squid SDK GraphQL server schema. A plugin for making PostGraphile API fully compatible with old APIs served by OpenReader will be made available soon.

Hasura​

Hasura is a powerful open-source GraphQL engine. You can use it to:

  • expose multiple data sources of different kinds (various databases, APIs etc) via a single API;
  • reliably serve subscriptions;
  • perform aggregations;
  • deeply customize your CRUD API.

You can integrate Hasura with your squid in two ways:

  1. Use Hasura to gather data from multiple sources, including your squid.

    For this scenario we recommend separating your Hasura instance from your squid, which should consist of just one service, the processor, plus the database. Supply your database credentials to Hasura, then configure it to produce the desired API.

    If you run your squid in our Cloud you can find database credentials in the app:

    database creds

  2. Run a dedicated Hasura instance for serving the data just from your squid.

    A complete example implementing this approach is available in this repository. Here's how it works:

    • Locally, Hasura runs in a Docker container. In the Cloud it is managed via the Hasura addon.
    • Hasura metadata is shared among all squid instances by means of the Hasura configuration tool. The tool can automatically create an initial configuration based on your TypeORM models, then persist any changes you might make with the web GUI and metadata exports.
    • Admin authentication secret is set via the HASURA_GRAPHQL_ADMIN_SECRET. The variable is set in .env locally and from a secret in Cloud deployments.

    See the configuration tool page and the repo readme for more details.

OpenReader​

OpenReader is a GraphQL server developed by the SQD team. Although still supported, it's not recommeded for new PostgreSQL-powered projects due to its limitations, especially for APIs implementing GraphQL subscriptions.

The server uses the schema file to produce its core API that can be extended with custom resolvers. Extra features include DoS protection and caching.