diff --git a/docs/sdk/how-to-start/squid-development.mdx b/docs/sdk/how-to-start/squid-development.mdx index 8e339edf..658651f5 100644 --- a/docs/sdk/how-to-start/squid-development.mdx +++ b/docs/sdk/how-to-start/squid-development.mdx @@ -464,7 +464,7 @@ At `src/main.ts`, change the [`Database`](/sdk/resources/persisting-data/overvie ``` -1. Define the schema of the database (and the [core schema of the GraphQL API](/sdk/reference/openreader-server/api) if it is used) at [`schema.graphql`](/sdk/reference/schema-file). +1. Define the schema of the database (and the [core schema of the OpenReader GraphQL API](/sdk/reference/openreader-server/api) if it is used) at [`schema.graphql`](/sdk/reference/schema-file). 2. Regenerate the TypeORM model classes with ```bash @@ -626,6 +626,10 @@ The alternative is to do the same steps in a different order: 5. [Retrieve any external data](#external-data) if necessary 6. [Add the persistence code for the transformed data](#batch-handler-persistence) +## GraphQL options + +[Store your data to PostgreSQL](/sdk/resources/persisting-data/typeorm), then consult [Serving GraphQL](/sdk/resources/serving-graphql) for options. + ## Scaling up If you're developing a large squid, make sure to use [batch processing](/sdk/resources/batch-processing) throughout your code. @@ -640,5 +644,8 @@ For complete examples of complex squids take a look at the [Giant Squid Explorer ## Next steps -* Deploy your squid [on own infrastructure](/sdk/resources/self-hosting) or to [Subsquid Cloud](/cloud) -* If your squid serves an [OpenReader](/sdk/reference/openreader-server/)-compatible API, consult [core API reference](/sdk/reference/openreader-server/api) while writing your frontend application. +* Learn about [batch processing](/sdk/resources/batch-processing). +* Learn how squid deal with [unfinalized blocks](/sdk/resources/unfinalized-blocks). +* [Use external APIs and IPFS](/sdk/resources/external-api) in your squid. +* See how squid should be set up for the [multichain setting](/sdk/resources/multichain). +* Deploy your squid [on own infrastructure](/sdk/resources/self-hosting) or to [Subsquid Cloud](/cloud). diff --git a/docs/sdk/resources/serving-graphql.md b/docs/sdk/resources/serving-graphql.md index b9b1855b..9608d20c 100644 --- a/docs/sdk/resources/serving-graphql.md +++ b/docs/sdk/resources/serving-graphql.md @@ -31,9 +31,13 @@ As per usual with PostGraphile installations, you can freely extend it with plug 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](https://github.com/subsquid-labs/squid-hasura-example). More TBA. + A complete example implementing this approach is available in [this repository](https://github.com/subsquid-labs/squid-hasura-example). Here's how it works: - + * Locally, Hasura runs in a [Docker container](https://github.com/subsquid-labs/squid-hasura-example/blob/70bb6d703dc90c1bb00b47f3fef7f388ab54e565/docker-compose.yml#L14C1-L28C20). In the Cloud it is managed via the [Hasura addon](/cloud/reference/hasura). + * Hasura metadata is shared among all squid instances by means of the [Hasura configuration tool](/sdk/resources/tools/hasura-configuration). The tool can automatically create an initial configuration based on your [TypeORM models](/sdk/reference/schema-file/intro/#typeorm-codegen), 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](/cloud/resources/env-variables/#secrets) in Cloud deployments. + + See the [configuration tool page](/sdk/resources/tools/hasura-configuration) and the [repo readme](https://github.com/subsquid-labs/squid-hasura-example#readme) for more details. ## OpenReader diff --git a/docs/sdk/resources/tools/hasura-configuration-web-ui-import-export.png b/docs/sdk/resources/tools/hasura-configuration-web-ui-import-export.png new file mode 100644 index 00000000..1a151b45 Binary files /dev/null and b/docs/sdk/resources/tools/hasura-configuration-web-ui-import-export.png differ diff --git a/docs/sdk/resources/tools/hasura-configuration.md b/docs/sdk/resources/tools/hasura-configuration.md new file mode 100644 index 00000000..476eefce --- /dev/null +++ b/docs/sdk/resources/tools/hasura-configuration.md @@ -0,0 +1,89 @@ +--- +sidebar_position: 110 +title: Hasura configuration tool +description: Configure Hasura for your squid +--- + +# Hasura configuration tool + +[`@subsquid/hasura-configuration`](https://www.npmjs.com/package/@subsquid/hasura-configuration) is a tool for managing Hasura configuration in [PostgreSQL-powered squids](/sdk/resources/persisting-data/typeorm). Install it with +```bash +npm i @subsquid/hasura-configuration +``` +Make sure that the following environment variables are set: + + * `HASURA_GRAPHQL_ENDPOINT` for Hasura URL (defaults to `http://localhost:8080`). + * `HASURA_GRAPHQL_ADMIN_SECRET` for admin access (only required to use `squid-hasura-configuration apply`). + * If your Hasura instance(s) use a role other than `public` to serve the anonymous part of your API, also set `HASURA_GRAPHQL_UNAUTHORIZED_ROLE`. + +## Generating the initial configuration + +The tool uses your squid's [TypeORM models](/sdk/reference/schema-file/intro/#typeorm-codegen) as input when generating the initial configuration. Make sure they are up to date. + +
+Here's how + +1. Finalize any edits to [`schema.graphql`](/sdk/reference/schema-file) + +2. Update the TypeScript code of your models with + ```bash + npx squid-typeorm-codegen + ``` + +3. Compile your models with + ```bash + npm run build + ``` + +4. Regenerate your [DB migrations](/sdk/resources/persisting-data/typeorm/#database-migrations) with a clean database to make sure they match your updated schema. + ```bash + docker compose down + docker compose up -d + rm -r db + npm squid-typeorm-migration generate + ``` + +You can turn off your database after doing that - Hasura configuration tool does not use it to make its initial configuration + +
+ +When done, run +```bash +npx squid-hasura-configuration regenerate +``` +The generated configuration will be available at `hasura_metadata.json`. It enables: +- tracking all tables that correspond to [schema entities](/sdk/reference/schema-file/entities); +- `SELECT` permissions for the `public` (or `$HASURA_GRAPHQL_UNAUTHORIZED_ROLE` if it is defined) role for all columns in these tables; +- tracking all [entity relationships](/sdk/reference/schema-file/entity-relations). + +## Applying the configuration + +Make sure your database is up, your Hasura instance is connected to it and the schema is up to date. If necessary, apply the migrations: +```bash +npx squid-typeorm-migration apply +``` + +When done, you can apply the generated config with +```bash +npx squid-hasura-configuration apply +``` +or import it using the _Settings > Metadata Actions > Import metadata_ function of the web GUI. + +## Persisting configuration changes + +:::warning +Regenerating `hasura_metadata.json` removes any modifications you might have made via metadata exporting. So, it is advisable that you finalize your schema before you begin any manual API fine-tuning. +::: + +When running a squid with a dedicated Hasura instance you will notice that squid resetting operations (`docker compose down; docker compose up -d` and `sqd deploy -r`) restore your Hasura API to its non-configured state. As you develop your API further you may want to persist your changes. `squid-hasura-configuration` helps with that by being compatible with the _Settings > Metadata Actions > Import/Export metadata_ functions of the web GUI. + +![Web UI import and export](hasura-configuration-web-ui-import-export.png) + +Any extra configuration you may make via the web GUI or [Hasura metadata API](https://hasura.io/docs/2.0/api-reference/metadata-api/index) can be persisted by exporting the metadata to `hasura_metadata.json` via the _Export metadata_ function, then applying it to blank Hasura instances with +```bash +npx squid-hasura-configuration apply +``` + +## Example + +See [this repo](https://github.com/subsquid-labs/squid-hasura-example).