Datastore 에뮬레이터 실행

Datastore 에뮬레이터는 프로덕션 Datastore 환경의 로컬 에뮬레이션을 제공합니다. 에뮬레이터를 사용하여 로컬에서 애플리케이션을 개발하고 테스트할 수 있습니다. 또한 에뮬레이터를 사용하면 프로덕션 Datastore 인스턴스의 색인을 생성하고 필요하지 않은 색인을 삭제할 수 있습니다. 이 페이지에서는 에뮬레이터 설치, 에뮬레이터 시작, 애플리케이션을 에뮬레이터에 연결하도록 환경 변수 설정을 설명합니다.

알려진 문제

기본적으로 Datastore 에뮬레이터는 Datastore 모드의 Firestore에 의해 도입된 기능을 에뮬레이션하지 않습니다. 다음 기본 에뮬레이터 동작은 Datastore 모드와 일치하지 않습니다.

  • 에뮬레이터는 기본적으로 eventual consistency를 시뮬레이션합니다. Datastore 모드의 Firestore는 strong consistency를 가집니다.
  • 에뮬레이터는 트랜잭션 내에서 비상위 쿼리를 허용하지 않습니다. Datastore 모드의 Firestore에는 더 이상 이 제한사항이 적용되지 않습니다.
  • 에뮬레이터는 IN, !=, NOT-IN 쿼리를 지원하지 않습니다.
  • 에뮬레이터는 COUNT(*)와 같은 집계 쿼리를 지원하지 않습니다.

하지만 --use-firestore-in-datastore-mode 플래그는 Datastore 모드에서 Firestore에 대한 위의 제한 중 일부를 느슨하게 하는 데 도움이 됩니다.

  • 에뮬레이터는 strong consistency를 갖는 비상위 쿼리를 시뮬레이션합니다.
  • 에뮬레이터는 트랜잭션 내에서 비상위 쿼리를 허용합니다.
  • 에뮬레이터는 트랜잭션에서 25개의 항목 그룹 제한을 삭제합니다.

Datastore 모드로 Firestore를 에뮬레이션하려면 대신 gcloud emulators firestore start --database-mode=datastore-mode를 사용합니다.

시작하기 전에

Datastore 에뮬레이터를 사용하려면 다음이 필요합니다.

에뮬레이터 설치

Datastore 에뮬레이터는 gcloud CLI의 구성요소입니다. gcloud components install 명령어를 사용하여 Datastore 에뮬레이터를 설치합니다.

gcloud components install cloud-datastore-emulator

에뮬레이터 데이터 디렉터리

에뮬레이터는 지정된 데이터 디렉터리에 /WEB-INF/appengine-generated/local_db.bin을 만들고 local_db.bin에 데이터를 저장하여 Datastore를 시뮬레이션합니다. 기본적으로 에뮬레이터는 ~/.config/gcloud/emulators/datastore/ 데이터 디렉터리를 사용합니다. local_db.bin 파일은 에뮬레이터의 각 세션 간에 유지됩니다. 데이터 디렉터리를 여러 개 설정하고 각각의 개별적인 로컬 Datastore 모드 인스턴스로 생각할 수 있습니다. local_db.bin 파일의 콘텐츠를 지우려면 에뮬레이터를 중지하고 수동으로 파일을 삭제합니다.

에뮬레이터 시작

명령어 프롬프트에서 datastore start를 실행하여 에뮬레이터를 시작합니다.

gcloud emulators datastore start [flags]

여기서 [flags]는 gcloud CLI에 제공되는 선택적 명령줄 인수입니다. 예를 들면 다음과 같습니다.

  • --data-dir=[DATA_DIR]는 에뮬레이터의 데이터 디렉터리를 변경합니다. 에뮬레이터는 [DATA_DIR]에 /WEB-INF/appengine-generated/local_db.bin 파일을 만들거나 기존 파일이 있으면 이를 사용합니다.

  • --no-store-on-disk는 에뮬레이터가 에뮬레이터 세션의 데이터를 디스크에 유지하지 않도록 구성합니다.

선택적 플래그의 전체 목록은 gcloud beta emulators datastore start 참조를 확인하세요.

에뮬레이터를 시작한 후에는 다음과 유사한 메시지가 표시됩니다.

...
[datastore] Dev App Server is now running.

에뮬레이터를 중단하려면 명령 프롬프트에 Control-C를 입력합니다.

