创建和管理分区

预览 — Geo-partitioning

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

注意：此功能适用于 Spanner 企业 Plus 版。如需了解详情，请参阅 Spanner 版本概览。

本页介绍了如何创建和管理 Spanner 分区。

准备工作

如需使用分区，您必须在空数据库中设置 opt_in_dataplacement_preview 数据库选项：

控制台

1. 前往 Google Cloud 控制台中的实例页面。

   实例

2. 选择要添加分区的实例。

3. 选择要对数据进行分区划分的空数据库。

4. 在导航菜单中，点击 Spanner Studio。

5. 在 Spanner Studio 页面中，点击 New tab（新建标签页），或使用空白编辑器标签页。

6. 输入以下 ALTER DATABASE DDL 语句。

   GoogleSQL

   ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);
   

   将 DATABASE_ID 替换为数据库的唯一标识符。

   PostgreSQL

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

   将 DATABASE_ID 替换为数据库的唯一标识符。

7. 点击运行。

gcloud

如需设置 opt_in_dataplacement_preview 数据库选项，请使用 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);"

替换以下内容：

• DATABASE_ID：Spanner 数据库的永久标识符。
• INSTANCE_ID：Spanner 实例的永久标识符。

PostgreSQL

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

替换以下内容：

• DATABASE_ID：Spanner 数据库的永久标识符。
• INSTANCE_ID：Spanner 实例的永久标识符。

创建分区

控制台

1. 在 Google Cloud 控制台中，打开 Spanner 页面。

   转到 Spanner

2. 选择要添加分区的实例。

3. 在导航菜单中，选择分区。

4. 点击创建分区。

5. 输入分区 ID 以永久标识您的分区。分区 ID 在您的 Google Cloud 项目中也必须是唯一的。分区 ID 创建后便无法更改。

6. 在选择配置部分中，选择单区域或多区域。或者，如果您想比较不同区域的规范，请点击区域。

7. 从下拉菜单中选择一个配置。

8. 在分配计算容量部分，点击“单元”下方的以下任一选项：

   • 适用于小型实例分区的处理单元。
   • 大型实例的节点数。一个节点等于 1,000 个处理单元。

9. 为所选单位输入值。

   您的分区必须至少包含一个节点或 1,000 个处理单元。

10. 点击创建以创建分区。

gcloud

如需创建分区，请使用 gcloud beta spanner instance-partitions create。

gcloud beta spanner instance-partitions create PARTITION_ID \
  --config=PARTITION_CONFIG \
  --description="PARTITION_DESCRIPTION" \
  --instance=INSTANCE_ID \
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]

替换以下内容：

• PARTITION_ID：在您的 Google Cloud 项目中唯一的永久分区标识符。分区 ID 创建后便无法更改。
• PARTITION_CONFIG：分区配置的永久标识符，用于定义分区的地理位置，并会影响数据的存储位置。
• PARTITION_DESCRIPTION： Google Cloud 控制台中显示的分区名称。分区名称在您的 Google Cloud 项目中必须是唯一的。
• INSTANCE_ID：此分区所在的 Spanner 实例的永久性标识符。
• NODE_COUNT：分区的计算容量，以节点数表示。一个节点等于 1,000 个处理单元。
• PROCESSING_UNIT_COUNT：实例的计算容量，以处理单元数表示。您的分区必须至少有 1,000 个处理单元。以 1000 的倍数（1000、2000、3000 等）输入数量。

例如，如需在 eur3 中创建包含 5 个节点的分区 europe-partition，请运行以下命令：

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

客户端库

C++

如需了解如何安装和使用 Spanner 客户端库，请参阅 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#

如需了解如何安装和使用 Spanner 客户端库，请参阅 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

如需了解如何安装和使用 Spanner 客户端库，请参阅 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

如需了解如何安装和使用 Spanner 客户端库，请参阅 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

如需了解如何安装和使用 Spanner 客户端库，请参阅 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

如需了解如何安装和使用 Spanner 客户端库，请参阅 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

如需了解如何安装和使用 Spanner 客户端库，请参阅 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))

描述分区

gcloud

如需描述分区，请使用 gcloud beta spanner instance-partitions describe。

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

替换以下内容：

• PARTITION_ID：分区的永久标识符。
• INSTANCE_ID：实例的永久性标识符。

例如，如需描述分区 europe-partition，请运行以下命令：

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

列出分区

控制台

1. 在 Google Cloud 控制台中，打开 Spanner 页面。

   转到 Spanner

2. 从列表中选择一个实例。

3. 在导航菜单中，选择分区。

   系统会显示与该实例关联的分区列表。

gcloud

如需列出分区，请使用 gcloud beta spanner instance-partitions list。

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

gcloud CLI 会输出 Spanner 分区的列表，以及每个分区的 ID、显示名称、配置和计算容量。

修改分区

以下部分介绍了如何更改分区的计算容量。您无法更改分区 ID、名称或配置。

更改计算容量

您必须预配足够的计算容量，以将 CPU 利用率和存储空间利用率保持在建议的最大值以下。如需了解详情，请参阅 Spanner 的配额和限制。

如果您想增加分区的计算容量，您的Google Cloud 项目必须具有足够的配额才能添加计算容量。增加请求的处理时间取决于请求的大小。在大多数情况下，请求会在几分钟内完成。在极少数情况下，扩容最多可能需要 1 小时才能完成。

控制台

1. 在 Google Cloud 控制台中，打开 Spanner 页面。

   转到 Spanner

2. 从列表中选择一个实例。

3. 在导航菜单中，选择分区。

4. 在分区列表中，点击操作列下的更多操作，然后选择修改。

5. 选择度量单位（处理单元或节点），然后输入数量，以更改计算容量。使用处理单元时，请以 1000 的倍数（1000、2000、3000 等）输入数量。每个节点等于 1000 个处理单元。

   您的分区必须至少包含一个节点（1,000 个处理单元）。

6. 点击保存。

   如果系统对话框提示您没有足够的配额来添加计算容量，请按照说明请求更高配额。

gcloud

如需更改分区的计算容量，请使用 gcloud beta spanner instance-partitions update。使用此命令时，请以节点数或处理单元数的形式指定计算容量。

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

替换以下内容：

• PARTITION_ID：分区的永久标识符。
• INSTANCE_ID：实例的永久性标识符。
• NODE_COUNT：分区的新计算容量，以节点数表示。一个节点等于 1,000 个处理单元。
• PROCESSING_UNIT_COUNT：分区的新计算容量，以处理单元数表示。分区必须至少有 1,000 个处理单元。以 1000 的倍数（1000、2000、3000 等）输入数量。

可选标志：

• --async：如果您希望请求立即返回，而不等待正在进行的操作完成，请使用此标志。

您可以运行 gcloud spanner operations describe 来检查请求的状态。

删除分区

如果分区与任何展示位置或数据相关联，则无法将其删除。您必须先移出分区中的所有数据或删除使用该分区的展示位置表，然后才能删除该分区。

控制台

1. 在 Google Cloud 控制台中，打开 Spanner 页面。

   转到 Spanner

2. 从列表中选择一个实例。

3. 在导航菜单中，选择分区。

4. 在分区列表中，点击“操作”列下的更多操作，然后选择删除。

5. 按照说明操作，确认您要删除分区。

6. 点击删除。

gcloud

使用 gcloud beta spanner instance-partitions delete 命令。

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

后续步骤

• 了解如何创建和管理展示位置表和键。