Create and manage instance partitions

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 describes how to create and manage Spannerinstance partitions.

Create an instance partition

Console

  1. In the Google Cloud console, open theSpanner page.

    Go to Spanner

  2. Select the instance in which you want to add instance partitions.

  3. In the navigation menu, selectInstance partitions.

  4. ClickCreate instance partition.

  5. Enter aPartition ID to permanently identify your instancepartition. The instance partition ID must also be unique within yourGoogle Cloud project. You can't change the instance partition ID later.

  6. In theChoose a configuration section, selectRegionalorMulti-region.Alternatively, if you want to compare the specifications between theregions, then clickCompare region configurations.

  7. Select a configuration from the drop-down menu.

  8. In theAllocate compute capacity section, underUnit,click one of the following:

    • Processing units for small instance partitions.
    • Nodes for large instances. A node is 1000 processing units.

  9. Enter a value for the unit selected.

    Your instance partition must have at least one node or 1000 processing units.

  10. ClickCreate to create the instance partition.

gcloud

To create an instance partition, usegcloud beta spanner instance-partitions create.

gcloud beta spanner instance-partitions createINSTANCE_PARTITION_ID \  --config=INSTANCE_PARTITION_CONFIG \  --description="INSTANCE_PARTITION_DESCRIPTION" \  --instance=INSTANCE_ID \  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]

Replace the following:

  • INSTANCE_PARTITION_ID: the permanent instance partitionidentifier that is unique within your Google Cloud project. You can't changethe instance partition ID later.
  • INSTANCE_PARTITION_CONFIG: the permanent identifier of yourinstance partition configuration, which defines the geographic locationof the instance partition and affects where data is stored.
  • INSTANCE_PARTITION_DESCRIPTION: the name to display for theinstance partition in the Google Cloud console. The instance partitionname must be unique within your Google Cloud project.
  • INSTANCE_ID: the permanent identifier for yourSpanner instance where this instance partition resides.
  • NODE_COUNT: the compute capacity of the instance partition,expressed as a number of nodes. One node equals 1000 processing units.
  • PROCESSING_UNIT_COUNT: the compute capacity of the instance,expressed as a number of processing units. Your instance partition musthave at least 1000 processing units. Enter quantities in multiples of1000 (1000, 2000, 3000 and so on).

For example, to create an instance partitioneurope-partition ineur3with 5 nodes, run the following:

gcloudbetaspannerinstance-partitionscreateeurope-partition--config=eur3\--description="europe-partition"--instance=test-instance--nodes=5

Client libraries

C++

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

voidCreateInstancePartition(google::cloud::spanner_admin::InstanceAdminClientclient,std::stringconst&project_id,std::stringconst&instance_id,std::stringconst&instance_partition_id){autoproject=google::cloud::Project(project_id);autoin=google::cloud::spanner::Instance(project_id,instance_id);autoconfig=project.FullName()+"/instanceConfigs/nam3";google::spanner::admin::instance::v1::CreateInstancePartitionRequestrequest;request.set_parent(in.FullName());request.set_instance_partition_id(instance_partition_id);request.mutable_instance_partition()->set_display_name("Test instance partition");request.mutable_instance_partition()->set_node_count(1);request.mutable_instance_partition()->set_config(config);autoinstance_partition=client.CreateInstancePartition(request).get();if(!instance_partition)throwstd::move(instance_partition).status();std::cout <<"Created instance partition [" <<instance_partition_id <<"]:\n"            <<instance_partition->DebugString();}

C#

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

