> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Region Zone Config Extensions

Multi-Region *Zone Config Extensions* are a customization tool for advanced users to persistently modify the configuration generated by the standard [multi-region SQL abstractions](/docs/stable/multiregion-overview.md) for a region, a [super region](/docs/stable/multiregion-overview.md#super-regions), or a table locality.

They are controlled using the [`ALTER DATABASE ... ALTER LOCALITY`](/docs/stable/alter-database#alter-locality) 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 [default multi-region SQL abstractions](/docs/stable/multiregion-overview.md) as much as possible. However, if you need additional customizations, using Zone Config Extensions is better than writing your own low-level [zone configs](/docs/stable/configure-replication-zones.md) 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 [multi-region SQL configuration](/docs/stable/multiregion-overview.md). This is true even if you [add new tables](/docs/stable/create-table.md) or [regions](/docs/stable/alter-database.md#add-region), or if a table's [locality is changed](/docs/stable/alter-table.md#set-locality).
* 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:
  * [`REGIONAL`](/docs/stable/alter-database#parameters) extensions don't set [lease preferences](/docs/stable/configure-replication-zones.md).
  * [`REGIONAL IN`](/docs/stable/alter-database#parameters) extensions don't set [lease preferences](/docs/stable/configure-replication-zones.md), nor do they set [replica constraints](/docs/stable/configure-replication-zones.md) or [voter constraints](/docs/stable/configure-replication-zones.md) that would conflict with the original [home region](/docs/stable/table-localities.md#regional-by-row-tables).
  * `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 [survival goals](/docs/stable/multiregion-overview.md#survival-goals) for the database or its super regions.
  * Zone Config Extensions can set [`num_replicas`](/docs/stable/configure-replication-zones) as low as [`num_voters`](/docs/stable/configure-replication-zones), 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 [Failover regions](/docs/stable/alter-database.md#failover-regions).
* They can be region or super-region scoped. A region extension updates the zone configurations of [`REGIONAL BY TABLE`](/docs/stable/table-localities#regional-tables) tables and [`REGIONAL BY ROW`](/docs/stable/table-localities#regional-by-row-tables) 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 [`GLOBAL`](/docs/stable/table-localities#global-tables) tables.
* They are locality scoped. You can specify a Zone Config Extension that only applies to tables with certain [localities](/docs/stable/multiregion-overview.md#table-localities). For example, to apply a Zone Config Extension to tables with the [`GLOBAL` locality](/docs/stable/table-localities#global-tables), use [`ALTER DATABASE ... ALTER LOCALITY GLOBAL ...`](/docs/stable/alter-database#alter-locality).

> [!NOTE]
>
> Zone Config Extensions are a property of a [database region](/docs/stable/multiregion-overview.md#database-regions), *not* any particular [schema object](/docs/stable/schema-design-overview.md). This differs from raw [zone configurations](/docs/stable/configure-replication-zones.md), 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 [Use Zone Config Extensions](/docs/stable/alter-database.md#use-zone-config-extensions).

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

* [Use Zone Config Extensions](/docs/stable/alter-database.md#use-zone-config-extensions)
* [`ALTER DATABASE ... ALTER LOCALITY`](/docs/stable/alter-database#alter-locality)
* [Multi-Region Capabilities Overview](/docs/stable/multiregion-overview.md)
* [Data Domiciling](/docs/stable/data-domiciling.md)
* [`PLACEMENT RESTRICTED`](/docs/stable/alter-database#placement)
* [`SET LOCALITY`](/docs/stable/alter-table#set-locality)
* [`ADD REGION`](/docs/stable/alter-database#add-region)
* [`SET PRIMARY REGION`](/docs/stable/alter-database#set-primary-region)
* [Troubleshoot Replication Zones](/docs/v26.3/troubleshoot-replication-zones.md)