What is the metadata catalogue?
The Hasura metadata catalogue is a set of internal tables used to manage the state of the database and the GraphQL schema. Hasura GraphQL engine uses the data in the catalogue to generate the GraphQL API which then can be accessed from different clients.
The Hasura GraphQL engine stores this catalogue in a Postgres metadata database (which is by default the same database from which data is served over the GraphQL API if it is Postgres).
When initialized, the Hasura GraphQL engine creates a schema called
hdb_catalog in the metadata database and initializes a few tables under it as described below.
This schema is created by the Hasura GraphQL engine to manage its internal state. Whenever a table/permission/relationship is created/updated using the Hasura console or the metadata API, the Hasura GraphQL engine captures that information and stores it in the corresponding tables.
Exploring the catalogue
You can check the current schema and contents of the catalogue by exploring the
hdb_catalog schema in the metadata database through a Postgres client.
The metadata for Hasura Cloud projects is stored in dedicated databases managed by Hasura Cloud itself, hence the metadata catalogue will not be set up on the user's connected database(s). (Though note that if any event triggers are defined on a database, then their invocation logs will be stored in the "hdb_catalog" schema of that database).
Whenever the schema of the catalogue is modified (typically to support new features) a new version of the catalogue is generated.
The catalogue version is upgraded automatically on startup if a new version is available during Hasura GraphQL engine updates.