Create and manage instances

This page describes how to create, list, edit, and delete 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 console, the Google Cloud CLI, or client libraries. You can also create an instance with a custom instance configuration by adding optional read-only replicas.

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

Console

1. In the Google Cloud console, go to the Spanner Instances page.

2. Click Create instance.

   Go to Create instance

3. In the Select an edition section, select a Spanner edition.

   If you want to compare the specifications between the different editions, then click Compare editions. For more information, see the Spanner editions overview.

4. Click Continue.

5. In the Name your instance section, enter an Instance name to display in the Google Cloud console. The instance name must be unique within your Google Cloud project.

6. Enter 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.

7. Click Continue.

8. In the Configure your instance section, under Choose a configuration, select Regional, Dual-region, or Multi-region.

   Note: Dual-region and multi-region instance configurations are only available in the Enterprise Plus edition. If you want to compare the specifications between the three configurations, then click Compare region configurations.

9. Select a configuration location from the drop-down.

10. Optional: To add a read-only replica to a Spanner base configuration, first create a custom instance configuration using the Google Cloud CLI. Adding optional read-only replicas to a base configuration is available in the Enterprise edition and Enterprise Plus edition.

11. Click Continue.

12. In the Allocate compute capacity section, under Select unit, click one of the following:

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

    For more information, see Compute capacity, nodes and processing units.

13. Under Choose a scaling mode, click one of the following:

    • Manual allocation if you want to manually set compute capacity for fixed compute resources and costs.

      • Quantity indicates the number of processing units or nodes to use for this instance.

    • Autoscaling (Preview), to let Spanner automatically add and remove compute capacity. Managed autoscaler is available in the Spanner Enterprise edition and Enterprise Plus edition. For more information about the managed autoscaler, see Managed autoscaler for Spanner. Configure the following managed autoscaler options:

      • Minimum indicates the minimum limit to scale down to, depending on the measurement unit that you choose for Compute capacity. For more information, see Determine the minimum limit.
      • Maximum indicates the maximum limit to scale up to, depending on the measurement unit that you choose for Compute capacity. For more information, see Determine the maximum limit.
      • High priority CPU utilization target indicates the target percentage of high priority CPU to use. For more information, see Determine the CPU utilization target.
      • Storage utilization target indicates the target percentage of storage to use. For more information, see Determine the Storage Utilization Target.

14. Click Create to create the instance.

gcloud

Use the gcloud spanner instances create command to create an instance. Specify the compute capacity as the number of nodes or processing units that you want on the instance.

gcloud spanner instances create INSTANCE_ID \
--edition=EDITION \
--config=INSTANCE_CONFIG \
--description=INSTANCE_DESCRIPTION \
--nodes=NODE_COUNT

or

gcloud spanner instances create INSTANCE_ID \
--edition=EDITION \
--config=INSTANCE_CONFIG \
--description=INSTANCE_DESCRIPTION \
--processing-units=PROCESSING_UNIT_COUNT

Replace the following:

• 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_DESCRIPTION: 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). Note: Don't use this parameter if you're creating an instance that you intend to enable with the managed autoscaler later.

Add managed autoscaling (Preview)

You can also create Enterprise edition and Enterprise Plus edition instances to use managed autoscaling with the gcloud beta spanner instances create command. For more information, see Managed autoscaler for Spanner.

Use the following command to create an instance with managed autoscaler.

  gcloud beta spanner instances create INSTANCE_ID \
    --edition=EDITION \
    --config=INSTANCE_CONFIG \
    --description=INSTANCE_DESCRIPTION \
    --autoscaling-min-processing-units=MINIMUM_PROCESSING_UNITS \
    --autoscaling-max-processing-units=MAXIMUM_PROCESSING_UNITS \
    --autoscaling-high-priority-cpu-target=CPU_PERCENTAGE \
    --autoscaling-storage-target=STORAGE_PERCENTAGE

