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

# Hasura configuration tool

> Generate and apply Hasura metadata for a Squid SDK indexer schema.

<Info>
  For info on migrating to `@subsquid/hasura-configuration>=2.0.0` see [this page](../guides/migration/migrate-to-hasura-v2).
</Info>

[`@subsquid/hasura-configuration`](https://www.npmjs.com/package/@subsquid/hasura-configuration) is a tool for managing Hasura configuration in [PostgreSQL-powered squids](../guides/writing-to-postgres). 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](./schema-files/schema-files-codegen#typeorm-codegen) as input when generating the initial configuration. Make sure they are up to date.

<Steps>
  <Step title="Finalize the schema">
    Finalize any edits to [`schema.graphql`](./schema-files/schema-files-codegen).
  </Step>

  <Step title="Update the TypeORM models">
    Update the TypeScript code of your models with:

    ```bash theme={"system"}
    npx squid-typeorm-codegen
    ```
  </Step>

  <Step title="Compile the models">
    ```bash theme={"system"}
    npm run build
    ```
  </Step>

  <Step title="Regenerate the database migrations">
    Regenerate your [DB migrations](../guides/writing-to-postgres#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 the database after this step. The Hasura configuration tool does not use it to generate the initial configuration.
  </Step>
</Steps>

When done, run either command:

<Tabs>
  <Tab title="Main binary">
    ```bash theme={"system"}
    npx squid-hasura-configuration regenerate
    ```
  </Tab>

  <Tab title="Standalone binary">
    ```bash theme={"system"}
    npx squid-hasura-configuration-regenerate
    ```
  </Tab>
</Tabs>

Both binaries accept `--force`, which overwrites an existing `hasura_metadata.json` without prompting:

```bash theme={"system"}
npx squid-hasura-configuration regenerate --force
```

The generated configuration will be available at `hasura_metadata.json`. It enables:

* tracking all tables that correspond to [schema entities](./schema-files/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](./schema-files/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, apply the generated config with either command:

<Tabs>
  <Tab title="Main binary">
    ```bash theme={"system"}
    npx squid-hasura-configuration apply
    ```
  </Tab>

  <Tab title="Standalone binary">
    ```bash theme={"system"}
    npx squid-hasura-configuration-apply
    ```
  </Tab>
</Tabs>

You can also 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).