Create and manage instances

This page describes how to create, list, edit, and delete Cloud Spanner instances.

Note: To explore Spanner using a 90-day free trial instance, see Create a Spanner free trial instance.

Create an instance

You can create an instance with the Google Cloud CLI or with the Google Cloud console and client libraries. You can also create an instance with a custom instance configuration by adding optional read-only replicas.

Note: You do not need to provision storage in Spanner, and you are billed only for the storage that you use. Learn more about storage pricing.

Console

1. Go to the Create an instance page in the Google Cloud console.

   Create an instance

2. Enter the following values:

   • An instance name to display in the Google Cloud 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.
   • Choose a configuration, which defines the geographic location of the instance and affects how data is replicated.

   • If the configuration you selected has any read-only replica locations available, and you would like to add a read-only replica to your instance configuration, click Add read-only replica and select its region and number. Add optional read-only replicas to scale reads and support low latency stale reads. (When you create and add a read-only replica to an instance configuration using the Google Cloud console, the custom instance configuration is created automatically.)

   • 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.

3. 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]: A permanent identifier of your instance configuration, which defines the geographic location of the instance and affects how data is replicated. For custom instance configurations, it starts with custom-. For more information, see instance configurations.
• [INSTANCE-NAME]: The name to display for the instance in the Google Cloud 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).

To create an instance test-instance in the base regional instance configuration us-central1, run:

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="Test Instance" --nodes=1

To create an instance custom-eur6-instance in the custom multi-region instance configuration custom-eur6, first create a custom instance configuration. Then, run:

gcloud spanner instances create custom-eur6-instance --config=custom-eur6 \
  --description="Instance with custom read-only" --nodes=1

You should see a message similar to the following example after running either one of the commands above:

Creating instance...done.

C++

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

View on GitHub Feedback

void CreateInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                    std::string const& project_id,
                    std::string const& instance_id,
                    std::string const& display_name,
                    std::string const& config_id) {
  namespace spanner = ::google::cloud::spanner;
  spanner::Instance in(project_id, instance_id);

  auto project = google::cloud::Project(project_id);
  std::string config_name =
      project.FullName() + "/instanceConfigs/" + config_id;
  auto instance =
      client
          .CreateInstance(spanner::CreateInstanceRequestBuilder(in, config_name)
                              .SetDisplayName(display_name)
                              .SetNodeCount(1)
                              .SetLabels({{"cloud_spanner_samples", "true"}})
                              .Build())
          .get();
  if (!instance) throw std::move(instance).status();
  std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
}

C#

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

View on GitHub Feedback

using Google.Api.Gax.ResourceNames;
using Google.Cloud.Spanner.Admin.Instance.V1;
using Google.Cloud.Spanner.Common.V1;
using Google.LongRunning;
using System;

public class CreateInstanceSample
{
    public Instance CreateInstance(string projectId, string instanceId)
    {
        // Create the InstanceAdminClient instance.
        InstanceAdminClient instanceAdminClient = InstanceAdminClient.Create();

        // Initialize request parameters.
        Instance instance = new Instance
        {
            InstanceName = InstanceName.FromProjectInstance(projectId, instanceId),
            ConfigAsInstanceConfigName = InstanceConfigName.FromProjectInstanceConfig(projectId, "regional-us-central1"),
            DisplayName = "This is a display name.",
            NodeCount = 1,
            Labels =
            {
                { "cloud_spanner_samples", "true" },
            }
        };
        ProjectName projectName = ProjectName.FromProject(projectId);

        // Make the CreateInstance request.
        Operation<Instance, CreateInstanceMetadata> response = instanceAdminClient.CreateInstance(projectName, instanceId, instance);

        Console.WriteLine("Waiting for the operation to finish.");

        // Poll until the returned long-running operation is complete.
        Operation<Instance, CreateInstanceMetadata> completedResponse = response.PollUntilCompleted();

        if (completedResponse.IsFaulted)
        {
            Console.WriteLine($"Error while creating instance: {completedResponse.Exception}");
            throw completedResponse.Exception;
        }

        Console.WriteLine($"Instance created successfully.");

        return completedResponse.Result;
    }
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
	instancepb "google.golang.org/genproto/googleapis/spanner/admin/instance/v1"
)

