Data Connect용 Firebase CLI 명령어 참조

Firebase CLI는 명령줄에서 Firebase 제품과 서비스를 관리하고 구성할 수 있는 도구입니다.

CLI는 새 Data Connect 프로젝트를 만들고, 해당 로컬 작업 디렉터리를 초기화하고, Data Connect 에뮬레이터를 설정하고, Data Connect 리소스를 나열하고, 클라이언트 SDK를 생성하는 등 다양한 Data Connect 작업을 실행하는 데 사용할 수 있는 명령어를 제공합니다.

설정 명령어

Firebase 프로젝트에 Data Connect 추가

firebase init

firebase init를 사용하여 새 로컬 프로젝트 구성을 설정합니다. 이 워크플로는 디렉터리에 Firebase 구성 파일을 만들거나 업데이트합니다.

firebase init

firebase init 흐름은 서비스와 데이터베이스를 설정하고, 선택적으로 Data Connect 에뮬레이터를 설치하고, 생성된 SDK를 구성하는 과정을 안내합니다.

서비스 및 데이터베이스 설정

제품 설정에 dataconnect를 선택하면 CLI에서 새 서비스 이름과 위치, 기존 PostgreSQL용 Cloud SQL 인스턴스를 연결할지 아니면 새 인스턴스를 만들지 묻는 메시지가 표시됩니다.

기존 인스턴스가 연결된 경우 CLI는 IAM 인증 및 공개 IP 주소와 같은 호환 설정을 확인합니다.

Local Emulator Suite 설정

CLI 흐름에서는 Data Connect 에뮬레이터를 비롯한 에뮬레이터를 설정할 수 있습니다.

Data Connect 에뮬레이터 명령어

Data Connect 에뮬레이터를 시작합니다.

emulators:start/exec

firebase emulators:start/exec

start를 사용하는 대화형 모드 또는 exec를 사용하는 스크립트 기반 비대화형 모드에서 Data Connect 에뮬레이터의 Local Emulator Suite 버전을 사용합니다.

로컬 PostgreSQL 데이터 내보내기 및 가져오기

로컬 프로토타입 제작 및 테스트와 지속적 통합을 지원하기 위해 로컬 데이터베이스 인스턴스에 저장된 데이터를 내보내고 개발 반복과 테스트 실행 간에 가져올 수 있습니다.

내보내기는 로컬 PostgreSQL 데이터베이스의 스냅샷으로 저장됩니다.

Data Connect에서는 내보내기/가져오기를 위한 세 가지 접근 방식을 제공합니다.

  • 에뮬레이터 종료 및 시작 시 스냅샷 백업을 제공하도록 firebase.json에 구성된 자동 내보내기/가져오기
  • CLI를 사용한 수동 내보내기/가져오기
  • VS Code 확장 프로그램 인터페이스를 사용하여 수동으로 내보내기/가져오기

firebase.json에서 구성된 자동 내보내기 및 가져오기

개발 세션 간에 데이터를 백업하려면 firebase init 시퀀스 중에 자동 백업 위치를 지정하세요. 이 위치는 emulators.dataconnect.dataDir 필드의 firebase.json에 저장됩니다. 데이터 변경사항은 에뮬레이터 실행 간에 여기에 자동으로 저장되므로 로컬 테스트 및 탐색 중에 유용합니다.

수동 내보내기: emulators:export 및 emulators:start/exec --import

Data Connect 에뮬레이터가 실행되는 동안 별도의 터미널에서 firebase emulators:export 명령어를 실행하여 데이터 스냅샷을 저장합니다. 그런 다음 --import 플래그를 사용하여 해당 스냅샷에서 에뮬레이터를 시작할 수 있습니다.

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

수동 내보내기/가져오기: VS Code 확장 프로그램

VS Code 확장 프로그램 UI에서 에뮬레이터가 실행되는 동안 에뮬레이터 데이터 내보내기 버튼을 사용하여 데이터를 내보내 현재 데이터베이스 콘텐츠를 내보냅니다. 기본 내보내기 위치는 프로젝트 디렉터리 루트의 exportedData 디렉터리입니다.

이전 섹션에 설명된 대로 CLI를 사용하여 이 데이터를 가져올 수 있습니다. 에뮬레이터 구성 링크를 클릭하고 가져오기 경로를 설정하여 VS Code를 통해 에뮬레이터를 시작하기 전에 이 데이터를 가져올 수도 있습니다.

스키마 및 커넥터 관리 명령어

이 섹션에는 스키마와 커넥터를 관리하는 데 사용하는 명령어의 CLI 참조 정보가 포함되어 있습니다.

이러한 명령어와 관련된 사용 사례 및 권장사항은 스키마 및 커넥터 관리 가이드를 참고하세요.

