Merge branch 'graphql-docs-rework' into develop

docs/sdk/how-to-start/squid-development.mdx

@@ -464,7 +464,7 @@ At `src/main.ts`, change the [`Database`](/sdk/resources/persisting-data/overvie
 <TabItem value="typeorm" label="PostgreSQL+GraphQL">
 ```
 
-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).

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:
 
-<!-- If you want to run Hasura in [Subsquid Cloud](/cloud), visit the [`hasura` addon page](/cloud/reference/hasura). -->
+    * 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
 

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.
+
+<details>
+<summary>Here's how</summary>
+
+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
+
+</details>
+
+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).