파티션 만들기 및 관리

미리보기 — Geo-partitioning

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

참고: Spanner Enterprise Plus 버전에서 이 기능을 사용할 수 있습니다. 자세한 내용은 Spanner 버전 개요를 참조하세요.

이 페이지에서는 Spanner 파티션을 만들고 관리하는 방법을 설명합니다.

시작하기 전에

파티션을 사용하려면 빈 데이터베이스에서 opt_in_dataplacement_preview 데이터베이스 옵션을 설정해야 합니다.

콘솔

1. Google Cloud 콘솔에서 인스턴스 페이지로 이동합니다.

   인스턴스

2. 파티션을 추가할 인스턴스를 선택합니다.

3. 데이터를 파티션을 나눌 빈 데이터베이스를 선택합니다.

4. 탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.

5. Spanner 스튜디오 페이지에서 새 탭을 클릭하거나 비어 있는 편집기 탭을 사용합니다.

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개 또는 처리 단위 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개는 처리 단위 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
}

자바

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. 측정 단위(처리 단위 또는 노드)를 선택한 후 수량을 입력하여 컴퓨팅 용량을 변경합니다. 처리 단위를 사용하는 경우 수량을 1,000의 배수(1,000, 2,000, 3,000 등)로 입력합니다. 노드 1개는 처리 단위 1,000개와 같습니다.

   파티션에 노드(처리 단위 1,000개)가 1개 이상 있어야 합니다.

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개는 처리 단위 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 PARTITION_ID
  --instance=INSTANCE_ID

다음 단계

• 배치 테이블 및 키를 만들고 관리하는 방법 알아보기