Criar e gerenciar partições de instâncias

Esta página descreve como criar e gerenciar partições de instância do Spanner.

Antes de começar

Para usar partições de instância, defina a opção de banco de dados opt_in_dataplacement_preview no banco de dados vazio:

Console

  1. Acesse a página Instâncias no Google Cloud console.

    Instâncias

  2. Selecione a instância em que você quer adicionar partições.

  3. Selecione o banco de dados vazio em que você quer particionar os dados.

  4. No menu de navegação, clique em Spanner Studio.

  5. Na página Spanner Studio, clique em Nova guia ou use a guia de editor vazia.

  6. Digite a seguinte instrução DDL ALTER DATABASE.

    GoogleSQL

    ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);
    

    Substitua DATABASE_ID pelo identificador exclusivo do seu banco de dados.

    PostgreSQL

    ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE;
    

    Substitua DATABASE_ID pelo identificador exclusivo do seu banco de dados.

  7. Clique em Executar.

gcloud

Para definir a opção de banco de dados opt_in_dataplacement_preview, use gcloud spanner databases ddl update.

GoogleSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);"

Substitua:

  • DATABASE_ID: o identificador permanente do banco de dados do Spanner.
  • INSTANCE_ID: o identificador permanente da sua instância do Spanner.

PostgreSQL

gcloud spanner databases ddl update DATABASE_ID \
  --instance=INSTANCE_ID \
  --ddl="ALTER DATABASE DATABASE_ID SET "spanner.opt_in_dataplacement_preview" = TRUE"

Substitua:

  • DATABASE_ID: o identificador permanente do banco de dados do Spanner.
  • INSTANCE_ID: o identificador permanente da sua instância do Spanner.

Criar uma partição de instância

Console

  1. No console Google Cloud , abra a página Spanner.

    Acessar o Spanner

  2. Selecione a instância em que você quer adicionar partições.

  3. No menu de navegação, selecione Partições de instância.

  4. Clique em Criar partição de instância.

  5. Insira um ID de partição para identificar permanentemente a partição da instância. O ID da partição da instância também precisa ser exclusivo no projeto doGoogle Cloud . Não será possível mudar o ID da partição da instância depois.

  6. Na seção Escolher uma configuração, selecione Regional ou Multirregião. Se você quiser comparar as especificações entre as regiões, clique em Comparar configurações de região.

  7. Selecione uma configuração no menu suspenso.

  8. Na seção Alocar capacidade de computação, em Unidade, clique em uma das seguintes opções:

    • Unidades de processamento para partições de instâncias pequenas.
    • Nós para instâncias grandes. Um nó é igual a 1.000 unidades de processamento.
  9. Insira um valor para a unidade selecionada.

    A partição da instância precisa ter pelo menos um nó ou 1.000 unidades de processamento.

  10. Clique em Criar para criar a partição da instância.

gcloud

Para criar uma partição de instância, use gcloud beta spanner instance-partitions create.

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

Substitua:

  • INSTANCE_PARTITION_ID: o identificador de partição de instância permanente exclusivo do projeto Google Cloud . Não será possível mudar o ID da partição da instância depois.
  • INSTANCE_PARTITION_CONFIG: o identificador permanente da configuração da partição da instância, que define a localização geográfica da partição da instância e afeta onde os dados são armazenados.
  • INSTANCE_PARTITION_DESCRIPTION: o nome a ser exibido para a partição de instância no console Google Cloud . O nome da partição de instância precisa ser exclusivo no projeto Google Cloud .
  • INSTANCE_ID: o identificador permanente da sua instância do Spanner, onde a partição da instância está localizada.
  • NODE_COUNT: a capacidade de computação da partição da instância, expressa como um número de nós. Um nó equivale a 1.000 unidades de processamento.
  • PROCESSING_UNIT_COUNT: a capacidade de computação da instância, expressa como um número de unidades de processamento. A partição da instância precisa ter pelo menos 1.000 unidades de processamento. Insira quantidades em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante).

Por exemplo, para criar uma partição de instância europe-partition em eur3 com cinco nós, execute o seguinte:

  gcloud beta spanner instance-partitions create europe-partition --config=eur3 \
    --description="europe-partition" --instance=test-instance --nodes=5

Bibliotecas de cliente

