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