스키마 및 커넥터 배포

deploy

firebase deploy

이 명령어는 firebase.json에 색인이 생성된 Data Connect 서비스의 리소스를 배포합니다. 필요한 경우 스키마 이전 및 커넥터 업데이트가 실행됩니다.

명령어 설명

firebase deploy

플래그 설명

--only dataconnect

이 프로젝트의 모든 Data Connect 서비스에 스키마와 커넥터를 배포하지만 다른 Firebase 제품 리소스는 배포하지 않습니다.

–-only dataconnect:serviceId

지정된 데이터 연결 서비스의 스키마와 커넥터를 배포합니다.

–-only dataconnect:serviceId:connectorId

지정된 데이터 연결 서비스에 대해 단일 커넥터를 배포합니다.

--only dataconnect:serviceId:schema

지정된 데이터 연결 서비스의 스키마를 배포합니다.

–-only 플래그를 사용하면 원하는 리소스의 하위 집합을 배포하기 위해 쉼표로 구분된 값을 전달할 수 있습니다.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

데이터 연결 서비스, 스키마, 커넥터 나열

dataconnect:services:list

firebase dataconnect:services:list

이 명령어는 프로젝트에 배포된 서비스, 스키마, 커넥터에 관한 기본 정보를 출력합니다.

SQL 스키마 비교 및 이전

firebase deploy을 실행하면 CLI는 업데이트를 배포하기 전에 SQL 스키마 비교를 실행합니다. dataconnect:sql 명령어 집합을 사용하여 직접 비교하고 업데이트할 수도 있습니다.

dataconnect:sql:diff

firebase dataconnect:sql:diff

이 명령어는 서비스의 로컬 스키마를 해당 Cloud SQL 데이터베이스의 현재 스키마와 비교합니다. 데이터베이스를 새 스키마로 마이그레이션하기 위해 실행되는 명령어를 출력합니다.

명령어 설명

firebase dataconnect:sql:diff

플래그/매개변수 설명

serviceId

서비스를 지정합니다. 생략하면 firebase.json의 모든 서비스에 대한 차이점을 출력합니다.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

이 명령어는 서비스의 Cloud SQL 데이터베이스에 로컬 스키마 변경사항을 적용합니다.

기본 dataconnect.yaml 파일로 새 로컬 Data Connect 프로젝트를 설정하면 dataconnect:sql:migrate 명령어의 동작은 변경사항을 실행하기 전에 필요한 변경사항을 묻고 선택적 변경사항을 묻는 것입니다. 엄격 모드 또는 호환 모드에서 스키마 마이그레이션에 설명된 대로 dataconnect.yaml 구성을 업데이트하여 선택적 변경사항을 항상 포함하거나 무시하도록 이 동작을 수정할 수 있습니다.

대화형 환경에서 CLI는 각 이전 SQL 문(파괴적인지 여부)을 표시하고 적용할 변경사항을 묻는 메시지를 표시합니다. --force 플래그를 전달하는 것은 모든 프롬프트를 수락하는 것과 같습니다.

비대화형 환경:

  • --force가 없으면 비파괴적인 변경사항만 적용됩니다. 파괴적인 변경사항이 있으면 CLI가 변경사항 없이 중단됩니다.
  • --force을 사용하면 모든 변경사항이 적용됩니다. 여기에 파괴적인 변경사항이 포함된 경우 --force 플래그가 제공되지 않는 한 변경사항이 출력되고 계속할지 묻는 메시지가 표시됩니다.
명령어 설명

firebase dataconnect:sql:migrate

플래그 설명

serviceId

지정된 서비스의 데이터베이스를 이전합니다. 프로젝트에 서비스가 하나만 있는 경우 serviceId가 추론됩니다.

--force

프롬프트를 자동으로 수락합니다.

다른 --only 플래그와 마찬가지로 쉼표로 구분된 여러 서비스를 제공할 수 있습니다.

엄격 모드 또는 호환 모드로 스키마 마이그레이션

Data Connect 스키마 마이그레이션에는 strict 및 compatible의 두 가지 스키마 유효성 검사 모드가 있습니다. 엄격 모드 검증에서는 애플리케이션 스키마를 배포하기 전에 데이터베이스 스키마가 애플리케이션 스키마와 정확히 일치해야 합니다. 호환 모드 유효성 검사에서는 데이터베이스 스키마가 애플리케이션 스키마와 호환되어야 합니다. 즉, 애플리케이션 스키마에서 사용하지 않는 데이터베이스의 요소는 수정되지 않은 상태로 유지됩니다.

이러한 스키마 유효성 검사 모드와 스키마 이전 권장사항은 스키마 및 커넥터 관리 가이드에 설명되어 있습니다.

