Skip to main content
Multi-Region Zone Config Extensions are a customization tool for advanced users to persistently modify the configuration generated by the standard for a region, a , or a table locality. They are controlled using the statement. Use cases for Zone Config Extensions include:
  • Failover behavior
  • Regions with stale read access
  • Quorum placement
  • Data domiciling
We strongly recommend that most users use the as much as possible. However, if you need additional customizations, using Zone Config Extensions is better than writing your own low-level for the following reasons:
  • Zone Config Extensions are persistent and kept up-to-date. Unlike raw zone config modification, which must be fully overwritten on each multi-region configuration change in order to take effect, Zone Config Extensions stay in place alongside the high-level . This is true even if you or , or if a table’s .
  • They are validated against the configs already in place in a multi-region cluster. Unlike hand-written zone configs, they are designed to work properly with the configuration generated by the higher-level multi-region SQL statements. Specifically, this means:
    • extensions don’t set .
    • extensions don’t set , nor do they set or that would conflict with the original .
    • SUPER REGION extensions don’t set lease preferences. Region constraints in their replica constraints and voter constraints can reference only regions that belong to the super region.
    • Zone Config Extensions don’t change the for the database or its super regions.
    • Zone Config Extensions can set as low as , which removes non-voting replicas and can reduce infrastructure costs while preserving the applicable survival goal.
  • They are composable. You can use Zone Config Extensions to build up approximations of many higher-level features. For an example, see .
  • They can be region or super-region scoped. A region extension updates the zone configurations of tables and partitions associated with that region. A super-region extension updates those objects when their home region belongs to the super region. Super-region extensions don’t apply to tables.
  • They are locality scoped. You can specify a Zone Config Extension that only applies to tables with certain . For example, to apply a Zone Config Extension to tables with the , use .
Zone Config Extensions are a property of a , not any particular . This differs from raw , which may need to be assigned (and reassigned) to 10s or 100s of different schema objects on every configuration change.
For instructions showing how to use Zone Config Extensions, see . When scopes overlap, CockroachDB applies REGIONAL extensions first, SUPER REGION extensions second, and REGIONAL IN extensions last. More-specific settings therefore override the same fields from less-specific extensions.

​
See also