Overview

info

OpenReader is no longer recommended for use in new squid projects relying on PostgreSQL. See Serving GraphQL to learn about the new options and the Known issues section to understand our motivation.

OpenReader is a server that presents data of PostgreSQL-powered squids as a GraphQL API. It relies on the eponymous library lib of the Squid SDK for schema generation. Schema file is used as an input; the resulting API supports OpenCRUD queries for the entities defined in the schema.

To start the API server based on schema.graphql install @subsquid/graphql-server and run the following in the squid project root:

npx squid-graphql-server

The squid-graphql-server executable supports multiple optional flags to enable caching, subscriptions, DoS protection etc. Its features are covered in the next sections.

The API server listens at port defined by the GQL_PORT environment variable (defaults to 4350). The database connection is configured with the env variables DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT.

In SQD Cloud, OpenReader is usually ran as the api: service in the deploy: section of the Deployment manifest.

Supported queries

The details of the supported OpenReader queries can be found in a separate section Core API. Here is a brief overview of the queries generated by OpenReader for each entity defined in the schema file:

• the squid last processed block is available with squidStatus { height } query
• a "get one by ID" query with the name {entityName}ById for each entity defined in the schema file
• a "get one" query for @unique fields, with the name {entityName}ByUniqueInput
• Entity queries named {entityName}sConnection. Each query supports rich filtering support, including field-level filters, composite AND and OR filters, nested queries, cross-relation queries and Relay-compatible cursor-based pagination.
• Subsriptions via live queries
• (Deprecated in favor of Relay connections) Lookup queries with the name {entityName}s.

Union and typed JSON types are mapped into GraphQL Union Types with a proper type resolution with __typename.

Built-in custom scalar types

The OpenReader GraphQL API defines the following custom scalar types:

• DateTime entity field values are presented in the ISO format
• Bytes entity field values are presented as hex-encoded strings prefixed with 0x
• BigInt entity field values are presented as strings

Known issues

• RAM usage of subscriptions scales poorly under high load, making the feature unsuitable for most production uses. There are currently no plans to fix this issue.
• Setting up custom resolvers for subscriptions is unreasonably hard.
• @subsquid/graphql-server depends on the deprecated Apollo Server v3.