환경 변수 설정

에뮬레이터를 시작한 후에는 애플리케이션이 프로덕션 Datastore 모드 데이터베이스 대신 에뮬레이터에 연결하도록 환경 변수를 설정해야 합니다. 이러한 환경 변수는 애플리케이션 실행에 사용하는 것과 동일한 머신에서 설정해야 합니다.

에뮬레이터를 시작할 때마다 환경 변수를 설정해야 합니다. 환경 변수는 에뮬레이터를 재시작할 때 변경될 수 있는 동적 할당 포트 번호에 따라 달라집니다.

변수 자동 설정

애플리케이션과 에뮬레이터를 동일한 머신에서 실행하면 환경 변수를 자동으로 설정할 수 있습니다.

Linux/macOS

명령어 치환을 사용하여 env-init를 실행합니다.

$(gcloud beta emulators datastore env-init)

Windows

env-init의 출력을 사용하여 배치 파일을 만들고 실행합니다.

gcloud beta emulators datastore env-init > set_vars.cmd && set_vars.cmd

이제 애플리케이션이 Datastore 에뮬레이터에 연결됩니다.

변수 수동 설정

애플리케이션과 에뮬레이터를 다른 머신에서 실행할 경우 환경 변수를 수동으로 설정합니다.

  1. env-init 명령어를 실행합니다.

    gcloud beta emulators datastore env-init

  2. 애플리케이션을 실행하는 머신에서 환경 변수 및 값을 env-init 명령어의 출력에 따라 설정합니다. 예를 들면 다음과 같습니다.

    Linux/macOS
    export DATASTORE_DATASET=my-project-id
export DATASTORE_EMULATOR_HOST=::1:8432
export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
export DATASTORE_HOST=http://::1:8432
export DATASTORE_PROJECT_ID=my-project-id
    Windows
    set DATASTORE_DATASET=my-project-id
set DATASTORE_EMULATOR_HOST=::1:8432
set DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
set DATASTORE_HOST=http://::1:8432
set DATASTORE_PROJECT_ID=my-project-id

이제 애플리케이션이 Datastore 에뮬레이터에 연결됩니다. 이 명령어로 제공하는 프로젝트 ID와 포트는 위의 예시와 다릅니다.

색인 업데이트 및 삭제

에뮬레이터를 사용하여 애플리케이션을 실행하면 프로덕션 Datastore 모드 데이터베이스의 색인을 생성하고 필요하지 않은 색인을 삭제할 수도 있습니다. gcloud CLI 사용에서 자세히 알아보세요.

환경 변수 삭제

에뮬레이터 사용을 마친 후에는 애플리케이션이 프로덕션 Datastore 모드 데이터베이스에 연결하도록 에뮬레이터를 중지(Control-C)하고 환경 변수를 제거하세요.

변수 자동 제거

애플리케이션과 에뮬레이터를 동일한 머신에서 실행한다면 환경 변수를 자동으로 제거할 수 있습니다.

Linux/macOS

명령어 치환을 사용하여 env-unset를 실행합니다.

$(gcloud beta emulators datastore env-unset)

Windows

env-unset의 출력을 사용하여 배치 파일을 만들고 실행합니다.

gcloud beta emulators datastore env-unset > remove_vars.cmd && remove_vars.cmd

애플리케이션이 프로덕션 Datastore 모드 데이터베이스에 연결됩니다.

변수 수동 제거

애플리케이션과 에뮬레이터를 다른 머신에서 실행할 경우 환경 변수를 수동으로 삭제합니다.

  1. env-unset 명령어를 실행합니다.

    gcloud beta emulators datastore env-unset

  2. 애플리케이션을 실행하는 머신에서 env-unset 명령어의 출력에 따라 환경 변수를 삭제합니다. 예를 들면 다음과 같습니다.

    Linux/macOS
    unset DATASTORE_DATASET
unset DATASTORE_EMULATOR_HOST
unset DATASTORE_EMULATOR_HOST_PATH
unset DATASTORE_HOST
unset DATASTORE_PROJECT_ID
    Windows
    set DATASTORE_DATASET=
set DATASTORE_EMULATOR_HOST=
set DATASTORE_EMULATOR_HOST_PATH=
set DATASTORE_HOST=
set DATASTORE_PROJECT_ID=

애플리케이션이 프로덕션 Datastore 모드 데이터베이스에 연결됩니다.