Skip to main content

​
Hasura configuration tool

For info on migrating to @subsquid/hasura-configuration>=2.0.0 see this page.
@subsquid/hasura-configuration is a tool for managing Hasura configuration in PostgreSQL-powered squids. Install it with 
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 as input when generating the initial configuration. Make sure they are up to date. When done, run 
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;
  • 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.

​
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: 
npx squid-typeorm-migration apply
When done, you can apply the generated config with 
npx squid-hasura-configuration apply
or import it using the Settings > Metadata Actions > Import metadata function of the web GUI.

​
Persisting configuration changes

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. Any extra configuration you may make via the web GUI or Hasura metadata API can be persisted by exporting the metadata to hasura_metadata.json via the Export metadata function, then applying it to blank Hasura instances with 
npx squid-hasura-configuration apply

​
Example

See this repo.