or

  gcloud beta spanner instances create INSTANCE_ID \
    --edition=EDITION \
    --config=INSTANCE_CONFIG \
    --description=INSTANCE_DESCRIPTION \
    --autoscaling-min-nodes=MINIMUM_NODES \
    --autoscaling-max-nodes=MAXIMUM_NODES \
    --autoscaling-high-priority-cpu-target=CPU_PERCENTAGE \
    --autoscaling-storage-target=STORAGE_PERCENTAGE

Replace the following:

• 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-DESCRIPTION: the name to display for the instance in the Google Cloud console. The instance name must be unique within your Google Cloud project.
• MINIMUM_PROCESSING_UNITS, MINIMUM_NODES: the minimum number of processing units or nodes when scaling down. For more information, see Determine the minimum limit.
• MAXIMUM_PROCESSING_UNITS, MAXIMUM_NODES: the maximum number of processing units or nodes when scaling up. For more information, see Determine the maximum limit.
• CPU_PERCENTAGE: the target percentage of high priority CPU to use, from 10 to 90%. If you're optimizing for cost, then use a higher percentage. For more information, see Determine the CPU utilization target.
• STORAGE_PERCENTAGE: the target percentage of storage to use, from 10 to 99%. For more information, see Determine the storage utilization target.

Examples for using custom configurations

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

gcloud spanner instances create test-instance --edition=STANDARD --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 --edition=ENTERPRISE_PLUS --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 previous commands:

Creating instance...done.

C++

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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.

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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.

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import (
	"context"
	"fmt"
	"io"

	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
	"cloud.google.com/go/spanner/admin/instance/apiv1/instancepb"
)

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"},
			Edition:     instancepb.Instance_STANDARD,
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance %s: %w", 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: %w", 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
}

Create an instance with managed autoscaling using Go (Preview)

import (
	"context"
	"fmt"
	"io"

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

// Example of creating an autoscaling instance with Go.
// projectID is the ID of the project that the new instance will be in.
// instanceID is the ID of the new instance to be created.
func createInstanceWithAutoscalingConfig(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 fmt.Errorf("could not create instance admin client for project %s: %w", projectID, err)
	}
	defer instanceAdmin.Close()

	instanceName := fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID)
	fmt.Fprintf(w, "Creating instance %s.", instanceName)

	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: "Create instance example",
			AutoscalingConfig: &instancepb.AutoscalingConfig{
				AutoscalingLimits: &instancepb.AutoscalingConfig_AutoscalingLimits{
					MinLimit: &instancepb.AutoscalingConfig_AutoscalingLimits_MinNodes{
						MinNodes: 1,
					},
					MaxLimit: &instancepb.AutoscalingConfig_AutoscalingLimits_MaxNodes{
						MaxNodes: 2,
					},
				},
				AutoscalingTargets: &instancepb.AutoscalingConfig_AutoscalingTargets{
					HighPriorityCpuUtilizationPercent: 65,
					StorageUtilizationPercent:         95,
				},
			},
			Labels: map[string]string{"cloud_spanner_samples": "true"},
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance %s: %w", instanceName, err)
	}
	fmt.Fprintf(w, "Waiting for operation on %s to complete...", instanceID)
	// 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: %w", 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)

	instance, err := instanceAdmin.GetInstance(ctx, &instancepb.GetInstanceRequest{
		Name: instanceName,
		// Get the autoscaling_config field from the newly created instance.
		FieldMask: &field_mask.FieldMask{Paths: []string{"autoscaling_config"}},
	})
	if err != nil {
		return fmt.Errorf("failed to get instance [%s]: %w", instanceName, err)
	}
	fmt.Fprintf(w, "Instance %s has autoscaling_config: %s.", instanceID, instance.AutoscalingConfig)
	return nil
}

