console/doc/mz-backwards-compatibility.md
Since the Console queries system catalog tables in Materialize, there will be cases where the schema of a table will change. Since customer environments can upgrade at different times, we need to support both versions of Materialize until all environments are successfully upgraded. Here are a few ways to do this:
We have a hook called useEnvironmentGate that returns true if the environment greater than or equal to the version you input. We can use it on runtime to handle both versions then create a follow up issue to cleanup when all environments are upgraded. To figure out which version to use, you can use the Release Schedule notion document as the source of truth.
If you need to test on different versions, you can create a test environment on Staging by signing up with your Materialize email but with a different alias. For example, for [email protected], you can sign up with [email protected]. On this test environment, you can deploy a custom version to it by following this guide.
We use Kysely to code generate type definitions for our system catalog tables. At the time of writing, these types are generated in materialize.d.ts. Since we can't use runtime checks to get around type errors, we can get around this by manually editing materialize.d.ts then creating a follow up issue to do another codegen to synchronize. There are a few cases that might happen:
We can add these columns to the appropriate tables
We can keep these columns around for the previous version given they shouldn't break any current behavior
We can edit the type of a column to be a discriminated union then do runtime checks to handle the discriminated union.
Make sure to annotate the change with a TODO so that codegens from other PRs before cleanup don't dismiss it too easily.