System tables: add flag to differentiate between stable and unstable system tables

[chaas]

Feature request

Split out system tables to into ones that are stable and can be used in views (aka stored in catalog) vs ones that are unstable and can be selected upon but not used in views (aka not stored in catalog, we can continue to make broken changes).

The split will most likely be:

• object tables (mz_object, mz_indexes, ... ) -> stable
• introspection tables (compute & timely logs) -> unstable

Also update documentation to differentiate between the two, and more clearly identify the differences in the tables. Current documentation is alphabetical order over all system tables with no categorization.

[chaas]

@benesch FYI - you mentioned in passing that system tables are currently in unsafe mode, but I wasn't able to reproduce that in testing. I was able to successfully run commands like CREATE VIEW ob_view AS SELECT id from mz_objects; and CREATE MATERIALIZED VIEW ob_mz_view AS SELECT id from mz_objects;

We do have a warning in the docs

WARNING! The system tables are not part of Materialize’s stable interface. Backwards-incompatible changes to these tables may be made at any time.

But there's no technical constraint at the moment, and I wanted to flag it in case folks were operating under the assumption that there was.

[benesch]

Ah, sorry, if I said that I misspoke! I just meant that they are called out as not stable in the docs, not that we actually do anything to enforce correct usage of them.

[teskje]

If we want to include introspection relations here, we need to introduce the unstable flag not only for tables, but also for sources, materialized views, and views (which is what introspection relations are). I think we can just introduce the flag for all catalog items, akin to what we had with the volatile flag. The rule would then be that it is forbidden to create any new catalog item that depends on an unstable catalog item.

Two things we still need to clarify:

• Should system tables (like mz_objects, mz_indexes, ...) be considered unstable or not? As @benesch mentioned, they are documented as unstable now. Do we want to change that and commit to keeping them stable from now on?
• Should we expose the unstable flag anywhere in the system tables?

[chaas]

From my conversations with @benesch, my understanding was:

• System tables like mz_objects, mz_indexes will now be stable, except for a few that we will specifically mark, like mz_view_keys and mz_view_foreign_keys. That was a big motivator to tackle this epic https://github.com/MaterializeInc/materialize/issues/7174.
• We should add whether a table is stable vs unstable in the catalog docs
• I'm not sure about exposing the flag in the tables themselves