Preview —Geo-partitioning

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Note: This feature is available with the Spanner Enterprise Plus edition. For more information, see theSpanner editions overview.

This page introduces geo-partitioning and explains how it works inSpanner.

Spanner offersregional and multi-regional instanceconfigurations, which let you replicate your dataacross geographic locations. Geo-partitioning lets you further segment andstore rows in your database table across different instance configurations.

Benefits and use cases

Geo-partitioning lets you partition rows in your database, providing thefollowing benefits:

• Regional latency in a global database: By using geo-partitioning,Spanner manages your data in a single, unified database acrossgeographically distributed locations, while ensuring low latency for regionalaccess. Using geo-partitioning simplifies operations and reduces complexitycompared to managing multiple sharded databases.
• Global database capabilities: Geo-partitioning offers database featuressuch as global transactions, data movement between regions, and uniquenessenforcement across geographical regions.
• Data residency compliance: Spanner provides dataresidency commitments at the placement level. For information, seedata residency compatibility for databases that use geo-partitioning.

The following are common use cases:

• User-related data: Geo-partitioning user-related data to processand store data in a region that is closest to the user.

• Localized data: Location-specific information like traffic and specialevents.

How geo-partitioning works

All Spanner instances have a main instance partition that iscalled thedefault instance partition. If you don't create additional instancepartitions, all database objects are stored in the default partition, which isin the same location as your instance configuration. If you want to partitionthe data in a database, you must create additional instance partitions in yourinstance.

To use geo-partitioning in a database:

1. Create additional instance partitions in your instance.These user-created instance partitions have their own configuration (eitherregional or multi-region) and node count.

2. Create your database like you would normally. Thedatabase has a default placement that is associated with the defaultinstance partition of the instance.

3. Create placements in your database that are associatedwith the additional instance partitions. Your database can interact with theadditional instance partitions that were created in the same instance.

4. Create placement tables that have a placement key attribute.You must use the placement key in your DML statements to specify whichinstance partition the row data resides in. If you create non-placementtables in your database, Spanner stores that data in thedefault instance partition.

The placement key for each row in a placement table must be assigned to one ofthe following:

• A value which matches the name of one of the user-created placements definedfor that database; or

• The placement key value,default, which stores the data in the defaultplacement.

For instructions on how to use instance partitions, seecreate and manage instance partitions.

Important considerations

Consider the following before creating your instance partitions, placements, andplacement tables:

• Instance partition location: Carefully select the instance partitionregions that provide the most benefits for your application.

  Although you can create instance partitions in an instance with a regionalinstance configuration, we recommend that you create instance partitions in aninstance with a multi-region instance configuration so that the defaultinstance partition location is also in a multi-region configuration.

  Moreover, select a multi-region default instance partition location that hasread-write and read-only regions that cover all jurisdictions requiredby your application. Then, create additional instance partitions (which can beregional) with leader regions that match the regions in the multi-regiondefault instance partition.

• Number of instance partitions: Too many instance partitions can lead tooverhead, while too few might not offer enough benefits. You can create amaximum of ten instance partitions per instance.

Limitations

The following limitations apply during thePreviewrelease and are subject to change or removal upon the GA release or after:

• You can't create an instance partition using adual-region configuration.
• For each instance partition, the compute capacity must be at least one node(1000 processing units).
• For a given instance, you can't create more than one instance partition thatuses the same base instance configuration. For example, withintest-instance, you can't create two partitions,partition-1 andpartition-2 that both useus-central1 as the instance partitionconfiguration.
• For every node in your instance partition, you can place a maximum of 100million placement rows. You can view the number of placement rows that havebeen placed in each of your instance partitions on the Instance partitionspage of the Google Cloud console.
• For every node in your destination instance partition, Spannercanmove around 10 placement rows per second.
• You can't createincremental backupsorcopy the backup.
• You can't create instance partitions in an instance withmanaged autoscaler enabled.
• You can't move the instance partition to a different instance configuration.
• You can't move an instance that has instance partitions. (You can moveindividual rows into different instance partitions so you don't need to movethe instance.)
• Using instance partitions doesn't guarantee compliance and regulatoryrequirements.
• Change streams don't support partitioned data.
• If you use anINSERT orDELETE DML statement for a placement table, thatstatement must be the only statement in thetransaction.
• The read-write transaction mode lets you reference only the primary keys of aplacement table in theWHERE clause. If you need to reference a non-primarykey column of a placement table in theWHERE clause, then you can use one ofthe following alternatives:
  • If you only need read-only access, switch to the read-only transaction mode.
  • If you need to make updates, either use the partitioned DML transactionmode, or find the primary keys in a read-only transaction query, and then,in a separate read-write transaction, reference the returned primary keys intheWHERE clause.
• You can't usenamed schemas.
• You can't create instance partitions infree trial instances orgranular-sized instances smaller than one node (1000 processing units).
• You can't alter a placement. Instead, you cancreate a new placement,usepartitioned DML to update theplacement of your data to a new placement, and thendrop the originalplacement.

Access control with IAM

You need to have thespanner.instancePartitions.create,spanner.instancePartitions.update, andspanner.instancePartitions.deletepermissions to create and manage instance partitions. If you only need to viewthe instance partitions, you need to have thespanner.instancePartitions.listorspanner.instancePartitions.get permission. For more information, seeIAM overview.

For information on how to grant Spanner IAMpermissions, seeApply IAM permissions.

Monitoring

Spanner provides several metrics to help you monitor yourinstance partitions. After you've created an additional instance partition, yousee an additional drop-down filter forInstance partitions on the Systeminsights page in the Google Cloud console. The default selection is to showmetrics forAll instance partitions. You can use the drop-down to filter themetrics for a specific instance partition.

To learn more about monitoring your Spanner resources, seeMonitor instances with Cloud Monitoring.

Backups

You can createfull backups for databases that usegeo-partitioning. You can't delete the instance partition if you use it ina backup. For more information, seeCreate backups.

Usage notes:

• Spanner stores backups of geo-partitioned data in the sameplacement location as the original data at the backup's version time.

• Torestore backups thatcontain geo-partitioned data, your destination instance must meet thefollowing conditions:

  • The destination instance must use the same instance partition names as theoriginal backup.
  • Each instance partition in the destination instance must use the sameinstance configuration as the original backup.

Pricing

There is no additional charge for using geo-partitioning. You are charged thestandard Spanner pricing for the amount of compute capacity thatyour instance uses and the amount of storage that your database uses.

For more information, seeSpanner pricing.

What's next

• Learn how toCreate and manage instance partitions.
• Learn how toCreate and manage data placements.