로컬에서 Spanner 에뮬레이션

gcloud CLI는 Google Cloud 프로젝트나 결제 계정을 만들지 않고 무료로 애플리케이션을 개발하고 테스트하는 데 사용할 수 있는 로컬 인메모리 에뮬레이터를 제공합니다. 에뮬레이터는 데이터를 메모리에만 저장하므로 데이터, 스키마, 구성을 포함한 모든 상태가 다시 시작 시 손실됩니다. 에뮬레이터는 Spanner 프로덕션 서비스와 동일한 API를 제공하며, 프로덕션 배포가 아닌 로컬 개발 및 테스트를 대상으로 합니다.

에뮬레이터는 GoogleSQL 및 PostgreSQL 언어 모두 지원합니다. 클라이언트 라이브러리의 모든 언어를 지원합니다. 또한 Google Cloud CLIREST API와 함께 에뮬레이터를 사용할 수 있습니다.

에뮬레이터는 GitHub에서 오픈소스 프로젝트로도 사용할 수 있습니다.

제한사항 및 차이점

이 에뮬레이터에서는 다음 항목이 지원되지 않습니다.

  • TLS/HTTPS, 인증, IAM, 권한, 역할
  • PLAN 또는 PROFILE 쿼리 모드. NORMAL만 지원합니다.
  • ANALYZE. 에뮬레이터는 이를 수락하지만 무시합니다.
  • 감사 로깅 및 모니터링 도구

이 에뮬레이터는 또한 다음과 같이 Spanner 프로덕션 서비스와 구분됩니다.

  • 에뮬레이터와 프로덕션 서비스 간 오류 메시지가 일치하지 않을 수 있습니다.
  • 에뮬레이터의 성능과 확장성은 프로덕션 서비스와 비교할 수 없습니다.
  • 읽기-쓰기 트랜잭션 및 스키마 변경은 완료될 때까지 전체 데이터베이스를 잠가 배타적 액세스로 설정합니다.
  • Partitioned DML파티션 쿼리가 지원되지만 이 에뮬레이터는 해당 문이 파티션을 나눌 수 있는 문인지 확인하지 않습니다. 즉, Partitioned DML 또는 파티션 쿼리 문이 에뮬레이터에서 실행되더라도, 프로덕션 서비스에서 파티션을 나눌 수 없는 문 오류로 실패할 수 있습니다.

지원 여부 또는 부분적 지원 여부를 포함한 API 및 기능의 전체 목록은 GitHub의 README 파일에서 확인하세요.

에뮬레이터 설치 및 실행

에뮬레이터를 실행하는 가장 일반적인 두 가지 방법은 gcloud CLIDocker를 사용하는 것입니다. 애플리케이션 개발 및 테스트 워크플로에 적합한 방법을 선택할 수 있습니다.

gcloud CLI

  1. gcloud CLI를 설치합니다.

  2. Windows 및 MacOS 사용자의 경우 에뮬레이터를 사용하려면 시스템에 Docker를 설치하고 시스템 경로에서 사용할 수 있어야 합니다.

  3. 최신 버전을 가져오도록 gcloud를 업데이트합니다.

    gcloud components update
    
  4. 에뮬레이터를 시작합니다.

    gcloud emulators spanner start
    

    에뮬레이터가 이미 설치되지 않은 경우 에뮬레이터의 바이너리를 다운로드하여 설치하라는 메시지가 나타납니다.

    기본적으로 에뮬레이터는 gRPC 요청의 경우 localhost:9010, REST 요청의 경우 localhost:9020라는 두 가지 로컬 엔드포인트를 호스팅합니다.

    이 명령어에 대한 자세한 내용은 gcloud emulators spanner를 참조하세요.

Docker

  1. Docker가 시스템에 설치되어 있고 시스템 경로에서 사용 가능한지 확인합니다.

  2. 최신 에뮬레이터 이미지를 가져옵니다.

    docker pull gcr.io/cloud-spanner-emulator/emulator
    
  3. 에뮬레이터를 시작합니다.

    docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator
    

    이 명령어는 에뮬레이터를 실행하고 컨테이너의 포트를 로컬 호스트에 있는 동일한 포트에 매핑합니다. 로컬 엔드포인트에는 gRPC 요청을 위한 localhost:9010과 REST 요청을 위한 localhost:9020이 있습니다.

에뮬레이터와 함께 gcloud CLI 사용

에뮬레이터를 gcloud와 함께 사용하려면 인증을 사용 중지하고 엔드포인트를 재정의해야 합니다.

에뮬레이터와 프로덕션 서비스 간에 빠르게 전환할 수 있도록 gcloud 구성을 별도로 만드는 것이 좋습니다. 에뮬레이터 구성을 만들고 활성화하려면 다음을 실행합니다.

gcloud config configurations create emulator
  gcloud config set auth/disable_credentials true
  gcloud config set project your-project-id
  gcloud config set api_endpoint_overrides/spanner http://localhost:9020/

구성된 다음에는 gcloud 명령어가 프로덕션 서비스 대신 에뮬레이터로 전송됩니다. 에뮬레이터의 인스턴스 구성으로 인스턴스를 만들어서 이를 확인할 수 있습니다.

gcloud spanner instances create test-instance \
   --config=emulator-config --description="Test Instance" --nodes=1

에뮬레이터와 기본 구성 간에 전환하려면 다음을 실행합니다.

gcloud config configurations activate [emulator | default]

에뮬레이터에 클라이언트 라이브러리 사용

SPANNER_EMULATOR_HOST 환경 변수를 설정하여 에뮬레이터에 클라이언트 라이브러리의 지원되는 버전을 사용할 수 있습니다. 지식을 보급하는 방법에는 여러 가지가 있습니다. 예를 들면 다음과 같습니다.

Linux/macOS

export SPANNER_EMULATOR_HOST=localhost:9010

Windows

set SPANNER_EMULATOR_HOST=localhost:9010

다음과 같이 gcloud env-init를 사용할 수도 있습니다.

Linux/macOS

$(gcloud emulators spanner env-init)

Windows

gcloud emulators spanner env-init > set_vars.cmd && set_vars.cmd

애플리케이션이 시작되면 클라이언트 라이브러리는 자동으로 SPANNER_EMULATOR_HOST를 확인하고 실행 중인 에뮬레이터에 연결합니다.

SPANNER_EMULATOR_HOST가 설정된 다음에는 아래의 시작하기 가이드에 따라 에뮬레이터를 테스트할 수 있습니다. 프로젝트 만들기, 인증, 사용자 인증 정보와 관련된 안내는 에뮬레이터를 사용할 때 필요하지 않기 때문에 무시해도 됩니다.

지원되는 버전

다음 표에는 에뮬레이터를 지원하는 클라이언트 라이브러리 버전이 표시되어 있습니다.

클라이언트 라이브러리 최소 버전
C++ v0.9.x+
C# v3.1.0+
Go v1.5.0+
자바 v1.51.0+
Node.js v4.5.0+
PHP v1.25.0+
Python v1.15.0+
Ruby v1.13.0+

C#에 대한 추가 안내

또한 C# 클라이언트 라이브러리의 경우 연결 문자열emulatordetection 옵션을 지정해야 합니다. 다른 클라이언트 라이브러리와 달리 C#은 기본적으로 SPANNER_EMULATOR_HOST 환경 변수를 무시합니다. 방법은 다음과 같습니다.

var builder = new SpannerConnectionStringBuilder
{
    DataSource = $"projects/{projectId}/instances/{instanceId}/databases/{databaseId}";
    EmulatorDetection = "EmulatorOnly"
};