インスタンス パーティションの作成と管理

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

始める前に

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

コンソール

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

    インスタンス

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

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

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

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

  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 データベースの永続的な ID。
  • INSTANCE_ID: Spanner インスタンスの永続的な ID。

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 データベースの永続的な ID。
  • INSTANCE_ID: Spanner インスタンスの永続的な ID。

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

コンソール

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

    Spanner に移動

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

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

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

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

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

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

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

    • 小規模なインスタンス パーティションの場合: 処理ユニット
    • 大規模なインスタンスの場合: ノード。1 ノードは 1,000 個の処理ユニットに相当します。

  9. 選択したユニットの値を入力します。

    インスタンス パーティションには、少なくとも 1 つのノードまたは 1,000 個の処理ユニットが必要です。

  10. [作成] をクリックしてインスタンス パーティションを作成します。

gcloud

インスタンス パーティションを作成するには、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]

次のように置き換えます。

  • INSTANCE_PARTITION_ID: Google Cloud プロジェクト内で一意の永続的なインスタンス パーティション ID。インスタンス パーティション ID を後で変更することはできません。
  • INSTANCE_PARTITION_CONFIG: インスタンス パーティション構成の永続的な ID。インスタンス パーティションの地理的位置を定義し、データの保存場所に影響します。
  • INSTANCE_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

次のように置き換えます。

  • INSTANCE_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. コンピューティング容量を変更するには、測定単位（処理ユニットまたはノード）を選択し、数量を入力します。処理ユニットを使用する場合は、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 INSTANCE_PARTITION_ID /
  --instance=INSTANCE_ID /
  [--nodes=NODE_COUNT | --processing-units=PROCESSING_UNIT_COUNT]
  [--async]

次のように置き換えます。

  • INSTANCE_PARTITION_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 を実行します。

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

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

コンソール

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

    Spanner に移動

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

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

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

  5. 手順に沿ってパーティションの削除を確認します。

  6. [削除] をクリックします。

gcloud

gcloud beta spanner instance-partitions delete コマンドを使用します。

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

次のステップ