Java

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
import com.google.spanner.admin.instance.v1.CreateInstanceRequest;
import com.google.spanner.admin.instance.v1.Instance;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.ProjectName;
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) {
    // Set Instance configuration.
    int nodeCount = 2;
    String displayName = "Descriptive name";

    // Create an Instance object that will be used to create the instance.
    Instance instance =
        Instance.newBuilder()
            .setDisplayName(displayName)
            .setEdition(Instance.Edition.STANDARD)
            .setNodeCount(nodeCount)
            .setConfig(InstanceConfigName.of(projectId, "regional-us-east4").toString())
            .build();

    try (Spanner spanner =
            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
        InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {

      // Wait for the createInstance operation to finish.
      Instance createdInstance =
          instanceAdminClient
              .createInstanceAsync(
                  CreateInstanceRequest.newBuilder()
                      .setParent(ProjectName.of(projectId).toString())
                      .setInstanceId(instanceId)
                      .setInstance(instance)
                      .build())
              .get();
      System.out.printf("Instance %s was successfully created%n", createdInstance.getName());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance %s failed with error message %s%n",
          instance.getName(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
    }
  }
}

Note: The old client library interface code samples for Java are archived in GitHub.

Create an instance with managed autoscaling using Java (Preview)

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
import com.google.spanner.admin.instance.v1.AutoscalingConfig;
import com.google.spanner.admin.instance.v1.CreateInstanceRequest;
import com.google.spanner.admin.instance.v1.Instance;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.ProjectName;
import java.util.concurrent.ExecutionException;

class CreateInstanceWithAutoscalingConfigExample {

  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) {
    try (Spanner spanner =
        SpannerOptions.newBuilder()
            .setProjectId(projectId)
            .build()
            .getService();
        InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {
      // Set Instance configuration.
      String configId = "regional-us-east4";
      String displayName = "Descriptive name";

      // Create an autoscaling config.
      // When autoscaling_config is enabled, node_count and processing_units fields
      // need not be specified.
      AutoscalingConfig autoscalingConfig =
          AutoscalingConfig.newBuilder()
              .setAutoscalingLimits(
                  AutoscalingConfig.AutoscalingLimits.newBuilder().setMinNodes(1).setMaxNodes(2))
              .setAutoscalingTargets(
                  AutoscalingConfig.AutoscalingTargets.newBuilder()
                      .setHighPriorityCpuUtilizationPercent(65)
                      .setStorageUtilizationPercent(95))
              .build();
      Instance instance =
          Instance.newBuilder()
              .setAutoscalingConfig(autoscalingConfig)
              .setDisplayName(displayName)
              .setConfig(
                  InstanceConfigName.of(projectId, configId).toString())
              .build();

      // Creates a new instance
      System.out.printf("Creating instance %s.%n", instanceId);
      try {
        // Wait for the createInstance operation to finish.
        Instance instanceResult = instanceAdminClient.createInstanceAsync(
            CreateInstanceRequest.newBuilder()
                .setParent(ProjectName.of(projectId).toString())
                .setInstanceId(instanceId)
                .setInstance(instance)
                .build()).get();
        System.out.printf("Autoscaler instance %s was successfully created%n",
            instanceResult.getName());
      } catch (ExecutionException e) {
        System.out.printf(
            "Error: Creating instance %s failed with error message %s%n",
            instance.getName(), e.getMessage());
      } catch (InterruptedException e) {
        System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
      }
    }
  }
}

Node.js

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

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

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

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

// Creates a new instance
try {
  console.log(
    `Creating instance ${instanceAdminClient.instancePath(
      projectId,
      instanceId
    )}.`
  );
  const [operation] = await instanceAdminClient.createInstance({
    instanceId: instanceId,
    parent: instanceAdminClient.projectPath(projectId),
    instance: {
      config: instanceAdminClient.instanceConfigPath(
        projectId,
        'regional-us-central1'
      ),
      nodeCount: 1,
      displayName: 'Display name for the instance.',
      labels: {
        cloud_spanner_samples: 'true',
        created: Math.round(Date.now() / 1000).toString(), // current time
      },
      edition:
        protos.google.spanner.admin.instance.v1.Instance.Edition.STANDARD, //optional
    },
  });

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

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

Note: The old client library interface code samples for Node.js are archived in GitHub.

PHP

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

use Google\Cloud\Spanner\Admin\Instance\V1\Client\InstanceAdminClient;
use Google\Cloud\Spanner\Admin\Instance\V1\CreateInstanceRequest;
use Google\Cloud\Spanner\Admin\Instance\V1\Instance;

/**
 * Creates an instance.
 * Example:
 * ```
 * create_instance($projectId, $instanceId);
 * ```
 *
 * @param string $projectId  The Spanner project ID.
 * @param string $instanceId The Spanner instance ID.
 */
function create_instance(string $projectId, string $instanceId): void
{
    $instanceAdminClient = new InstanceAdminClient();
    $parent = InstanceAdminClient::projectName($projectId);
    $instanceName = InstanceAdminClient::instanceName($projectId, $instanceId);
    $configName = $instanceAdminClient->instanceConfigName($projectId, 'regional-us-central1');
    $instance = (new Instance())
        ->setName($instanceName)
        ->setConfig($configName)
        ->setDisplayName('dispName')
        ->setNodeCount(1);

    $operation = $instanceAdminClient->createInstance(
        (new CreateInstanceRequest())
        ->setParent($parent)
        ->setInstanceId($instanceId)
        ->setInstance($instance)
    );

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

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

Note: The old client library interface code samples for PHP are archived in GitHub.

Python

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

def create_instance(instance_id):
    """Creates an instance."""
    from google.cloud.spanner_admin_instance_v1.types import \
        spanner_instance_admin

    spanner_client = spanner.Client()

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

    operation = spanner_client.instance_admin_api.create_instance(
        parent=spanner_client.project_name,
        instance_id=instance_id,
        instance=spanner_instance_admin.Instance(
            config=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())),
            },
            edition=spanner_instance_admin.Instance.Edition.STANDARD,  # Optional
        ),
    )

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

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