유효성 검사 모드는 dataconnect.yaml 파일의 schemaValidation 키를 사용하여 정의됩니다. schemaValidation가 지정되지 않은 경우 CLI는 호환되는 변경사항을 적용하고 엄격한 변경사항을 실행하기 전에 메시지를 표시합니다. 구성 참조를 참고하세요.

커넥터 변경사항 관리

firebase deploy를 실행하면 CLI가 해당 커넥터의 업데이트를 시작합니다. CLI는 각 커넥터의 변경사항을 분석하고 이전 버전의 클라이언트 코드에서 예기치 않은 동작 (메시지는 경고 수준) 또는 중단 (메시지는 중단 수준)을 일으킬 수 있는 커넥터 변경사항과 관련하여 평가 메시지 집합을 발행합니다.

영향 평가 시나리오
경고 수준 (와이어 호환, 동작이 변경될 수 있음)
  • @retired 주석 없이 쿼리에서 null 허용 필드를 삭제합니다.
중단 수준 (와이어가 호환되지 않으며 클라이언트가 중단될 수 있음)
  • 기본값이 없는 null 허용 변수를 null이 아닌 변수로 변경
  • 필드의 데이터 유형을 JSON 호환 유형(예: Int에서 Float)으로 변경합니다.
  • null이 아닌 열을 null 허용으로 변경
  • @retired 주석 없이 null 허용 변수를 삭제합니다.
  • @retired 주석 없이 기본값이 있는 null이 아닌 변수를 삭제합니다.
호환성 중단 수준 (와이어 비호환, 클라이언트가 중단됨)
  • @retired 주석 없이 작업을 삭제합니다.
  • @retired 주석이 없는 쿼리에서 null이 아닌 필드를 삭제합니다.
  • 기본값이 없는 null이 아닌 변수를 추가합니다.
  • 필드의 데이터 유형을 호환되지 않는 유형으로 변경 (예: String에서 Int로 변경)
  • 기본값이 없고 @retired 주석이 없는 null이 아닌 변수를 삭제합니다.

대화형 환경에서 CLI는 각 커넥터 평가를 표시하고 적용할 변경사항을 묻는 메시지를 표시합니다. --force 플래그를 전달하는 것은 모든 평가를 수락하는 것과 같습니다.

비대화형 환경의 경우:

  • 경고 수준 평가 (가능한 동작 변경)만 발생하는 경우 모든 커넥터가 배포되고 경고가 터미널에 기록됩니다.
  • 심각한 수준의 평가가 발생하면 커넥터가 배포되지 않고 경고가 터미널에 로깅됩니다. --force 플래그로 재정의할 수 있습니다.

승인 코드 감사

Data Connect를 사용하면 Firebase CLI에서 firebase deploy를 사용하여 서버에 배포할 때 커넥터 코드를 분석하여 승인 전략을 감사할 수 있습니다. 이 감사를 사용하여 코드베이스를 검토할 수 있습니다.

커넥터를 배포하면 CLI에서 커넥터의 기존, 수정된, 새로운 작업 코드에 대한 평가를 출력합니다.

수정된 작업과 새 작업의 경우 새 작업에서 특정 액세스 수준을 사용하거나 기존 작업을 수정하여 해당 액세스 수준을 사용하는 경우 CLI에서 경고를 표시하고 확인을 요청합니다.

다음의 경우 항상 경고와 메시지가 표시됩니다.

  • PUBLIC

auth.uid를 사용하여 필터로 확장하지 않는 경우 다음 액세스 수준에서 경고와 메시지가 표시됩니다.

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

승인에 대한 자세한 내용은 승인 및 증명 가이드를 참고하세요.

SDK 명령어

SDK 생성

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

이 명령어는 connector.yaml에 선언된 입력된 SDK를 생성합니다.

웹 SDK, Android SDK, iOS SDK 사용에 관한 가이드도 참고하세요.

명령어 설명

firebase dataconnect:sdk:generate

플래그 설명

--watch

프로세스를 계속 실행하고 스키마 및 커넥터 GQL 파일에 변경사항을 저장할 때마다 새 SDK를 생성합니다.

생성에 실패하면 오류가 stdout에 출력되고 생성된 코드는 변경되지 않으며 명령어가 계속 실행됩니다.

–-only connectorId:platform

단일 플랫폼 및 단일 커넥터에 대해서만 SDK를 생성합니다.

–only 플래그를 사용하면 쉼표로 구분된 값을 전달할 수 있습니다.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Cloud SQL 관리 명령어

Cloud SQL의 SQL 역할 부여

Data Connect는 Cloud SQL에서 호스팅되는 자체 PostgreSQL 인스턴스 위에서 작동합니다. SQL 역할 명령어를 사용하면 데이터베이스 테이블의 권한을 관리할 수 있습니다.

