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 시퀀스 중에 자동 백업 위치를 지정합니다. 이 위치는 firebase.json의 emulators.dataconnect.dataDir 필드에 저장됩니다. 에뮬레이터 실행 사이에 데이터 변경사항이 자동으로 여기에 저장되므로 로컬 테스트 및 탐색 중에 유용합니다.

수동 내보내기: 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

지정된 Data Connect 서비스에 단일 커넥터를 배포합니다.

–-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 주석 없이 쿼리에서 nullable 필드를 삭제합니다.
중단 수준 (와이어 불일치, 클라이언트가 중단될 수 있음)
  • 기본값 없이 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

플래그 설명

–-시청

스키마 및 커넥터 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가 아닌 환경의 자동 감지를 재정의합니다.