Macro mz_sql::session::vars::definitions::feature_flags

macro_rules! feature_flags {
    (@inner
        // The feature flag name.
        name: $name:expr,
        // The feature flag description.
        desc: $desc:literal,
        // The feature flag default value.
        default: $value:expr,
    ) => { ... };
    ($({
        // The feature flag name.
        name: $name:expr,
        // The feature flag description.
        desc: $desc:literal,
        // The feature flag default value.
        default: $value:expr,
        // Should the feature be turned on during catalog rehydration when
        // parsing a catalog item.
        enable_for_item_parsing: $enable_for_item_parsing:expr,
    },)+) => { ... };
}

Macro to simplify creating feature flags, i.e. boolean flags that we use to toggle the availability of features.

The arguments to feature_flags! are:

• $name, which will be the name of the feature flag, in snake_case
• $feature_desc, a human-readable description of the feature
• $value, which if not provided, defaults to false

Note that not all VarDefinition<bool> are feature flags. Feature flags are for variables that:

• Belong to SystemVars, not SessionVars
• Default to false and must be explicitly enabled, or default to true and can be explicitly disabled.

WARNING / CONTRACT: Syntax-related feature flags must always enable behavior. In other words, setting a feature flag must make the system more permissive. For example, let’s suppose we’d like to gate deprecated upsert syntax behind a feature flag. In this case, do not add a feature flag like disable_deprecated_upsert_syntax, as disable_deprecated_upsert_syntax = on would prevent the system from parsing the deprecated upsert syntax. Instead, use a feature flag like enable_deprecated_upsert_syntax.

The hazard this protects against is related to reboots after feature flags have been disabled. Say someone creates a Kinesis source while enable_kinesis_sources = on. Materialize will commit this source to the system catalog. Then, suppose we discover a catastrophic bug in Kinesis sources and set enable_kinesis_sources to off. This prevents users from creating new Kinesis sources, but leaves the existing Kinesis sources in place. This is because disabling a feature flag doesn’t remove access to catalog objects created while the feature flag was live. On the next reboot, Materialize will proceed to load the Kinesis source from the catalog, reparsing and replanning the CREATE SOURCE definition and rechecking the enable_kinesis_sources feature flag along the way. Even though the feature flag has been switched to off, we need to temporarily re-enable it during parsing and planning to be able to boot successfully.

Ensuring that all syntax-related feature flags enable behavior means that setting all such feature flags to on during catalog boot has the desired effect.