This page describes how to create, list, edit, and delete Cloud Spanner instances.
Creating an instance
You can create an instance with the Google Cloud CLI or with the Google Cloud console.
Console
Go to the Create an instance page in the console.
Enter the following values:
- An instance name to display in the console. The instance name must be unique within your Google Cloud project.
- An instance ID to permanently identify your instance. The instance ID must also be unique within your Google Cloud project. You cannot change the instance ID later.
- A configuration, which defines the geographic location of the instance and affects how data is replicated. Learn more about instance configurations.
- The amount of compute capacity for the instance. The compute capacity determines the amount of serving and storage resources that are available to databases in the instance. You specify the compute capacity by choosing the measurement units (processing units or nodes) and then entering a quantity. When using processing units, enter quantities up to 1000 in multiples of 100 (100, 200, 300 and so on) and enter greater quantities in multiples of 1000 (1000, 2000, 3000 and so on). Each node equals 1000 processing units. Learn more about processing units and nodes.
Click Create to create the instance.
gcloud
Use the gcloud spanner instances create
command. When using this command,
specify the compute capacity as a number or nodes or processing units.
gcloud spanner instances create [INSTANCE-ID] --config=[INSTANCE-CONFIG] \
--description="[INSTANCE-NAME]" --nodes=[NODE-COUNT]
or
gcloud spanner instances create [INSTANCE-ID] --config=[INSTANCE-CONFIG] \
--description="[INSTANCE-NAME]" --processing-units=[PROCESSING-UNIT-COUNT]
Provide the following values:
[INSTANCE-ID]
: A permanent identifier that is unique within your Google Cloud project. You cannot change the instance ID later.[INSTANCE-CONFIG]
: The instance configuration, which defines the geographic location of the instance and affects how data is replicated. Learn more about instance configurations.[INSTANCE-NAME]
: The name to display for the instance in the console. The instance name must be unique within your Google Cloud project.[NODE-COUNT]
: The compute capacity of the instance, expressed as a number of nodes. Each node equals 1000 processing units.[PROCESSING-UNIT-COUNT]
: The compute capacity of the instance, expressed as a number of processing units. Enter quantities up to 1000 in multiples of 100 (100, 200, 300 and so on) and enter greater quantities in multiples of 1000 (1000, 2000, 3000 and so on).
For example:
gcloud spanner instances create test-instance --config=regional-us-central1 \
--description="Test Instance" --nodes=1
You should see a message similar to the following example:
Creating instance...done.
C++
To learn how to install and use the client library for Spanner, see Spanner client libraries.
C#
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Go
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Java
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Node.js
To learn how to install and use the client library for Spanner, see Spanner client libraries.
PHP
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Python
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Ruby
To learn how to install and use the client library for Spanner, see Spanner client libraries.
Listing instances
Console
Go to the Spanner Instances page in the console.
The console shows a list of your Cloud Spanner instances, along with each instance's ID, display name, configuration, and compute capacity expressed in both processing units and in nodes.
gcloud
Use the gcloud spanner instances list
command:
gcloud spanner instances list
The gcloud CLI prints a list of your Cloud Spanner instances, along with each instance's ID, display name, configuration, and compute capacity.
Editing an instance
The following sections explain how to change an instance's display name and compute capacity. You cannot change the instance ID or instance configuration.
Changing the display name
Console
Go to the Spanner Instances page in the console.
Click the name of the instance that you want to rename.
Click Edit instance.
Enter a new instance name. This name must be unique within the Google Cloud project.
Click Save.
gcloud
Use the gcloud spanner instances update
command:
gcloud spanner instances update [INSTANCE-ID] --description=[INSTANCE-NAME]
Provide the following values:
[INSTANCE-ID]
: The permanent identifier for the instance.[INSTANCE-NAME]
: The name to display for the instance in the console. The instance name must be unique within your Google Cloud project.
Changing the compute capacity
You must provision enough compute capacity to keep CPU utilization and storage utilization below the recommended maximums. For more information, see the quotas and limits for Cloud Spanner.
There are a few cases in which you cannot reduce the compute capacity of an existing instance:
- Removing compute capacity would require your instance to store more than 4 TB of data per 1000 processing units (1 node).
- Based on your historic usage patterns, Cloud Spanner has created a large number of splits for your instance's data, and in some rare cases Cloud Spanner would not be able to manage the splits after removing compute capacity.
In the latter case, you may try reducing the compute capacity by progressively smaller amounts until you find the minimum capacity that Cloud Spanner needs to manage all of the instance's splits. If the instance no longer requires so many splits due to a change in usage patterns, Cloud Spanner may eventually merge some splits together and allow you to try reducing the instance's compute capacity further after a week or two.
When removing compute capacity, monitor your CPU utilization and request latencies in Cloud Monitoring to ensure CPU utilization stays below 65% for regional instances and 45% for each region in multi-region instances. You may experience a temporary increase in request latencies while removing compute capacity.
If you want to increase the compute capacity of an instance, your Google Cloud project must have sufficient quota to add the compute capacity.
Console
Go to the Spanner Instances page in the console.
Click the name of the instance that you want to change.
Click Edit Instance.
Change the compute capacity by choosing the measurement units (processing units or nodes) and then entering a quantity. When using processing units, enter quantities up to 1000 in multiples of 100 (100, 200, 300 and so on) and enter greater quantities in multiples of 1000 (1000, 2000, 3000 and so on). Each node equals 1000 processing units.
Click Save.
If you see a dialog that says you have insufficient quota to add compute capacity in this location, follow the instructions to request a higher quota.
gcloud
Use the gcloud spanner instances update
command. When using this command,
specify the compute capacity as a number or nodes or processing
units.
gcloud spanner instances update [INSTANCE-ID] --nodes=[NODE-COUNT]
or
gcloud spanner instances update [INSTANCE-ID] --processing-units=[PROCESSING-UNIT-COUNT]
Provide the following values:
[INSTANCE-ID]
: The permanent identifier for the instance.[NODE-COUNT]
: The compute capacity of the instance, expressed as a number of nodes. Each node equals 1000 processing units.[PROCESSING-UNIT-COUNT]
: The compute capacity of the instance, expressed as a number of processing units. Enter quantities up to 1000 in multiples of 100 (100, 200, 300 and so on) and enter greater quantities in multiples of 1000 (1000, 2000, 3000 and so on).
Labelling an instance
Labels help organize your resources.
Console
Go to the Spanner Instances page in the console.
Select the checkbox for the instance. The Info panel appears on the right-hand side of the page.
Click the Labels tab in the Info panel. You can then add, delete or update labels for the Cloud Spanner instance.
Deleting an instance
Console
Go to the Spanner Instances page in the console.
Click the name of the instance that you want to delete.
Click Delete instance.
Follow the instructions to confirm that you want to delete the instance.
Click Delete.
gcloud
Use the gcloud spanner instances delete
command, replacing
[INSTANCE-ID]
with the instance ID:
gcloud spanner instances delete [INSTANCE-ID]
Stopping or restarting an instance
Spanner is a fully managed database service which oversees its own underlying tasks and resources, including monitoring and restarting processes when necessary with zero downtime. As there is no need to manually stop or restart a given instance, Spanner does not offer a way to do so.
What's next
- Learn how to insert, update, and delete data with Data Manipulation Language (DML) or the gcloud CLI.
- Grant IAM roles for the instance and its databases.
- Understand how to design a Cloud Spanner schema.