gcloud CLI는 Google Cloud 프로젝트나 결제 계정을 만들지 않고도 무료 체험판 인스턴스를 사용하여 애플리케이션을 개발하고 테스트하는 데 사용할 수 있는 로컬 인메모리 에뮬레이터를 제공합니다. 에뮬레이터는 데이터를 메모리에만 저장하므로 데이터, 스키마, 구성을 포함한 모든 상태가 다시 시작 시 손실됩니다. 에뮬레이터는 Spanner 프로덕션 서비스와 동일한 API를 제공하며 프로덕션 배포가 아닌 로컬 개발 및 테스트 용도입니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-06-03(UTC)"],[],[],null,["# Emulate Spanner locally\n\nThe [gcloud CLI](/sdk) provides a local, in-memory emulator, which\nyou can use to develop and test your applications. Because the emulator\nstores data only in memory, all state, including data, schema, and configs, is\nlost on restart. The emulator offers the same APIs as the Spanner\nproduction service and is intended for local development and testing, not for\nproduction deployments.\n\nThe emulator supports both the GoogleSQL and PostgreSQL\ndialects. It supports all languages of the\n[client libraries](#client-libraries). You can also use the emulator with the\n[Google Cloud CLI](/sdk/gcloud) and [REST APIs](/spanner/docs/reference/rest).\n\nThe emulator is also available as an open source project in\n[GitHub](https://github.com/GoogleCloudPlatform/cloud-spanner-emulator).\n| **Note:** To explore Spanner using a 90-day free trial instance, see [Create a Spanner free trial instance](/spanner/docs/free-trial-quickstart).\n\nLimitations and differences\n---------------------------\n\nThe emulator doesn't support the following:\n\n- TLS/HTTPS, authentication, Identity and Access Management, permissions, or roles.\n- In the `PLAN` or `PROFILE` [query modes](/spanner/docs/reference/rest/v1/QueryMode), the query plan that is returned is empty.\n- The [`ANALYZE` statement](/spanner/docs/query-optimizer/overview#construct-statistics-package). The emulator accepts but ignores it.\n- Any of the [audit logging](/spanner/docs/audit-logging) and monitoring tools.\n\nThe emulator also differs from the Spanner production service in\nthe following ways:\n\n- Error messages might not be consistent between the emulator and the production service.\n- Performance and scalability for the emulator is not comparable to the production service.\n- Read-write transactions and schema changes lock the entire database for exclusive access until they are completed.\n- [Partitioned DML](/spanner/docs/dml-partitioned) and [`partitionQuery`](/spanner/docs/reference/rest/v1/projects.instances.databases.sessions/partitionQuery) are supported, but the emulator doesn't check to ensure that statements are [partitionable](/spanner/docs/dml-partitioned#partitionable-idempotent). This means that a partitioned DML or `partitionQuery` statement might run in the emulator, but it might fail in the production service with the non-partitionable statement error.\n\nFor a complete list of APIs and features that are supported, unsupported, and\npartially supported, see the\n[README](https://github.com/GoogleCloudPlatform/cloud-spanner-emulator/blob/master/README.md)\nfile in GitHub.\n\nOptions for running the emulator\n--------------------------------\n\nThere are two common ways to run the emulator:\n\n- [gcloud CLI](#emulator-for-gcloud)\n- [Docker](#install-docker)\n\nChoose the way that is appropriate for your application development and\ntest workflow.\n| **Note:** For more ways to run the emulator, see the [README](https://github.com/GoogleCloudPlatform/cloud-spanner-emulator/blob/master/README.md#quickstart).\n\nSet up the emulator for gcloud CLI\n----------------------------------\n\nFor Windows and macOS users, before installing the emulator, do the following:\n\n- Install the [gcloud CLI](/sdk/install) components on your\n workstation:\n\n gcloud components install cloud-spanner-emulator\n\n If gcloud CLI is already installed, run the following command\n to ensure all of its components are updated: \n\n gcloud components update\n\n### Create and configure the emulator using gcloud CLI\n\nTo use the emulator with gcloud CLI, you must disable\nauthentication and override the endpoint. We recommend creating a separate\n[gcloud CLI configuration](/sdk/docs/configurations) so that you\ncan quickly switch back and forth between the emulator and the production\nservice.\n\n1. Create and activate an emulator configuration:\n\n gcloud config configurations create emulator\n gcloud config set auth/disable_credentials true\n gcloud config set project your-project-id\n gcloud config set api_endpoint_overrides/spanner http://localhost:9020/\n\n Once configured, your gcloud CLI commands are sent to the emulator\n instead of the production service. You can verify this by creating an instance\n with the emulator's instance config: \n\n gcloud spanner instances create test-instance \\\n --config=emulator-config --description=\"Test Instance\" --nodes=1\n\n To switch between the emulator and default configuration, run: \n\n gcloud config configurations activate [emulator | default]\n\n2. Start the emulator using [gcloud CLI](#start-emulator-gcloud).\n\nInstall the emulator in Docker\n------------------------------\n\n1. Install [Docker](https://www.docker.com/products/docker-desktop) on your\n system and make it available on the system path.\n\n2. Get the latest emulator image:\n\n docker pull gcr.io/cloud-spanner-emulator/emulator\n\n3. Run the emulator in Docker:\n\n docker run -p 9010:9010 -p 9020:9020 gcr.io/cloud-spanner-emulator/emulator\n\n This command runs the emulator and maps the ports in the container to the\n same ports on your local host. The emulator uses two local endpoints:\n `localhost:9010` for gRPC requests and `localhost:9020` for REST requests.\n4. Start the emulator using [gcloud CLI](#start-emulator-gcloud).\n\nStart the emulator using gcloud CLI\n-----------------------------------\n\nStart the emulator using the\n[gcloud emulators spanner](/sdk/gcloud/reference/emulators/spanner/start)\ncommand: \n\n gcloud emulators spanner start\n\nThe emulator uses two local endpoints:\n\n- `localhost:9010` for gRPC requests\n- `localhost:9020` for REST requests\n\nUse the client libraries with the emulator\n------------------------------------------\n\nYou can use [supported versions](#supported-versions) of the client libraries\nwith the emulator by setting the `SPANNER_EMULATOR_HOST` environment variable.\nThere are many ways to do this. For example:\n**Important:** If you are using C#, see the [additional instructions for C#](#cs). \n\n### Linux/macOS\n\n export SPANNER_EMULATOR_HOST=localhost:9010\n\n### Windows\n\n set SPANNER_EMULATOR_HOST=localhost:9010\n\nOr with [gcloud env-init](/sdk/gcloud/reference/emulators/spanner/env-init): \n\n### Linux/macOS\n\n $(gcloud emulators spanner env-init)\n\n### Windows\n\n gcloud emulators spanner env-init \u003e set_vars.cmd && set_vars.cmd\n\nWhen your application starts, the client library automatically checks for\n`SPANNER_EMULATOR_HOST` and connects to the emulator if it's running.\n\nOnce `SPANNER_EMULATOR_HOST` is set, you can test the emulator by following the\nGetting Started guides. Ignore the instructions related to project\ncreation, authentication, and credentials since these aren't needed to use the\nemulator.\n\n- [Getting Started in C++](/spanner/docs/getting-started/cpp)\n\n- [Getting Started in C#](/spanner/docs/getting-started/csharp). You must set connection string options. See [additional instructions for C#](#cs).\n\n- [Getting Started in Go](/spanner/docs/getting-started/go)\n\n- [Getting Started in Java](/spanner/docs/getting-started/java)\n\n- [Getting Started in Node.js](/spanner/docs/getting-started/nodejs)\n\n- [Getting Started in PHP](/spanner/docs/getting-started/php)\n\n- [Getting Started in Python](/spanner/docs/getting-started/python)\n\n- [Getting Started in Ruby](/spanner/docs/getting-started/ruby)\n\n### Supported versions\n\nThe following table lists the versions of the [client libraries](/spanner/docs/reference/libraries)\nthat support the emulator.\n\n### Additional instructions for C#\n\nFor the C# client library, you must also specify the\n[`emulatordetection`](/dotnet/docs/referenceapi/Google.Api.Gax.EmulatorDetection)\noption in the [connection string](/dotnet/docs/referenceconnection_string).\nUnlike the other client libraries, C# ignores the `SPANNER_EMULATOR_HOST`\nenvironment variable by default. The following is an example for the\nconnection string: \n\n var builder = new SpannerConnectionStringBuilder\n {\n DataSource = $\"projects/{projectId}/instances/{instanceId}/databases/{databaseId}\";\n EmulatorDetection = \"EmulatorOnly\"\n };"]]