C++

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

void CreateInstancePartition(
    google::cloud::spanner_admin::InstanceAdminClient client,
    std::string const& project_id, std::string const& instance_id,
    std::string const& instance_partition_id) {
  auto project = google::cloud::Project(project_id);
  auto in = google::cloud::spanner::Instance(project_id, instance_id);
  auto config = project.FullName() + "/instanceConfigs/nam3";

  google::spanner::admin::instance::v1::CreateInstancePartitionRequest request;
  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);

  auto instance_partition = client.CreateInstancePartition(request).get();
  if (!instance_partition) throw std::move(instance_partition).status();
  std::cout << "Created instance partition [" << instance_partition_id << "]:\n"
            << instance_partition->DebugString();
}

C#

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.


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

public class CreateInstancePartitionSample
{
    public InstancePartition CreateInstancePartition(string projectId, string instanceId, string instancePartitionId)
    {
        // Create the InstanceAdminClient instance.
        InstanceAdminClient instanceAdminClient = InstanceAdminClient.Create();

        // Initialize request parameters.
        InstancePartition partition = new InstancePartition
        {
            DisplayName = "This is a display name.",
            NodeCount = 1,
            ConfigAsInstanceConfigName = InstanceConfigName.FromProjectInstanceConfig(projectId, "nam3"),
        };
        InstanceName instanceName = 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}");
            throw completedResponse.Exception;
        }

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

        return completedResponse.Result;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

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.
func createInstancePartition(w io.Writer, projectID, instanceID, instancePartitionID string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance"
	// instancePartitionID := "my-instance-partition"
	ctx := context.Background()
	instanceAdmin, err := instance.NewInstanceAdminClient(ctx)
	if err != nil {
		return err
	}
	defer instanceAdmin.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},
		},
	})
	if err != nil {
		return fmt.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)
	if err != nil {
		return fmt.Errorf("waiting for instance partition creation to finish failed: %w", err)
	}
	// The instance partition may not be ready to serve yet.
	if i.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)
	return nil
}

Java

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.


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.CreateInstancePartitionRequest;
import com.google.spanner.admin.instance.v1.InstanceConfigName;
import com.google.spanner.admin.instance.v1.InstanceName;
import com.google.spanner.admin.instance.v1.InstancePartition;
import java.util.concurrent.ExecutionException;

class CreateInstancePartitionSample {

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

