パーティションを作成、管理する

プレビュー — Geo-partitioning

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

PostgreSQL Interface に関する注: 地域別パーティション分割のプレビュー リリースは、Spanner 用の PostgreSQL インターフェースをサポートしていません。

注: この機能は、Spanner Enterprise Plus エディションで利用できます。詳細については、Spanner エディションの概要をご覧ください。

このページでは、Spanner のパーティションを作成して管理する方法について説明します。

始める前に

パーティションを使用するには、空のデータベースに opt_in_dataplacement_preview データベース オプションを設定する必要があります。

コンソール

1. Google Cloud コンソールの [インスタンス] ページに移動します。

   Instances

2. パーティションを追加するインスタンスを選択します。

3. データをパーティショニングする空のデータベースを選択します。

4. ナビゲーション メニューで [Spanner Studio] をクリックします。

5. [Spanner Studio] ページで、 [新しいタブ] をクリックするか、空のエディタタブを使用します。

6. 次の ALTER DATABASE DDL ステートメントを入力します。

   ALTER DATABASE DATABASE_ID SET OPTIONS (opt_in_dataplacement_preview = true);
   

   DATABASE_ID は、データベースの一意の識別子に置き換えます。

7. [実行] をクリックします。

gcloud

opt_in_dataplacement_preview データベース オプションを設定するには、gcloud spanner databases ddl update を使用します。

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

以下のように置き換えます。

• DATABASE_ID: Spanner データベースの永続的な識別子。
• INSTANCE_ID: Spanner インスタンスの永続的な識別子。

パーティションを作成する

Console

1. Google Cloud コンソールで、[Spanner] ページを開きます。

   Spanner に移動

2. パーティションを追加するインスタンスを選択します。

3. ナビゲーション メニューで [パーティション] を選択します。

4. [パーティションを作成] をクリックします。

5. パーティションを永続的に識別するためのパーティション ID を入力します。パーティション ID も Google Cloud プロジェクト内で一意にする必要があります。パーティション ID は後で変更できません。

6. [構成を選択] セクションで、[リージョン] または [マルチリージョン] を選択します。または、リージョン間で仕様を比較する場合は、[リージョン構成の比較] をクリックします。

7. プルダウン メニューから構成を選択します。

8. [コンピューティング容量を割り当てる] セクションの [単位] で、次のいずれかをクリックします。

   • 小規模なインスタンス パーティションの処理ユニット。
   • 大規模なインスタンスなら [Nodes]。ノードは 1,000 処理ユニットです。

9. 選択した単位の値を入力します。

   パーティションには、少なくとも 1 つのノードまたは 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。パーティション ID を後で変更することはできません。
• PARTITION_CONFIG: パーティション構成の永続的な ID。パーティションの地理的位置を定義し、データの保存場所に影響します。
• PARTITION_DESCRIPTION: Google Cloud コンソールに表示されるパーティションの名前。パーティション名は、Google Cloud プロジェクト内で一意である必要があります。
• INSTANCE_ID: このパーティションが存在する Spanner インスタンスの永続的な ID。
• NODE_COUNT: ノード数で表されるパーティションのコンピューティング容量。1 ノードは 1,000 処理ユニットに相当します。
• PROCESSING_UNIT_COUNT: 処理ユニット数で表されるインスタンスのコンピューティング容量。パーティションには少なくとも 1,000 個の処理ユニットが必要です。数量は 1,000 の倍数（1,000、2,000、3,000 など）で入力します。

たとえば、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: パーティションの永続的な ID。
• INSTANCE_ID: インスタンスの永続的な識別子。

たとえば、パーティション europe-partition の説明を取得するには、次のコマンドを実行します。

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

パーティションを一覧表示する

Console

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 によって、各パーティションの ID、表示名、構成、コンピューティング容量とともに Spanner パーティションの一覧が出力されます。

パーティションを編集する

次のセクションでは、パーティションのコンピューティング容量を変更する方法について説明します。パーティション ID、名前、構成は変更できません。

コンピューティング容量を変更する

CPU 使用率とストレージ使用率が推奨最大値を超えないように、十分なコンピューティング容量をプロビジョニングする必要があります。詳細については、Spanner の割り当てと上限をご覧ください。

パーティションのコンピューティング容量を増やすには、コンピューティング容量を追加するだけの十分な割り当てが Google Cloud プロジェクトに必要です。増加リクエストが完了するまでの時間は、リクエストのサイズによって異なります。ほとんどの場合、リクエストは数分以内に完了します。まれに、スケールアップが完了するまでに最大 1 時間かかることがあります。

Console

1. Google Cloud コンソールで、[Spanner] ページを開きます。

   Spanner に移動

2. リストからインスタンスを選択します。

3. ナビゲーション メニューで [パーティション] を選択します。

4. パーティションのリストで、[操作] 列の [その他の操作] をクリックし、[編集] を選択します。

5. コンピューティング容量を変更するには、測定単位（処理ユニットまたはノード）を選択し、数量を入力します。処理単位を使用する場合は、1,000 の倍数（1,000、2,000、3,000 など）で数量を入力します。各ノードは 1,000 の処理ユニットに相当します。

   パーティションには、少なくとも 1 つのノード（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: パーティションの永続的な ID。
• INSTANCE_ID: インスタンスの永続的な識別子。
• NODE_COUNT: ノード数で表されるパーティションの新しいコンピューティング容量。1 ノードは 1,000 処理ユニットに相当します。
• PROCESSING_UNIT_COUNT: パーティションの新しいコンピューティング容量（処理単位数で表されます）。パーティションには 1,000 以上の処理ユニットが必要です。数量は 1,000 の倍数（1,000、2,000、3,000 など）で入力します。

オプションのフラグ:

• --async: このフラグは、処理中のオペレーションの完了を待たずに、リクエストをすぐに返す場合に使用します。

リクエストのステータスを確認するには、gcloud spanner operations describe を実行します。

パーティションを削除する

プレースメントまたはデータに関連付けられているパーティションは削除できません。パーティションを削除する前に、まずパーティション内のデータの移動を行うか、パーティションを使用するプレースメント テーブルを削除する必要があります。

Console

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

次のステップ

• プレースメント テーブルとキーを作成、管理する方法を学習する。