Adjusting the GraphQL Schema

When db-sync adds new tables or columns to it's database schema, it is needed to update the GraphQL schema as well. This ensures that users will be able to query all available data. Since the whole construct of this GraphQL implementation is complex it involves a few steps which will be explained in detail here.

1. Add/Adjust Hasura Schema

The first component is Hasura, which is query the data directly from the database. Therefore it is needed to add the tables to packages/api-cardano-db-hasura/hasura/project/metadata/databases/default/tables. To add a new table create a yaml file with the prefix public_ to follow the naming convention. The yaml file needs to follow this schema:

table:
  name: NAME_OF_YOUR_TABLE
  schema: SCHEMA_WHERE_TO_FIND_YOUR_TABLE
configuration:
  column_config: {}
  custom_column_names: {} 
  custom_root_fields:
    select: NAME_WITHIN_HASURA -> typically camelCase
    select_aggregate: AGGREGATOR_NAME_WITHIN_HASURA -> typically camelCase with _aggregate suffix
object_releationships: // mulitple possible
  - name: NAME_OF_FOREIGN_OBJECT
    using:
      manual_configuration:
        column_mapping:
          FOREIGN_KEY: PRIMARY_KEY_OF_FOREIGN_OBJECT
        remote_table:
          name: NAME_OF_FOREIGN_TABLE
          schema: SCHEMA_OF_FOREIGN_TABLE
select_permissions:
  - role: cardano-graphl // in our case we are using this role to access data
    permission:
      columns:
        - COLUMN_NAMES_FROM_DB // name all columns here including foreignkeys, which needs to be accessed
      filter: {}
      limit: 2500
      allow_aggregation: true

• Add this file to tables.yaml

2. Add new table schema.graphql

This new table must be added to the file packages/api-cardano-db-hasura/schema.graphql. The following things must be added:

• Add Object to Query (example: Link)
• Create type description (example: Link)
• Create OrderBy (example: Link)
• Create boolExp (example: Link)
• Create Aggregate type (example: Link)

3. Add new table to executableSchema

To register this new schema it must be added to the executableSchema. This is defined in the file packages/api-cardano-db-hasura/src/executableSchema.ts To add it a new object must be added to the dictionary (Link)