> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenReader Overview

> An open source GraphQL server built by SQD

<Info>
  OpenReader is no longer recommended for use in new squid projects [relying on
  PostgreSQL](../../guides/writing-to-postgres). See [Serving
  GraphQL](../../guides/serving-graphql) to learn about the new
  options and the [Limitations](#limitations) section to understand our
  motivation.
</Info>

OpenReader is a server that presents data of PostgreSQL-powered squids as a GraphQL API. It relies on the [eponymous library](https://github.com/subsquid/squid-sdk/tree/master/graphql/openreader) lib of the Squid SDK for schema generation. [Schema file](../schema-files/schema-files-codegen) is used as an input; the resulting API supports [OpenCRUD](https://www.opencrud.org/) queries for the entities defined in the schema.

## Getting started

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

```bash theme={"system"}
npx squid-graphql-server
```

The `squid-graphql-server` executable supports multiple optional flags to enable [caching](./configuration/caching), [subscriptions](./configuration/subscriptions), [DoS protection](./configuration/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`](../data-stores/typeorm-store#db_schema) and
`DB_SCHEMA_INCLUDE_PUBLIC`, so the API can read the same non-default schema as
the processor.

In [SQD Cloud](/en/cloud/overview), OpenReader is usually ran as the `api:` service in the `deploy:` section of the [Deployment manifest](/en/cloud/reference/manifest).

## Supported queries

The details of the supported OpenReader queries can be found in a separate section [Core API](./api/intro). 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}ById` for each [entity](../schema-files/entities) defined in the schema file
* Entity queries named `{entityName}sConnection`. Each query supports rich filtering support, including [field-level filters](./api/queries), composite [`AND` and `OR` filters](./api/and-or-filters), [nested queries](./api/nested-field-queries), [cross-relation queries](./api/cross-relation-field-queries) and [Relay-compatible](https://relay.dev/graphql/connections.htm) cursor-based [pagination](./api/paginate-query-results).
* [Subscriptions](./configuration/subscriptions) via live queries
* list queries with the name `{entityName}s`

[Union types](../schema-files/unions-typed-json) are mapped to [GraphQL union types](https://graphql.org/learn/schema/#union-types) and [resolved](./api/resolve-union-types-interfaces) with `__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:

* `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
* `BigDecimal` entity field values are presented as strings
* `JSON` entity field values are presented as JSON

## Operational options

Run `npx 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 on the
[caching](./configuration/caching), [subscriptions](./configuration/subscriptions)
and [DoS protection](./configuration/dos-protection) pages.

## Limitations

* RAM usage of [subscriptions](./configuration/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.

## Next steps

<CardGroup cols={2}>
  <Card title="Core API" icon="code" href="./api/intro">
    Explore the automatically generated GraphQL API
  </Card>

  <Card title="Custom Resolvers" icon="function" href="./configuration/custom-resolvers">
    Extend the API with custom queries
  </Card>

  <Card title="Authorization" icon="shield" href="./configuration/authorization">
    Add basic access control to your API
  </Card>

  <Card title="DoS Protection" icon="shield-halved" href="./configuration/dos-protection">
    Protect your API from abuse
  </Card>
</CardGroup>