dataconnect:sql:setup

firebase dataconnect:sql:setup

이 명령어는 데이터베이스의 테이블에 대한 초기 전역 권한을 구성합니다.

기본 데이터베이스 프로비저닝 및 관리 흐름에서는 프로젝트에서 새 데이터베이스 (그린필드)를 사용한다고 가정하며, firebase deploy를 호출하면 Data Connect에서 적용할 데이터베이스 스키마 변경사항을 표시하고 승인 후 마이그레이션을 실행합니다. 이 흐름을 선호하는 경우 dataconnect:sql:setup에서 superuser 스키마 소유권을 포함한 권한을 부여하라는 메시지를 표시합니다.

기존 (브라운필드) 데이터베이스의 경우 스키마를 이전하는 자체 워크플로가 있을 수 있으며 스키마 소유권을 직접 유지하고 싶을 수 있습니다. 이 흐름을 선호하는 경우 Data Connect에서 SQL 마이그레이션을 처리해야 하는지 묻는 dataconnect:sql:setup 프롬프트에서 거부해야 합니다. 거부하면 Data Connect는 데이터베이스 테이블에 대한 read 및 write 액세스만 가져가지만 스키마 소유권 및 이전은 사용자의 책임으로 유지됩니다.

자세한 논의 및 사용 사례는 서비스 및 데이터베이스 관리를 참고하세요.

dataconnect:sql:grant

firebase dataconnect:sql:grant

경우에 따라 Data Connect 앱에서 생성된 데이터를 쿼리하거나 업데이트하기 위해 데이터베이스에 직접 액세스해야 할 수 있습니다. 이렇게 하려면 이 섹션에 정의된 역할 중 하나를 필요한 사용자 또는 서비스 계정에 부여해야 합니다.

부여된 역할에 대한 자세한 내용은 PostgreSQL 사용자 역할을 참고하세요.

역할 SQL 역할 권한 용도 부여 가능
리더 firebasereader_<db_name>_<schema_name> 데이터베이스에 대한 읽기 전용 액세스 권한입니다.

지정된 스키마 내의 모든 테이블에서 SELECT 작업을 실행할 수 있습니다.		 데이터 수정이 아닌 검색이 필요한 사용자 또는 서비스에 적합합니다. 예
작가 firebasewriter_<db_name>_<schema_name> 데이터베이스에 대한 읽기 및 쓰기 액세스 권한입니다.

스키마 내의 모든 테이블에서 SELECT, INSERT, UPDATE, DELETE, TRUNCATE 작업을 실행할 수 있습니다.		 데이터베이스 내에서 데이터를 수정해야 하는 사용자 또는 서비스에 적합합니다. 예
소유자 firebaseowner_<db_name>_<schema_name> 스키마 소유자입니다.

스키마의 모든 테이블과 시퀀스에 대한 모든 권한이 있습니다.		 이 역할은 IAM roles/cloudsql.client 역할과 함께 데이터베이스에서 마이그레이션을 실행할 수 있는 권한을 부여합니다.

예를 들어 firebase dataconnect:sql:migrate을 호출하는 경우입니다.		 예
수퍼유저 cloudsqlsuperuser 데이터베이스에 대한 모든 권한이 있는 기본 제공 수퍼유저 역할입니다.

소유자 권한 외에도 스키마를 만들고, 스키마를 삭제하고, 확장 프로그램을 설치하고, 기타 관리 작업을 실행할 수 있습니다.

'firebasesuperuser'로 로그인하여 CLI에서 액세스합니다.		 확장 프로그램을 설치하고, 초기 스키마를 만들고, 부여 가능한 SQL 역할을 다른 사용자에게 부여하는 데 필요합니다.

관리자가 아닌 사용자에게 슈퍼 사용자 권한이 필요한 경우 이전이 실패하고 사용자에게 데이터베이스 관리자 (즉, roles/cloudsql.admin 권한이 있는 사용자)에게 권한이 있는 SQL 명령을 실행하도록 요청하라는 메시지가 표시됩니다.		 roles/cloudsql.admin 권한이 있는 사용자에게 부여되며 Firebase CLI에서 직접 부여할 수 없음
명령어 설명

firebase dataconnect:sql:grant

플래그/매개변수 설명

-R, --role 역할

부여할 SQL 역할입니다(소유자, 작성자, 독자 중 하나).

-E, --email email_address

역할을 부여할 사용자 또는 서비스 계정의 이메일입니다.

전체 옵션

다음 전역 옵션은 모든 명령어에 적용됩니다.

  • --json는 다른 도구에서 파싱할 수 있도록 CLI 출력을 JSON으로 전환합니다.
  • --noninteractive 및 --interactive는 TTY가 아닌 환경의 자동 감지를 필요에 따라 재정의합니다.