usingGoogle.Cloud.Spanner.Admin.Instance.V1;usingGoogle.Cloud.Spanner.Common.V1;usingGoogle.LongRunning;usingSystem;publicclassCreateInstancePartitionSample{publicInstancePartitionCreateInstancePartition(stringprojectId,stringinstanceId,stringinstancePartitionId){// Create the InstanceAdminClient instance.InstanceAdminClientinstanceAdminClient=InstanceAdminClient.Create();// Initialize request parameters.InstancePartitionpartition=newInstancePartition{DisplayName="This is a display name.",NodeCount=1,ConfigAsInstanceConfigName=InstanceConfigName.FromProjectInstanceConfig(projectId,"nam3"),};InstanceNameinstanceName=InstanceName.FromProjectInstance(projectId,instanceId);// Make the CreateInstancePartition request.Operation<InstancePartition,CreateInstancePartitionMetadata>response=instanceAdminClient.CreateInstancePartition(instanceName,partition,instancePartitionId);Console.WriteLine("Waiting for the operation to finish.");// Poll until the returned long-running operation is complete.Operation<InstancePartition,CreateInstancePartitionMetadata>completedResponse=response.PollUntilCompleted();if(completedResponse.IsFaulted){Console.WriteLine($"Error while creating instance partition: {completedResponse.Exception}");throwcompletedResponse.Exception;}Console.WriteLine($"Instance created successfully.");returncompletedResponse.Result;}}

Go

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

import("context""fmt""io"instance"cloud.google.com/go/spanner/admin/instance/apiv1""cloud.google.com/go/spanner/admin/instance/apiv1/instancepb")// Example of creating an instance partition with Go.// projectID is the ID of the project that the new instance partition will be in.// instanceID is the ID of the instance that the new instance partition will be in.// instancePartitionID is the ID of the new instance partition to be created.funccreateInstancePartition(wio.Writer,projectID,instanceID,instancePartitionIDstring)error{// projectID := "my-project-id"// instanceID := "my-instance"// instancePartitionID := "my-instance-partition"ctx:=context.Background()instanceAdmin,err:=instance.NewInstanceAdminClient(ctx)iferr!=nil{returnerr}deferinstanceAdmin.Close()op,err:=instanceAdmin.CreateInstancePartition(ctx,&instancepb.CreateInstancePartitionRequest{Parent:fmt.Sprintf("projects/%s/instances/%s",projectID,instanceID),InstancePartitionId:instancePartitionID,InstancePartition:&instancepb.InstancePartition{Config:fmt.Sprintf("projects/%s/instanceConfigs/%s",projectID,"nam3"),DisplayName:"my-instance-partition",ComputeCapacity:&instancepb.InstancePartition_NodeCount{NodeCount:1},},})iferr!=nil{returnfmt.Errorf("could not create instance partition %s: %w",fmt.Sprintf("projects/%s/instances/%s/instancePartitions/%s",projectID,instanceID,instancePartitionID),err)}// Wait for the instance partition creation to finish.i,err:=op.Wait(ctx)iferr!=nil{returnfmt.Errorf("waiting for instance partition creation to finish failed: %w",err)}// The instance partition may not be ready to serve yet.ifi.State!=instancepb.InstancePartition_READY{fmt.Fprintf(w,"instance partition state is not READY yet. Got state %v\n",i.State)}fmt.Fprintf(w,"Created instance partition [%s]\n",instancePartitionID)returnnil}

Java

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

importcom.google.cloud.spanner.Spanner;importcom.google.cloud.spanner.SpannerOptions;importcom.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;importcom.google.spanner.admin.instance.v1.CreateInstancePartitionRequest;importcom.google.spanner.admin.instance.v1.InstanceConfigName;importcom.google.spanner.admin.instance.v1.InstanceName;importcom.google.spanner.admin.instance.v1.InstancePartition;importjava.util.concurrent.ExecutionException;classCreateInstancePartitionSample{staticvoidcreateInstancePartition(){// TODO(developer): Replace these variables before running the sample.StringprojectId="my-project";StringinstanceId="my-instance";StringinstancePartitionId="my-instance-partition";createInstancePartition(projectId,instanceId,instancePartitionId);}staticvoidcreateInstancePartition(StringprojectId,StringinstanceId,StringinstancePartitionId){// Set instance partition configuration.intnodeCount=1;StringdisplayName="Descriptive name";// Create an InstancePartition object that will be used to create the instance partition.InstancePartitioninstancePartition=InstancePartition.newBuilder().setDisplayName(displayName).setNodeCount(nodeCount).setConfig(InstanceConfigName.of(projectId,"nam3").toString()).build();try(Spannerspanner=SpannerOptions.newBuilder().setProjectId(projectId).build().getService();InstanceAdminClientinstanceAdminClient=spanner.createInstanceAdminClient()){// Wait for the createInstancePartition operation to finish.InstancePartitioncreatedInstancePartition=instanceAdminClient.createInstancePartitionAsync(CreateInstancePartitionRequest.newBuilder().setParent(InstanceName.of(projectId,instanceId).toString()).setInstancePartitionId(instancePartitionId).setInstancePartition(instancePartition).build()).get();System.out.printf("Instance partition %s was successfully created%n",createdInstancePartition.getName());}catch(ExecutionExceptione){System.out.printf("Error: Creating instance partition %s failed with error message %s%n",instancePartition.getName(),e.getMessage());}catch(InterruptedExceptione){System.out.println("Error: Waiting for createInstancePartition operation to finish was interrupted");}}}

Node.js

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

// Imports the Google Cloud client libraryconst{Spanner}=require('@google-cloud/spanner');/** * TODO(developer): Uncomment the following lines before running the sample. */// const projectId = 'my-project-id';// const instanceId = 'my-instance';// const instancePartitionId = 'my-instance-partition';// Creates a clientconstspanner=newSpanner({projectId:projectId,});// Get the instance admin clientconstinstanceAdminClient=spanner.getInstanceAdminClient();// Creates a new instance partitiontry{console.log(`Creating instance partition${instanceAdminClient.instancePartitionPath(projectId,instanceId,instancePartitionId,)}.`,);const[operation]=awaitinstanceAdminClient.createInstancePartition({instancePartitionId:instancePartitionId,parent:instanceAdminClient.instancePath(projectId,instanceId),instancePartition:{config:instanceAdminClient.instanceConfigPath(projectId,'nam3'),nodeCount:1,displayName:'Test instance partition',},});console.log(`Waiting for operation on${instancePartitionId} to complete...`,);awaitoperation.promise();console.log(`Created instance partition${instancePartitionId}.`);}catch(err){console.error('ERROR:',err);}

PHP

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;use Google\Cloud\Spanner\Admin\Instance\V1\CreateInstancePartitionRequest;use Google\Cloud\Spanner\Admin\Instance\V1\InstancePartition;/** * Creates an instance partition. * Example: * ``` * create_instance_partition($projectId, $instanceId, $instancePartitionId); * ``` * * @param string $projectId The Google Cloud project ID. * @param string $instanceId The Spanner instance ID. * @param string $instancePartitionId The instance partition ID. */function create_instance_partition(string $projectId, string $instanceId, string $instancePartitionId): void{    $instanceAdminClient = new InstanceAdminClient();    $instanceName = $instanceAdminClient->instanceName($projectId, $instanceId);    $instancePartitionName = $instanceAdminClient->instancePartitionName($projectId, $instanceId, $instancePartitionId);    $configName = $instanceAdminClient->instanceConfigName($projectId, 'nam3');    $instancePartition = (new InstancePartition())        ->setConfig($configName)        ->setDisplayName('Test instance partition.')        ->setNodeCount(1);    $operation = $instanceAdminClient->createInstancePartition(        (new CreateInstancePartitionRequest())        ->setParent($instanceName)        ->setInstancePartitionId($instancePartitionId)        ->setInstancePartition($instancePartition)    );    print('Waiting for operation to complete...' . PHP_EOL);    $operation->pollUntilComplete();    printf('Created instance partition %s' . PHP_EOL, $instancePartitionId);}

Python

To learn how to install and use the client library for Spanner, seeSpanner client libraries.

defcreate_instance_partition(instance_id,instance_partition_id):"""Creates an instance partition."""fromgoogle.cloud.spanner_admin_instance_v1.typesimportspanner_instance_adminspanner_client=spanner.Client()instance_admin_api=spanner_client.instance_admin_apiconfig_name="{}/instanceConfigs/nam3".format(spanner_client.project_name)operation=spanner_client.instance_admin_api.create_instance_partition(parent=instance_admin_api.instance_path(spanner_client.project,instance_id),instance_partition_id=instance_partition_id,instance_partition=spanner_instance_admin.InstancePartition(config=config_name,display_name="Test instance partition",node_count=1,),)print("Waiting for operation to complete...")operation.result(OPERATION_TIMEOUT_SECONDS)print("Created instance partition{}".format(instance_partition_id))

Describe an instance partition

gcloud

To describe an instance partition, usegcloud beta spanner instance-partitions describe.

gcloud beta spanner instance-partitions describePARTITION_ID \  --instance=INSTANCE_ID

Replace the following:

  • INSTANCE_PARTITION_ID: the permanent identifier for theinstance partition.
  • INSTANCE_ID: the permanent identifier for the instance.

For example, to describe the instance partitioneurope-partition,run the following:

gcloudbetaspannerinstance-partitionsdescribeeurope-partition--instance=test-instance

List instance partitions

Console

  1. In the Google Cloud console, open theSpanner page.

    Go to Spanner

  2. Select an instance from the list.

  3. In the navigation menu, selectInstance partitions.

    A list of instance partitions associated with that instance is shown.

gcloud

To list your instance partitions, usegcloud beta spanner instance-partitions list.

gcloud beta spanner instance-partitions list --instance=INSTANCE_ID

The gcloud CLI prints a list of your Spannerinstance partitions, along with each instance partition's ID, display name,configuration, and compute capacity.

Edit an instance partition

The following section explains how to change the compute capacity of yourinstance partition. You can't change the instance partition ID, name, orconfiguration.

Change the compute capacity

You must provision enoughcompute capacity to keepCPU utilization andstorage utilization below the recommendedmaximums. For more information, see thequotas and limits forSpanner.

If you want to increase the compute capacity of an instance partition, yourGoogle Cloud project must have sufficient quota to add the compute capacity. Thetime it takes for the increase request to complete depends on the size of therequest. In most cases, requests complete within a few minutes. On rareoccasions, a scale up might take up to an hour to complete.

Console

  1. In the Google Cloud console, open theSpanner page.

    Go to Spanner

  2. Select an instance from the list.

  3. In the navigation menu, selectInstance partitions.

  4. In the list of instance partitions, under theActions column, clickMore Actions and selectEdit.

  5. Change the compute capacity by choosing a measurement unit(processing units or nodes), and then entering a quantity. When usingprocessing units, enter quantities in multiples of 1000(1000, 2000, 3000 and so on). Each node equals 1000 processing units.

    Your instance partition must have at least one node (1000 processing units).

  6. ClickSave.

    If you see a dialog that says you have insufficient quota to add computecapacity , follow the instructions to request a higher quota.

gcloud

To change the compute capacity of your instance partition, usegcloud beta spanner instance-partitions update.When using this command, specify thecompute capacity as anumber of nodes or processing units.

gcloud beta spanner instance-partitions updateINSTANCE_PARTITION_ID \  --instance=INSTANCE_ID \  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]  [--async]

Replace the following:

  • INSTANCE_PARTITION_ID: the permanent identifier for theinstance partition.
  • INSTANCE_ID: the permanent identifier for the instance.
  • NODE_COUNT: the new compute capacity of the instance partition,expressed as a number of nodes. One node equals 1000 processing units.
  • PROCESSING_UNIT_COUNT: the new compute capacity of theinstance partition, expressed as a number of processing units. Yourinstance partition must have at least 1000 processing units. Enterquantities in multiples of 1000 (1000, 2000, 3000 and so on).

Optional flags:

  • --async: Use this flag if you want your request to return immediately,without waiting for the operation in progress to complete.

You can check the status of your request by runninggcloud spanner operations describe.

Delete an instance partition

You can't delete an instance partition while it's associated with any placementsor data. You must firstmove any data that's in the instance partitionor delete the placement tables that use the instance partition before you candelete the instance partition.

Console

  1. In the Google Cloud console, open theSpanner page.

    Go to Spanner

  2. Select an instance from the list.

  3. In the navigation menu, selectInstance partitions.

  4. In the list of instance partitions, under theActions column, clickMoreActions, and selectDelete.

  5. Follow the instructions to confirm that you want to delete the Instancepartition.

  6. ClickDelete.

gcloud

Use thegcloud beta spanner instance-partitions deletecommand.

gcloud beta spanner instance-partitions deleteINSTANCE_PARTITION_ID  --instance=INSTANCE_ID

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.