> ## 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.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.sqd.dev/feedback

```json
{
  "path": "/en/sdk/squid-sdk/resources/tools/hasura-configuration",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Hasura configuration tool

> Configure Hasura for a Squid SDK indexer with the hasura-configuration tool — auto-generate metadata from your schema and apply it to a Hasura instance.

<Info>
  For info on migrating to `@subsquid/hasura-configuration>=2.0.0` see [this page](/en/sdk/squid-sdk/resources/migrate/migrate-to-hasura-configuration-tool-v2).
</Info>

[`@subsquid/hasura-configuration`](https://www.npmjs.com/package/@subsquid/hasura-configuration) is a tool for managing Hasura configuration in [PostgreSQL-powered squids](/en/sdk/squid-sdk/resources/persisting-data/typeorm). Install it with

```bash theme={"system"}
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](/en/sdk/squid-sdk/reference/schema-file/intro#typeorm-codegen) as input when generating the initial configuration. Make sure they are up to date.

<Accordion title="Here's how">
  1. Finalize any edits to [`schema.graphql`](/en/sdk/squid-sdk/reference/schema-file)

  2. Update the TypeScript code of your models with
     ```bash theme={"system"}
     npx squid-typeorm-codegen
     ```

  3. Compile your models with
     ```bash theme={"system"}
     npm run build
     ```

  4. Regenerate your [DB migrations](/en/sdk/squid-sdk/resources/persisting-data/typeorm#database-migrations) with a clean database to make sure they match your updated schema.
     ```bash theme={"system"}
     docker compose down
     docker compose up -d
     rm -r db
     npx 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
</Accordion>

When done, run

```bash theme={"system"}
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](/en/sdk/squid-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](/en/sdk/squid-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 theme={"system"}
npx squid-typeorm-migration apply
```

When done, you can apply the generated config with

```bash theme={"system"}
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.
</Warning>

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.

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 theme={"system"}
npx squid-hasura-configuration apply
```

## Example

See [this repo](https://github.com/subsquid-labs/squid-hasura-example).