Description

As of #2379, we drop and recreate all system metadata using a bulk query during schema migrations. This is satisfyingly decisive, but it can lead to a performance problem because it can cause the schema cache to be rebuilt many times in a single transaction, which created the problem described in #3354.

A simple fix would be to tweak the migrations to avoid rebuilding the schema cache so many times, but I’ve been wanting to avoid doing that. Currently, we go to a lot of effort to avoid rebuilding the schema cache in places, but this duplicates a lot of logic, and as that logic becomes increasingly complicated, it becomes extremely difficult to keep in sync. Ideally, we’d like to have a single source of truth for how to build the schema cache and what rules its contents must follow, but we need to do it without incurring such a huge performance cost.

The idea I’ve been thinking about for a while is to incrementalize the process of building the schema cache, in the incremental compilation sense. Essentially, the idea is to add dependency tracking to the build process, so if some part of the metadata doesn’t change, we can avoid rebuilding it. Tracking all those dependencies by hand would be tricky and probably about as error-prone as our existing solution, so this PR adds some scaffolding for automatic incrementalization that does a lot of the work automatically. More details below.

Affected components

• Server

Related Issues

#2379, #3354

Solution and Design

The good news about this change is that it actually removes a lot of logic, so the resulting implementation is simpler. However, the bad news is that it is a fairly invasive refactor, and it touches all parts of the code that modify the catalog or schema cache. There’s also a lot of new supporting code to help with the incremental build process, especially since arrows have almost no standard library to speak of.

For some more details, see the “For reviewers” section below.

TODO

• Implement incrementalization abstraction
• Refactor buildSchemaCache to remove imperative updates
• Update metadata APIs to use buildSchemaCache code path
  • tables
  • relationships
  • computed fields
  • permissions
  • event triggers
  • remote schemas
• Reintegrate proper SchemaDependency tracking
• Update Diff.hs logic
• Fix broken tests
• Insert calls to cache in the right places
• Use a non-leaky WriterT implementation
• Improve performance of catalog fetch query
• Figure out how to handle foreign key dependencies properly
• Improve performance of bulk queries Performance is good enough, so punting this to future work
• Handle conflicting GraphQL field names
• Track dependencies from permissions to tables in a more fine-grained way
• Track error codes in inconsistent metadata objects Decided not to do this.
• Final cleanup of loose ends

Server checklist

Catalog upgrade

Does this PR change Hasura Catalog version?

• Yes
  • Updated docs with SQL for downgrading the catalog

Metadata

Does this PR add a new Metadata feature?

• No

GraphQL

• No new GraphQL schema is generated

Breaking changes

• No Breaking changes

• There are breaking changes:

  1. Metadata API

     Existing query types:

     • Modify args payload which is not backward compatible
     • Behavioural change of the API
     • Change in response JSON schema
     • Change in error code

  2. Logging

     • Log JSON schema has changed
     • Log type names have changed

For reviewers

This is a big change, so here are some tips on where to start and what to focus on if you’d like to review it:

1. First, familiarize yourself very briefly with arrows.

   1. A good introduction to the high-level concepts is Understanding arrows from the Haskell wikibook, but it doesn’t cover proc notation.

   2. For a primer on proc notation, the Arrow syntax page on the Haskell website includes some basic information, and the relevant section of the GHC User’s Guide has more details.

   3. If you want something really thorough, you can read Paterson’s paper introducing arrow notation, A New Notation for Arrows.

   You don’t need to thoroughly understand arrows to understand most of the code in this pull request, and in fact if you squint proc notation looks quite a bit like plain do notation.

2. Having done that, take a quick look at Hasura.Incremental and read the documentation comments. You don’t need to worry about the implementation to understand the rest of the code. You can also look at Hasura.IncrementalSpec for a couple small examples.

3. Now you can start reading through the bulk of the changes. Start with Hasura.RQL.DDL.Schema.Cache, focusing on buildSchemaCacheRule, which defines how to build a SchemaCache from catalog metadata.

4. Look at Hasura.RQL.DDL.Schema.Cache.Dependencies, which implements dependency resolution to ensure integrity of the schema cache.

5. Read Hasura.RQL.Types.SchemaCache.Build, which defines the basic interface for triggering cache rebuilds.

6. The rest of the changes are mostly just adjustments to the rest of the code to accommodate the modified schema cache construction process.