Note: The old client library interface code samples for Python are archived in GitHub.

Ruby

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# instance_config_id = "Your Spanner InstanceConfig 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: instance_config_id

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 upgrade the edition of your instance, and change an instance's display name and compute capacity. You can't change the instance ID or instance configuration (however, you can move your instance).

Upgrade the edition

You can upgrade your Standard edition instances to a higher-tier edition. Standard edition instances can be upgraded to the Enterprise edition or Enterprise Plus edition. Enterprise edition instances can be upgraded to the Enterprise Plus edition.

Self-service downgrade isn't available. To downgrade the edition of your instance, file a support ticket. For more information, see the Spanner editions FAQs.

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

3. Click Upgrade next to the edition type.

4. In the Edition instance page, and under Update edition, select the new higher-tier edition for your instance.

5. Click Save.

gcloud

Use the gcloud spanner instances update command to upgrade your instance's edition:

gcloud spanner instances update INSTANCE_ID --edition=EDITION \
[--async]

Replace the following:

• INSTANCE_ID: the permanent identifier for the instance.
• EDITION: specify the new higher-tier edition for your instance. For more information, see the Spanner editions overview.

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 running gcloud spanner operations describe.

Go

import (
	"context"
	"fmt"
	"io"

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

func updateInstance(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()

	req := &instancepb.UpdateInstanceRequest{
		Instance: &instancepb.Instance{
			Name: fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID),
			// The edition selected for this instance.
			// Different editions provide different capabilities at different price points.
			// For more information, see https://cloud.google.com/spanner/docs/editions-overview.
			Edition: instancepb.Instance_ENTERPRISE,
		},
		FieldMask: &field_mask.FieldMask{
			Paths: []string{"edition"},
		},
	}
	op, err := instanceAdmin.UpdateInstance(ctx, req)
	if err != nil {
		return fmt.Errorf("could not update instance %s: %w", fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID), err)
	}
	// Wait for the instance update to finish.
	_, err = op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for instance update to finish failed: %w", err)
	}

	fmt.Fprintf(w, "Updated instance [%s]\n", instanceID)
	return nil
}

Java

import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.cloud.spanner.admin.instance.v1.InstanceAdminClient;
import com.google.common.collect.Lists;
import com.google.protobuf.FieldMask;
import com.google.spanner.admin.instance.v1.Instance;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.InstanceName;
import com.google.spanner.admin.instance.v1.UpdateInstanceRequest;
import java.util.concurrent.ExecutionException;

