Firebase Data Connect는 엔드 투 엔드 프로토타입 제작은 물론 지속적 통합 및 지속적 배포(CI/CD) 흐름을 위한 로컬 에뮬레이터를 제공합니다.
Data Connect 에뮬레이터는 로컬 통합 PGLite 데이터베이스 인스턴스와 상호작용하여 완전히 로컬 환경에서 쿼리 및 변형을 프로토타입으로 만들고 클라이언트 코드를 테스트할 수 있습니다.
Data Connect 에뮬레이터는 비대화형 작업에도 사용할 수 있습니다. 자동 테스트를 실행할 수 있으며 CI/CD 워크플로와 함께 사용하기에 적합합니다. 이는 스키마가 안정적이고 클라이언트 측 코드를 프로토타입으로 만들고 테스트하려는 경우에 유용합니다.
이 가이드에서는 빠른 시작보다 에뮬레이터의 설치 및 사용을 더 자세히 다룹니다.
Data Connect 에뮬레이터 설치
Data Connect 에뮬레이터를 사용하기 위해 Local Emulator Suite를 설치하려면 다음이 필요합니다.
Node.js 버전 18.0 이상
Firebase CLI 설치 및 프로젝트 디렉터리 설정
설치 가이드에 따라Firebase CLI를 설치합니다.
Data Connect 에뮬레이터는 버그 수정 및 새로운 기능과 함께 활발히 개발되고 있으므로 정기적으로 업데이트하세요.
아직 초기화하지 않았다면 메시지에 따라 사용할 제품을 지정하여 현재 작업 디렉터리를 Firebase 프로젝트로 초기화합니다.
firebaseinit
Local Emulator Suite 구성 설정 또는 수정
Firebase VS Code 확장 프로그램에서 Data Connect 에뮬레이터를 시작한 경우 필요한 경우 에뮬레이터가 설치되었습니다.
Firebase CLI를 사용하여 에뮬레이터를 Local Emulator Suite의 다른 선택된 구성요소와 함께 수동으로 설치할 수 있습니다. 이 명령어는 원하는 에뮬레이터를 선택하고 해당 에뮬레이터 바이너리 파일을 다운로드하며 기본값이 적절하지 않은 경우 에뮬레이터 포트를 설정할 수 있는 구성 마법사를 시작합니다.
firebaseinitemulators
에뮬레이터가 설치되면 Firebase CLI 버전을 업데이트할 때까지 업데이트 확인이 수행되지 않으며 자동 다운로드가 추가로 진행되지 않습니다.
Firebase 프로젝트 선택
설정 흐름에서 Firebase CLI는 Firebase 프로젝트를 선택하거나 만들도록 프롬프트를 표시합니다. Firebase 콘솔에서 Data Connect로 설정한 기존 프로젝트를 선택하면 선택한 구성이 추천됩니다.
에뮬레이터 설정
에뮬레이터 구성
firebase init 흐름을 실행하면 에뮬레이터 설정 옵션이 안내됩니다.
Local Emulator Suite의 다른 에뮬레이터와 마찬가지로 구성 매개변수는 로컬 프로젝트 파일에 저장됩니다.
firebase.json 파일에는 에뮬레이터 포트 할당이 포함되어 있습니다.
emulators:ui 키는 Data Connect 에뮬레이터에는 적용되지 않습니다.
로컬 및 프로덕션 Data Connect 리소스 사용
프로덕션 리소스에 영향을 주지 않으려면 demo- projectID를 설정하거나 클라이언트 코드가 에뮬레이터에 연결되도록 계측해야 합니다(후반 섹션 참고).
에뮬레이터 시작
CI/CD 워크플로와 같이 비대화형으로 에뮬레이터를 실행하는 경우 exec 옵션으로 시작하세요.
firebaseemulators:exec./path/to/test-script.sh
클라이언트 코드에 사전 정의된 쿼리와 변형을 통합하고 클라이언트 테스트를 위해 에뮬레이터를 사용하는 경우 대화형 작업을 위해 start 옵션을 사용할 수 있습니다. VS Code 확장 프로그램에서 에뮬레이터를 시작할 수도 있습니다.
firebaseemulators:start
에뮬레이터와 통신하도록 클라이언트 코드 구현
Data Connect 에뮬레이터와 상호작용하도록 인앱 구성 또는 테스트 클래스를 다음과 같이 설정합니다.
자바스크립트
import{initializeApp}from"firebase/app";import{connectorConfig}from"@name-of-package";import{connectDataConnectEmulator,getDataConnect}from'firebase/data-connect';// TODO: Replace the following with your app's Firebase project configurationconstfirebaseConfig={//...};constapp=initializeApp(firebaseConfig);constdataConnect=getDataConnect(app,connectorConfig);connectDataConnectEmulator(dataConnect,"localhost",9399);// Make calls from your app
Kotlin Android
valconnector=MoviesConnector.instance// Connect to the emulator on "10.0.2.2:9399"connector.dataConnect.useEmulator()// (Alternatively) if you're running your emulator on non-default port:connector.dataConnect.useEmulator(port=9999)// Make calls from your app
iOS
let connector = DataConnect.dataConnect(DefaultConnectorClient.connectorConfig)
// Connect to the emulator on "127.0.0.1:9399"
connector.useEmulator()
// (alternatively) if you're running your emulator on non-default port:
connector.useEmulator(port: 9999)
// Make calls from your app
테스트 및 지속적 통합에 에뮬레이터 사용
컨테이너화된 Local Emulator Suite 이미지 실행
일반적인 CI 설정에서 컨테이너를 사용하여 Local Emulator Suite를 설치하고 구성하는 방법은 간단합니다.
다음과 같은 몇 가지 문제가 있습니다.
에뮬레이터 바이너리는 ~/.cache/firebase/emulators/에 설치되고 캐시됩니다. 이 경로를 CI 캐시 구성에 추가하여 반복 다운로드를 방지할 수 있습니다.
저장소에 firebase.json 파일이 없는 경우 emulators:start 또는 emulators:exec 명령어에 명령줄 인수를 추가하여 시작할 에뮬레이터를 지정해야 합니다. 예를 들면 --only dataconnect입니다.
테스트 간 데이터베이스 삭제
실행 간에 테스트 환경을 재설정하려면 다음을 권장합니다.
다음을 처리하기 위한 전용 변형 작성:
설정에서 시작 데이터로 로컬 데이터베이스 인스턴스를 채웁니다.
테스트 후 데이터베이스 인스턴스에서 수정된 데이터를 정리에서 삭제합니다.
Data Connect 에뮬레이터와 프로덕션 환경의 차이점
Data Connect 에뮬레이터는 서버 측 제품의 여러 기능을 시뮬레이션합니다. 하지만 다음과 같은 예외가 있습니다.
PGLite의 버전과 세부 구성은 프로덕션 Cloud SQL 인스턴스의 버전과 다를 수 있습니다.
에뮬레이터를 사용하여 Data Connect의 pgvector 및 Vertex API 통합으로 개발하는 경우 Cloud Vertex API 호출은 Cloud SQL의 Vertex 통합을 통하지 않고 직접 이루어집니다. 하지만 프로덕션 API 호출은 계속 이루어지므로 실제 Firebase 프로젝트를 사용해야 하고 demo- 프로젝트는 사용할 수 없으며 Vertex API 비용이 발생합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["필요한 정보가 없음","missingTheInformationINeed","thumb-down"],["너무 복잡함/단계 수가 너무 많음","tooComplicatedTooManySteps","thumb-down"],["오래됨","outOfDate","thumb-down"],["번역 문제","translationIssue","thumb-down"],["샘플/코드 문제","samplesCodeIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-06(UTC)"],[],[],null,["\u003cbr /\u003e\n\nFirebase Data Connect provides you with a local emulator for end-to-end\nprototyping as well as continuous integration and continuous deployment\n(CI/CD) flows:\n\n- The Data Connect emulator interacts with a local integrated PGLite database instance to let you prototype queries and mutations and test client code in a fully local environment.\n- The Data Connect emulator can also be used for non-interactive work. It lets you run automated tests and is suitable for use with CI/CD workflows. This is useful when your schemas are stable and you want to prototype and test client-side code.\n\nThis guide covers installation and usage of the emulator in more detail than\nthe quickstart.\n\nInstall the Data Connect emulator\n\nBefore installing the Local Emulator Suite to use the Data Connect\nemulator, you will need:\n\n- Node.js version 18.0 or higher.\n\nInstall the Firebase CLI and set up project directory **Note:** If you've followed the [Get started with Firebase Data Connect](/docs/data-connect/quickstart) guide, you can skip this section.\n\n1. Install the Firebase CLI, [following the installation guide](/docs/cli).\n Be sure to [update regularly](/docs/cli#update-cli), since the\n Data Connect emulator is under active development with bug fixes and\n new features.\n\n2. If you haven't already done so, initialize the current working directory as\n a Firebase project, following prompts to specify which products to use:\n\n firebase init\n\nSet or modify the Local Emulator Suite configuration\n\nIf you started the Data Connect emulator from the Firebase VS Code\nextension, the emulator was installed for you, if needed.\n\nYou can use the Firebase CLI to manually install the emulator along with\nother selected components of the Local Emulator Suite. This command starts a\nconfiguration wizard that lets you select emulators of interest, download the\ncorresponding emulator binary files, and set emulator ports if the defaults are\nnot appropriate. \n\n firebase init emulators\n\nOnce an emulator is installed, no update checks are performed and no additional\nautomatic downloads will occur until you update your Firebase CLI version.\n\nChoose a Firebase project\n\nIn the setup flow, the Firebase CLI prompts you to choose or create a\nFirebase project. If you choose an existing project you've set up with\nData Connect in the Firebase console, the configuration you chose\nthere will be suggested.\n\nSet up the emulator **Note:** Usage of the emulator in the Firebase Data Connect VS Code extension is covered in [Get started with Firebase Data Connect](/docs/data-connect/quickstart).\n\nConfigure the emulator\n\nRunning the `firebase init` flow will guide you through emulator setup options.\nLike other emulators in the Local Emulator Suite, configuration parameters\nare stored in local project files.\n\n- Your `firebase.json` file contains emulator port assignments.\n - The `emulators:ui` key does not apply to the Data Connect emulator.\n\nWork with local and production Data Connect resources\n\nIf you want to be sure not to impact production resources, set a `demo-`\nprojectID or make sure your client code is instrumented to connect to\nthe emulator, as discussed in a later section.\n\nStart the emulator\n\nIf you're running the emulator non-interactively, for example for CI/CD\nworkflows, start it with the `exec` option. \n\n firebase emulators:exec ./path/to/test-script.sh\n\nIf you're integrating predefined queries and mutations in client code and are\nusing the emulator specifically for testing clients, you can use the `start`\noption for interactive work. You can also start the emulator from the VS Code\nextension. \n\n firebase emulators:start\n\n| **Note:** When you start the emulator with `firebase emulators:start`, SDK code will be automatically generated just as if you had run `firebase sdk:generate`.\n\nInstrument your client code to talk to the emulator\n\nSet up your in-app configuration or test classes to interact with the\nData Connect emulator as follows. \n\nJavaScript \n\n```javascript\nimport { initializeApp } from \"firebase/app\";\nimport { connectorConfig } from \"@name-of-package\";\nimport { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect';\n\n// TODO: Replace the following with your app's Firebase project configuration\nconst firebaseConfig = {\n //...\n};\n\nconst app = initializeApp(firebaseConfig);\n\nconst dataConnect = getDataConnect(app, connectorConfig);\nconnectDataConnectEmulator(dataConnect, \"localhost\", 9399);\n\n// Make calls from your app\n \n```\n\nKotlin Android \n\n```kotlin\nval connector = MoviesConnector.instance\n\n// Connect to the emulator on \"10.0.2.2:9399\"\nconnector.dataConnect.useEmulator()\n\n// (Alternatively) if you're running your emulator on non-default port:\nconnector.dataConnect.useEmulator(port = 9999)\n\n// Make calls from your app\n \n```\n\niOS \n\n```text\nlet connector = DataConnect.dataConnect(DefaultConnectorClient.connectorConfig)\n\n// Connect to the emulator on \"127.0.0.1:9399\"\nconnector.useEmulator()\n\n// (alternatively) if you're running your emulator on non-default port:\nconnector.useEmulator(port: 9999)\n\n// Make calls from your app\n \n```\n\nUse the emulator for testing and continuous integration\n\nRun containerized Local Emulator Suite images\n\nInstallation and configuration of the Local Emulator Suite with containers\nin a typical CI setup is straightforward.\n\nThere are a few issues to note:\n\n- Emulator binaries are installed and cached at `~/.cache/firebase/emulators/`. You may want to add this path to your CI cache configuration to avoid repeated downloads.\n- If you don't have a `firebase.json` file in your repository, you must add a command line argument to the `emulators:start` or `emulators:exec` command to specify which emulators should be started. For example, `--only dataconnect`.\n\nClear your database between tests\n\nTo reset your test environments between runs, Firebase recommends:\n\n- Writing dedicated mutations to handle the following:\n - In setup, populate a local database instance with starting data.\n - In teardown, delete modified data from post-test database instance.\n\nHow the Data Connect emulator differs from production\n\nThe Data Connect emulator simulates many features of the server-side\nproduct. However, there are some exceptions to be aware of:\n\n- The version and detailed configuration of PGLite may differ from the version of your production Cloud SQL instance.\n- If you're using the emulator to develop with Data Connect's pgvector and Vertex API integration, calls to the Cloud Vertex API are made directly, rather than through Cloud SQL's Vertex integration. However, calls to the production API are still made, meaning you must use a real Firebase project, cannot use a `demo-` project, and costs of the Vertex API will be incurred."]]
