이 페이지는 Cloud Translation API를 통해 번역되었습니다.

로컬에서 Spanner 에뮬레이션

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

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

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

제한사항 및 차이점

에뮬레이터는 다음을 지원하지 않습니다.

TLS/HTTPS, 인증, ID 및 액세스 관리, 권한, 역할
PLAN 또는 PROFILE 쿼리 모드에서는 반환되는 쿼리 계획이 비어 있습니다.
ANALYZE 문. 에뮬레이터는 이를 수락하지만 무시합니다.
감사 로깅 및 모니터링 도구

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

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

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

에뮬레이터 실행 옵션

에뮬레이터를 실행하는 일반적인 방법에는 두 가지가 있습니다.

gcloud CLI
Docker

애플리케이션 개발 및 테스트 워크플로에 적합한 방법을 선택합니다.

gcloud CLI용 에뮬레이터 설정

Windows 및 macOS 사용자의 경우 에뮬레이터를 설치하기 전에 다음을 실행합니다.

워크스테이션에 gcloud CLI 구성요소를 설치합니다.
```
gcloud components install
```
gcloud CLI가 이미 설치되어 있으면 다음 명령어를 실행하여 모든 구성요소가 업데이트되었는지 확인합니다.
```
gcloud components update
```

gcloud CLI를 사용하여 에뮬레이터 만들기 및 구성

에뮬레이터를 gcloud CLI와 함께 사용하려면 인증을 사용 중지하고 엔드포인트를 재정의해야 합니다. 에뮬레이터와 프로덕션 서비스 간에 빠르게 전환할 수 있도록 gcloud CLI 구성을 별도로 만드는 것이 좋습니다.

에뮬레이터 구성을 만들고 활성화합니다.

  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 CLI 명령어가 프로덕션 서비스 대신 에뮬레이터로 전송됩니다. 에뮬레이터의 인스턴스 구성으로 인스턴스를 만들어서 이를 확인할 수 있습니다.

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

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

gcloud config configurations activate [emulator | default]

gcloud CLI를 사용하여 에뮬레이터를 시작합니다.

Docker에 에뮬레이터 설치

시스템에 Docker를 설치하고 시스템 경로에서 사용할 수 있도록 합니다.

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

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

Docker에서 에뮬레이터를 실행합니다.
```
docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator
```
이 명령어는 에뮬레이터를 실행하고 컨테이너의 포트를 로컬 호스트에 있는 동일한 포트에 매핑합니다. 에뮬레이터는 gRPC 요청의 경우 localhost:9010, REST 요청의 경우 localhost:9020라는 두 가지 로컬 엔드포인트를 사용합니다.
gcloud CLI를 사용하여 에뮬레이터를 시작합니다.

gcloud CLI를 사용하여 에뮬레이터 시작

gcloud emulators spanner 명령어를 사용하여 에뮬레이터를 시작합니다.

gcloud emulators spanner start

에뮬레이터는 두 개의 로컬 엔드포인트를 사용합니다.

gRPC 요청의 localhost:9010
localhost:9020: REST 요청

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

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"
};