public class UpdateInstanceExample {

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

  static void updateInstance(String projectId, String instanceId) {
    // Set Instance configuration.
    int nodeCount = 2;
    String displayName = "Updated name";

    // Update an Instance object that will be used to update the instance.
    Instance instance =
        Instance.newBuilder()
            .setName(InstanceName.of(projectId, instanceId).toString())
            .setDisplayName(displayName)
            .setNodeCount(nodeCount)
            .setEdition(Instance.Edition.ENTERPRISE)
            .setConfig(InstanceConfigName.of(projectId, "regional-us-east4").toString())
            .build();

    try (Spanner spanner =
            SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
        InstanceAdminClient instanceAdminClient = spanner.createInstanceAdminClient()) {

      // Wait for the updatedInstance operation to finish.
      Instance updatedInstance =
          instanceAdminClient
              .updateInstanceAsync(
                  UpdateInstanceRequest.newBuilder()
                      .setFieldMask(
                          FieldMask.newBuilder().addAllPaths(Lists.newArrayList("edition")))
                      .setInstance(instance)
                      .build())
              .get();
      System.out.printf("Instance %s was successfully updated%n", updatedInstance.getName());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Updating instance %s failed with error message %s%n",
          instance.getName(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println("Error: Waiting for updateInstance operation to finish was interrupted");
    }
  }
}

Node.js

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

// Imports the Google Cloud client library
const {Spanner, protos} = 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 instanceAdminClient = spanner.getInstanceAdminClient();

// Updates an instance
try {
  console.log(
    `Updating instance ${instanceAdminClient.instancePath(
      projectId,
      instanceId
    )}.`
  );
  const [operation] = await instanceAdminClient.updateInstance({
    instance: {
      name: instanceAdminClient.instancePath(projectId, instanceId),
      labels: {
        updated: 'true',
        created: Math.round(Date.now() / 1000).toString(), // current time
      },
      edition:
        protos.google.spanner.admin.instance.v1.Instance.Edition.ENTERPRISE, //optional
    },
    // Field mask specifying fields that should get updated in an Instance
    fieldMask: (protos.google.protobuf.FieldMask = {
      paths: ['labels', 'edition'],
    }),
  });

  console.log(`Waiting for operation on ${instanceId} to complete...`);
  await operation.promise();
  console.log(`Updated instance ${instanceId}.`);
  const [metadata] = await instanceAdminClient.getInstance({
    name: instanceAdminClient.instancePath(projectId, instanceId),
  });
  console.log(
    `Instance ${instanceId} has been updated with the ${metadata.edition} ` +
      'edition.'
  );
} catch (err) {
  console.error('ERROR:', err);
}

Python

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

To authenticate to Spanner, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

def update_instance(instance_id):
    """Updates an instance."""
    from google.cloud.spanner_admin_instance_v1.types import \
        spanner_instance_admin

    spanner_client = spanner.Client()

    name = "{}/instances/{}".format(spanner_client.project_name, instance_id)

