Hasura configuration tool
@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 tohttp://localhost:8080
).HASURA_GRAPHQL_ADMIN_SECRET
for admin access (only required to usesquid-hasura-configuration apply
).- If your Hasura instance(s) use a role other than
public
to serve the anonymous part of your API, also setHASURA_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.
Here's how
-
Finalize any edits to
schema.graphql
-
Update the TypeScript code of your models with
npx squid-typeorm-codegen
-
Compile your models with
npm run build
-
Regenerate your DB migrations with a clean database to make sure they match your updated schema.
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
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 thepublic
(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.