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

# Multi-Region Zone Config Extensions

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

Multi-Region *Zone Config Extensions* are a customization tool for advanced users to persistently modify the configuration generated by the standard <InternalLink path="multiregion-overview">multi-region SQL abstractions</InternalLink> for a region, a <InternalLink path="multiregion-overview#super-regions">super region</InternalLink>, or a table locality.

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

<Note>
  Zone Config Extensions are a property of a <InternalLink path="multiregion-overview#database-regions">database region</InternalLink>, *not* any particular <InternalLink path="schema-design-overview">schema object</InternalLink>. This differs from raw <InternalLink path="configure-replication-zones">zone configurations</InternalLink>, which may need to be assigned (and reassigned) to 10s or 100s of different schema objects on every configuration change.
</Note>

For instructions showing how to use Zone Config Extensions, see <InternalLink path="alter-database#use-zone-config-extensions">Use Zone Config Extensions</InternalLink>.

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

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