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 Limitations section to understand our motivation.
schema.graphql install @subsquid/graphql-server and run the following in the squid project root:
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 the port defined by GQL_PORT, then
GRAPHQL_SERVER_PORT, and defaults to 4000. Squid templates commonly set
GQL_PORT=4350 in .env. The database connection accepts DB_URL or
DB_NAME, DB_USER, DB_PASS, DB_HOST, and DB_PORT, together with the
DB_SSL* variables. GQL_DB_CONNECTION_POOL_SIZE defaults to 5, and
DB_TYPE can select PostgreSQL or CockroachDB. It also honors
DB_SCHEMA and
DB_SCHEMA_INCLUDE_PUBLIC, so the API can read the same non-default schema as
the processor.
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 processor status is available with
squidStatus { height hash finalizedHeight finalizedHash }; disable it with--no-squid-status - a “get one by ID” query with the name
{entityName}ByIdfor each entity defined in the schema file - Entity queries named
{entityName}sConnection. Each query supports rich filtering support, including field-level filters, compositeANDandORfilters, nested queries, cross-relation queries and Relay-compatible cursor-based pagination. - Subscriptions via live queries
- list queries with the name
{entityName}s
__typename. Typed JSON objects remain object fields in the generated API.
Built-in custom scalar types
The OpenReader GraphQL API defines the following custom scalar types:DateTimeentity field values are presented in the ISO formatBytesentity field values are presented as hex-encoded strings prefixed with0xBigIntentity field values are presented as stringsBigDecimalentity field values are presented as stringsJSONentity field values are presented as JSON
Operational options
Runnpx squid-graphql-server --help for the complete current option list.
Important controls include --sql-statement-timeout,
--validation-max-errors, --isolation-level, --dialect thegraph, and the
request, response-size, cache, and subscription options documented below.
Limitations
- 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-serverdepends on the deprecated Apollo Server v3.