> ## 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](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview) on a per-region basis.

They are controlled using the [`ALTER DATABASE ... ALTER LOCALITY`](https://docs.cockroachlabs.com/docs/v24.2/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](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview) as much as possible. However, if you need additional customizations, using Zone Config Extensions is better than writing your own low-level [zone configs](https://docs.cockroachlabs.com/docs/v24.2/configure-replication-zones) 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](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview). This is true even if you [add new tables](https://docs.cockroachlabs.com/docs/v24.2/create-table) or [regions](https://docs.cockroachlabs.com/docs/v24.2/alter-database#add-region), or if a table's [locality is changed](https://docs.cockroachlabs.com/docs/v24.2/alter-table#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`](https://docs.cockroachlabs.com/docs/v24.2/alter-database#parameters) extensions don't set [lease preferences](https://docs.cockroachlabs.com/docs/v24.2/configure-replication-zones).
  * [`REGIONAL IN`](https://docs.cockroachlabs.com/docs/v24.2/alter-database#parameters) extensions don't set [lease preferences](https://docs.cockroachlabs.com/docs/v24.2/configure-replication-zones), nor do they set [replica constraints](https://docs.cockroachlabs.com/docs/v24.2/configure-replication-zones) or [voter constraints](https://docs.cockroachlabs.com/docs/v24.2/configure-replication-zones) that would conflict with the original [home region](https://docs.cockroachlabs.com/docs/v24.2/table-localities#regional-by-row-tables).
  * In no case will Zone Config Extensions change the [survival goals](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview#survival-goals) for the database.
* They are composable. You can use Zone Config Extensions to build up approximations of many higher-level features. For an example, see [Failover regions](https://docs.cockroachlabs.com/docs/v24.2/alter-database#failover-regions).
* They are region scoped. When a Zone Config Extension is attached to a [database region](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview#database-regions), any [`REGIONAL BY TABLE`](https://docs.cockroachlabs.com/docs/v24.2/table-localities#regional-tables) or [`REGIONAL BY ROW`](https://docs.cockroachlabs.com/docs/v24.2/table-localities#regional-by-row-tables) tables associated with that region will have their zone configurations updated according to the settings passed via the extension. As mentioned above, this updated config will also be persisted in the face of other multi-region configuration changes.
* They are locality scoped. You can specify a Zone Config Extension that only applies to tables with certain [localities](https://docs.cockroachlabs.com/docs/v24.2/multiregion-overview#table-localities). For example, to apply a Zone Config Extension to tables with the [`GLOBAL` locality](https://docs.cockroachlabs.com/docs/v24.2/table-localities#global-tables), use [`ALTER DATABASE ... ALTER LOCALITY GLOBAL ...`](https://docs.cockroachlabs.com/docs/v24.2/alter-database#alter-locality).

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

## See also

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