    operation = spanner_client.instance_admin_api.update_instance(
        instance=spanner_instance_admin.Instance(
            name=name,
            labels={
                "sample_name": "snippets-update_instance-explicit",
            },
            edition=spanner_instance_admin.Instance.Edition.ENTERPRISE,  # Optional
        ),
        field_mask=field_mask_pb2.FieldMask(paths=["labels", "edition"]),
    )

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

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

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

Replace the following:

• 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 can't 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 wouldn't be able to manage the splits after removing compute capacity.

In the latter case, you might try reducing the compute capacity by progressively smaller amounts until you find the minimum capacity that 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, Spanner might 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 under 65% for regional instances and 45% for each region in multi-region instances. You might 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. The time it takes for the increase request to complete depends on the size of the request. In most cases, requests complete within a few minutes. On rare occasions, a scale up might take up to an hour to complete.

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 of nodes or processing units.

gcloud spanner instances update INSTANCE_ID --nodes=NODE_COUNT
[--async]

or

gcloud spanner instances update INSTANCE_ID
--processing-units=PROCESSING_UNIT_COUNT [--async]

Replace the following:

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

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 running gcloud spanner operations describe.

Enable or modify managed autoscaler on an instance

Preview — Managed autoscaler

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

The following limitations apply when you add or change the managed autoscaling feature on an existing instance:

• Managed autoscaler is only available in the Enterprise edition or Enterprise Plus edition.
• You can't enable the managed autoscaler on an instance that you are moving.

• You can't move an instance while the managed autoscaler is enabled.

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 enable the managed autoscaler on.

3. Click Edit instance.

4. Under Configure compute capacity, click Autoscaling.

5. For Minimum, select the minimum limit to use when scaling down. For more information, see Determine the minimum limit.

6. For Maximum, select the maximum limit to use when scaling up. For more information, see Determine the maximum limit.

7. For High priority CPU utilization target, select the percentage of high priority CPU to use. For more information, see Determine the CPU utilization target.

8. For Storage utilization target, select the percentage of storage to use. For more information, see Determine the storage utilization target.

9. Click Save.

gcloud

Use the gcloud beta spanner instances update command to add the managed autoscaler to an instance. For more information and limitations, see Google Cloud CLI flags and limitations.

You can add the managed autoscaler with the following command:

  gcloud beta spanner instances update INSTANCE_ID \
    --autoscaling-min-processing-units=MINIMUM_PROCESSING_UNITS \
    --autoscaling-max-processing-units=MAXIMUM_PROCESSING_UNITS \
    --autoscaling-high-priority-cpu-target=CPU_PERCENTAGE \
    --autoscaling-storage-target=STORAGE_PERCENTAGE

or

  gcloud beta spanner instances update INSTANCE_ID \
    --autoscaling-min-processing-units=MINIMUM_NODES \
    --autoscaling-max-processing-units=MAXIMUM_NODES \
    --autoscaling-high-priority-cpu-target=CPU_PERCENTAGE \
    --autoscaling-storage-target=STORAGE_PERCENTAGE

Replace the following:

• INSTANCE_ID: the permanent identifier for the instance.
• MINIMUM_PROCESSING_UNITS, MINIMUM_NODES: the minimum number of processing units or nodes to use when scaling down. For more information, see Determine the minimum limit.
• MAXIMUM_PROCESSING_UNITS, MAXIMUM_NODES: the maximum number of processing units or nodes to use when scaling up. For more information, see Determine the maximum limit.
• CPU_PERCENTAGE: the target percentage of high priority CPU to use, from 10% to 90%. If you're optimizing for cost and don't require low latency on all requests, then use a higher percentage. For more information, see Determine the CPU utilization target.
• STORAGE_PERCENTAGE: the target percentage of storage to use, from 10% to 99%. For more information, see Determine the Storage Utilization Target.

After you add the managed autoscaler to an instance, you can also modify the managed autoscaler settings. For example, if you want to increase the maximum number of processing units to 10000, run the following command:

gcloud beta spanner instances update test-instance \
     --autoscaling-max-processing-units=10000

Change an instance from using managed autoscaler to manual scaling

Preview — Managed autoscaling

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

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 disable managed autoscaler on.

3. Under Choose a scaling mode, click Manual allocation.

4. Click Save.

gcloud

Use the gcloud beta spanner instances update command to update the instance.

Use the following command to change an instance from using the managed autoscaler to manual scaling:

  gcloud beta spanner instances update INSTANCE_ID \
  --processing-units=PROCESSING_UNIT_COUNT

or

  gcloud beta spanner instances update INSTANCE_ID \
  --nodes=NODE_COUNT

Replace the following:

• 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

Note: You can't move an instance that has managed autoscaler enabled.

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 can't create another free trial instance once you've deleted your first free trial instance. You can create one free trial instance per project lifecycle.

You can delete an instance with the Google Cloud console or the Google Cloud CLI.

If you want to delete an instance that has one or more databases with deletion protection enabled, you must first disable the deletion protection on all databases in that instance before you can delete the instance.

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 Identity and Access Management roles for the instance and its databases.
• Understand how to design a Spanner schema.