func createInstance(w io.Writer, projectID, instanceID string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance"
	ctx := context.Background()
	instanceAdmin, err := instance.NewInstanceAdminClient(ctx)
	if err != nil {
		return err
	}
	defer instanceAdmin.Close()

	op, err := instanceAdmin.CreateInstance(ctx, &instancepb.CreateInstanceRequest{
		Parent:     fmt.Sprintf("projects/%s", projectID),
		InstanceId: instanceID,
		Instance: &instancepb.Instance{
			Config:      fmt.Sprintf("projects/%s/instanceConfigs/%s", projectID, "regional-us-central1"),
			DisplayName: instanceID,
			NodeCount:   1,
			Labels:      map[string]string{"cloud_spanner_samples": "true"},
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance %s: %v", fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID), err)
	}
	// Wait for the instance creation to finish.
	i, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for instance creation to finish failed: %v", err)
	}
	// The instance may not be ready to serve yet.
	if i.State != instancepb.Instance_READY {
		fmt.Fprintf(w, "instance state is not READY yet. Got state %v\n", i.State)
	}
	fmt.Fprintf(w, "Created instance [%s]\n", instanceID)
	return nil
}

Java

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

View on GitHub Feedback

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.spanner.Instance;
import com.google.cloud.spanner.InstanceAdminClient;
import com.google.cloud.spanner.InstanceConfigId;
import com.google.cloud.spanner.InstanceId;
import com.google.cloud.spanner.InstanceInfo;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.spanner.admin.instance.v1.CreateInstanceMetadata;
import java.util.concurrent.ExecutionException;

class CreateInstanceExample {

  static void createInstance() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    createInstance(projectId, instanceId);
  }

  static void createInstance(String projectId, String instanceId) {
    Spanner spanner = SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
    InstanceAdminClient instanceAdminClient = spanner.getInstanceAdminClient();

    // Set Instance configuration.
    String configId = "regional-us-central1";
    int nodeCount = 2;
    String displayName = "Descriptive name";

    // Create an InstanceInfo object that will be used to create the instance.
    InstanceInfo instanceInfo =
        InstanceInfo.newBuilder(InstanceId.of(projectId, instanceId))
            .setInstanceConfigId(InstanceConfigId.of(projectId, configId))
            .setNodeCount(nodeCount)
            .setDisplayName(displayName)
            .build();
    OperationFuture<Instance, CreateInstanceMetadata> operation =
        instanceAdminClient.createInstance(instanceInfo);
    try {
      // Wait for the createInstance operation to finish.
      Instance instance = operation.get();
      System.out.printf("Instance %s was successfully created%n", instance.getId());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance %s failed with error message %s%n",
          instanceInfo.getId(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
    } finally {
      spanner.close();
    }
  }
}

Node.js

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

View on GitHub Feedback

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

const instance = spanner.instance(instanceId);

// Creates a new instance
try {
  console.log(`Creating instance ${instance.formattedName_}.`);
  const [, operation] = await instance.create({
    config: 'regional-us-west1',
    nodes: 1,
    displayName: 'This is a display name.',
    labels: {
      ['cloud_spanner_samples']: 'true',
      created: Math.round(Date.now() / 1000).toString(), // current time
    },
  });

  console.log(`Waiting for operation on ${instance.id} to complete...`);
  await operation.promise();

  console.log(`Created instance ${instanceId}.`);
} catch (err) {
  console.error('ERROR:', err);
}

PHP

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

View on GitHub Feedback

use Google\Cloud\Spanner\SpannerClient;

/**
 * Creates an instance.
 * Example:
 * ```
 * create_instance($instanceId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 */
function create_instance(string $instanceId): void
{
    $spanner = new SpannerClient();
    $instanceConfig = $spanner->instanceConfiguration(
        'regional-us-central1'
    );
    $operation = $spanner->createInstance(
        $instanceConfig,
        $instanceId,
        [
            'displayName' => 'This is a display name.',
            'nodeCount' => 1,
            'labels' => [
                'cloud_spanner_samples' => true,
            ]
        ]
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    printf('Created instance %s' . PHP_EOL, $instanceId);
}

Python

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

View on GitHub Feedback

def create_instance(instance_id):
    """Creates an instance."""
    spanner_client = spanner.Client()

    config_name = "{}/instanceConfigs/regional-us-central1".format(
        spanner_client.project_name
    )

    instance = spanner_client.instance(
        instance_id,
        configuration_name=config_name,
        display_name="This is a display name.",
        node_count=1,
        labels={
            "cloud_spanner_samples": "true",
            "sample_name": "snippets-create_instance-explicit",
            "created": str(int(time.time())),
        },
    )

    operation = instance.create()

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Created instance {}".format(instance_id))

Ruby

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

View on GitHub Feedback

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/instance"

instance_admin_client = Google::Cloud::Spanner::Admin::Instance.instance_admin

project_path = instance_admin_client.project_path project: project_id
instance_path = instance_admin_client.instance_path project: project_id, instance: instance_id
instance_config_path = instance_admin_client.instance_config_path project: project_id, instance_config: "regional-us-central1"

job = instance_admin_client.create_instance parent: project_path,
                                            instance_id: instance_id,
                                            instance: { name: instance_path,
                                                        config: instance_config_path,
                                                        display_name: instance_id,
                                                        node_count: 2,
                                                        labels: { cloud_spanner_samples: "true" } }

puts "Waiting for create instance operation to complete"

job.wait_until_done!

if job.error?
  puts job.error
else
  puts "Created instance #{instance_id}"
end

List instances

You can show a list of your Spanner instances.

Console

Go to the Spanner Instances page in the Google Cloud console.

Go to the Instances page

The Google Cloud console shows a list of your 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 Spanner instances, along with each instance's ID, display name, configuration, and compute capacity.

Edit 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.

Change the display name

Console

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Click the name of the instance that you want to rename.

3. Click Edit instance.

4. Enter a new instance name. This name must be unique within the Google Cloud project.

5. 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 Google Cloud console. The instance name must be unique within your Google Cloud project.

Change 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 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, Spanner has created a large number of splits for your instance's data, and in some rare cases 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

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Click the name of the instance that you want to change.

3. Click Edit Instance.

4. 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.

5. 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).

Label an instance

Labels help organize your resources.

Console

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Select the checkbox for the instance. The Info panel appears on the right-hand side of the page.

3. Click the Labels tab in the Info panel. You can then add, delete or update labels for the Spanner instance.

Move an instance

For instructions on how to move your instance from any instance configuration to any other instance configuration, including between regional and multi-regional configurations, see Move an instance.

Delete an instance

Warning: Deleting an instance permanently removes the instance and all its databases. You can't undo this later. Also, you cannot create another free trial instance once you've deleted your first free trial instance. You can create one free trial instance per project lifecycle.

Console

1. Go to the Spanner Instances page in the Google Cloud console.

   Go to the Instances page

2. Click the name of the instance that you want to delete.

3. Click Delete instance.

4. Follow the instructions to confirm that you want to delete the instance.

5. Click Delete.

gcloud

Use the gcloud spanner instances delete command, replacing [INSTANCE-ID] with the instance ID:

gcloud spanner instances delete [INSTANCE-ID]

Stop or restart 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 Spanner schema.