로컬에서 Spanner 에뮬레이션

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

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

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

제한사항 및 차이점

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

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

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

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

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

에뮬레이터 설치 및 실행

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

gcloud CLI

gcloud CLI를 설치합니다.
Windows 및 MacOS 사용자의 경우 에뮬레이터를 사용하려면 시스템에 Docker를 설치하고 시스템 경로에서 사용할 수 있어야 합니다.
최신 버전을 가져오도록 gcloud를 업데이트합니다.
```
gcloud components update
```
에뮬레이터를 시작합니다.
```
gcloud emulators spanner start
```
에뮬레이터가 이미 설치되지 않은 경우 에뮬레이터의 바이너리를 다운로드하여 설치하라는 메시지가 나타납니다.

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

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

Docker

Docker가 시스템에 설치되었고 시스템 경로에서 사용할 수 있는지 확인합니다.

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

docker pull gcr.io/cloud-spanner-emulator/emulator

에뮬레이터를 시작합니다.
```
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++으로 시작하기
C#으로 시작하기. 연결 문자열 옵션을 설정해야 합니다. C#에 대한 추가 안내를 참조하세요.
Go로 시작하기
자바로 시작하기
Node.js로 시작하기
PHP로 시작하기
Python으로 시작하기
Ruby로 시작하기

지원되는 버전

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

클라이언트 라이브러리	최소 버전
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"
};