  static void createInstancePartition(
      String projectId, String instanceId, String instancePartitionId) {
    // Set instance partition configuration.
    int nodeCount = 1;
    String displayName = "Descriptive name";

    // Create an InstancePartition object that will be used to create the instance partition.
    InstancePartition instancePartition =
        InstancePartition.newBuilder()
            .setDisplayName(displayName)
            .setNodeCount(nodeCount)
            .setConfig(InstanceConfigName.of(projectId, "nam3").toString())
            .build();

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

      // Wait for the createInstancePartition operation to finish.
      InstancePartition createdInstancePartition =
          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 (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance partition %s failed with error message %s%n",
          instancePartition.getName(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println(
          "Error: Waiting for createInstancePartition operation to finish was interrupted");
    }
  }
}

Node.js

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

// 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';
// const instancePartitionId = 'my-instance-partition';

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

// Get the instance admin client
const instanceAdminClient = spanner.getInstanceAdminClient();

// Creates a new instance partition
try {
  console.log(
    `Creating instance partition ${instanceAdminClient.instancePartitionPath(
      projectId,
      instanceId,
      instancePartitionId,
    )}.`,
  );
  const [operation] = await instanceAdminClient.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...`,
  );
  await operation.promise();

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

PHP

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

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

Para saber como instalar e usar a biblioteca de cliente do Spanner, consulte Bibliotecas de cliente do Spanner.

def create_instance_partition(instance_id, instance_partition_id):
    """Creates an instance partition."""
    from google.cloud.spanner_admin_instance_v1.types import spanner_instance_admin

    spanner_client = spanner.Client()
    instance_admin_api = spanner_client.instance_admin_api

    config_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))

Descrever uma partição de instância

gcloud

Para descrever uma partição de instância, use gcloud beta spanner instance-partitions describe.

gcloud beta spanner instance-partitions describe PARTITION_ID \
  --instance=INSTANCE_ID

Substitua:

  • INSTANCE_PARTITION_ID: o identificador permanente da partição de instância.
  • INSTANCE_ID: o identificador permanente da instância.

Por exemplo, para descrever a partição de instância europe-partition, execute o seguinte:

  gcloud beta spanner instance-partitions describe europe-partition
    --instance=test-instance

Listar partições de instâncias

Console

  1. No console Google Cloud , abra a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista.

  3. No menu de navegação, selecione Partições de instância.

    Uma lista de partições de instância associadas a essa instância é mostrada.

gcloud

Para listar as partições de instância, use gcloud beta spanner instance-partitions list.

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

A CLI gcloud mostra uma lista das partições de instância do Spanner, além do ID, do nome de exibição, da configuração e da capacidade de computação de cada partição.

Editar uma partição de instância

A seção a seguir explica como mudar a capacidade de computação da partição da instância. Não é possível mudar o ID, o nome ou a configuração da partição da instância.

Mudar a capacidade de computação

Provisione capacidade de computação suficiente para manter a utilização da CPU e a utilização de armazenamento abaixo dos valores máximos recomendados. Para mais informações, consulte as cotas e limites do Spanner.

Se você quiser aumentar a capacidade de uma partição de instância, seu projeto doGoogle Cloud precisa ter cota suficiente para adicionar a capacidade de computação. O tempo necessário para concluir a solicitação de aumento depende do tamanho da solicitação. Na maioria dos casos, as solicitações são concluídas em alguns minutos. Em raras ocasiões, uma escalonar verticalmente pode levar até uma hora para ser concluída.

Console

  1. No console Google Cloud , abra a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista.

  3. No menu de navegação, selecione Partições de instância.

  4. Na lista de partições de instância, na coluna Ações, clique em Mais ações e selecione Editar.

  5. Para alterar a capacidade de computação, escolha uma unidade de medida (unidades de processamento ou nós) e insira uma quantidade. Ao usar unidades de processamento, insira quantidades em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante). Cada nó é igual a 1.000 unidades de processamento.

    A partição da instância precisa ter pelo menos um nó (1.000 unidades de processamento).

  6. Clique em Salvar.

    Se for exibida uma caixa de diálogo informando que sua cota é insuficiente para adicionar capacidade de computação , siga as instruções para solicitar uma cota maior.

gcloud

Para mudar a capacidade de computação da partição da instância, use gcloud beta spanner instance-partitions update. Ao usar esse comando, especifique a capacidade de computação como um número de nós ou unidades de processamento.

gcloud beta spanner instance-partitions update INSTANCE_PARTITION_ID /
  --instance=INSTANCE_ID /
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]
  [--async]

Substitua:

  • INSTANCE_PARTITION_ID: o identificador permanente da partição de instância.
  • INSTANCE_ID: o identificador permanente da instância.
  • NODE_COUNT: a nova capacidade de computação da partição de instância, expressa como um número de nós. Um nó equivale a 1.000 unidades de processamento.
  • PROCESSING_UNIT_COUNT: a nova capacidade de computação da partição de instância, expressa como um número de unidades de processamento. A partição da instância precisa ter pelo menos 1.000 unidades de processamento. Insira quantidades em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante).

Sinalizações opcionais:

  • --async: use essa flag se quiser que a solicitação seja retornada imediatamente, sem aguardar a conclusão da operação em andamento.

É possível verificar o status da sua solicitação executando gcloud spanner operations describe.

Excluir uma partição de instância

Não é possível excluir uma partição de instância enquanto ela estiver associada a qualquer posicionamento ou dados. Primeiro, mova todos os dados que estão na partição da instância ou exclua as tabelas de posicionamento que usam a partição da instância antes de excluí-la.

Console

  1. No console Google Cloud , abra a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista.

  3. No menu de navegação, selecione Partições de instância.

  4. Na lista de partições de instância, na coluna Ações, clique em Mais ações e selecione Excluir.

  5. Siga as instruções para confirmar que você quer excluir a partição da instância.

  6. Clique em Excluir.

gcloud

Use o comando gcloud beta spanner instance-partitions delete.

gcloud beta spanner instance-partitions delete INSTANCE_PARTITION_ID
  --instance=INSTANCE_ID

A seguir