Firebase Data Connect 시작하기

이 빠른 시작에서는 Firebase Data Connect을(를) 사용하여 웹 및 모바일 앱을 PostgreSQL 데이터베이스에 연결하는 방법을 알아봅니다. 실습할 내용은 다음과 같습니다.

• VS Code 및 Firebase CLI를 사용하여 로컬 Firebase Data Connect 프로젝트 디렉터리를 설정합니다.
• 자연어로 앱 아이디어를 기반으로 Data Connect 스키마, 쿼리, 변형을 생성합니다.
• 앱에서 강력한 유형의 SDK를 사용하여 Data Connect 쿼리 및 변형을 실행합니다.
• PostgreSQL용 Cloud SQL 인스턴스, Data Connect 스키마, 쿼리, 변형을 프로비저닝합니다.

로컬 프로젝트 디렉터리 설정

Data Connect의 로컬 개발 도구는 두 가지 방법으로 설치할 수 있습니다.

자동 설치 (macOS 또는 Linux) 수동 설치 (Windows)

1. 프로젝트 디렉터리에서 다음 명령어를 실행합니다.

   스크립트는 Firebase CLI 및 Data Connect VS Code 확장 프로그램을 설치하고 firebase init dataconnect를 안내하여 프로젝트를 설정합니다. VS Code 데스크톱이 설치되어 있지 않으면 스크립트가 브라우저에서 엽니다.

   curl -sL https://firebase.tools/init/dataconnect | editor=true bash

2. Visual Studio Code 왼쪽 패널에서 Firebase 아이콘을 클릭하여 Data Connect VS Code 확장 프로그램 화면을 엽니다.

3. 에뮬레이터 시작 을 클릭하여 로컬 PGlite 데이터베이스로 에뮬레이터를 실행합니다.

스키마 검토

Firebase Data Connect은 GraphQL을 사용하여 데이터 모델을 정의합니다. @table 명령어는 GraphQL 유형을 PostgreSQL 테이블에 매핑합니다. 유형의 필드는 PostgreSQL 열에 매핑됩니다. 기본 키가 복합된 조인 테이블을 사용하는 다대다 관계를 비롯하여 다른 @table 유형을 참조하는 필드를 사용하여 테이블 간의 관계를 정의할 수 있습니다.

기본 설정에서는 Data Connect 스키마 파일을 dataconnect/schema/ 디렉터리에서 찾을 수 있습니다. 다음은 영화 템플릿 스키마의 두 가지 테이블 예시입니다. Gemini를 사용하여 스키마를 생성한 경우 스키마가 다를 수 있습니다.

type Movie @table {
  # Every table has an implicit primary key field that looks something like:
  #  id: UUID! @default(expr: "uuidV4()")
  title: String!
  imageUrl: String!
  genre: String
}

type Review @table(key: ["movie", "user"]) {
  user: User!
  movie: Movie!
  rating: Int
  reviewText: String
  reviewDate: Date! @default(expr: "request.time")
}

스키마 자세히 알아보기Data Connect

쿼리 및 변형 개발

Firebase Data Connect는 쿼리 및 변형에 GraphQL을 사용합니다. .gql 파일에서 이를 정의하고 앱에서 이름으로 호출합니다. GraphQL 구문은 강력한 유형의 SDK와 앱에 필요한 정확한 데이터를 가져오는 유연한 API를 제공합니다.

데이터베이스에 데이터 시드

에뮬레이터가 실행 중인 상태에서 초기 데이터로 시드할 수 있습니다. 제공된 dataconnect/seed_data.gql 파일을 사용하거나 자체 변형을 작성할 수 있습니다.

VS Code에서 실행 (로컬) 코드 렌즈 버튼을 사용하여 변형을 실행하고 로컬 PGlite 데이터베이스를 채웁니다.

쿼리 및 변형 검토

기본 설정에서는 Data Connect 쿼리 및 변형을 dataconnect/example/ 디렉터리에서 찾을 수 있습니다.

중첩된 쿼리를 사용하여 관계형 데이터를 정확하게 쿼리할 수 있습니다.

query ListMovies @auth(level: PUBLIC, insecureReason: "Anyone can list all movies and their reviews.") {
  movies {
    title imageUrl genre
    reviews_on_movie {
      rating reviewDate
      user { username }
    }
  }
}

Data Connect를 사용하면 Firebase 인증으로 보안 쿼리 및 변형을 빌드할 수 있습니다.

앱을 안전하게 보호하기 위해 웹 및 모바일 앱은 Data Connect 쿼리 및 변형에만 액세스할 수 있습니다. @auth 쿼리 및 변형은 Firebase 인증 UID {field}_expr: "auth.uid"와 같은 표현식을 사용하여 안전하게 액세스할 수 있습니다.

mutation AddReview($movieId: UUID!, $rating: Int!, $reviewText: String!) @auth(level: USER) {
  review_upsert(
    data: {
      userId_expr: "auth.uid"
      movieId: $movieId
      rating: $rating
      reviewText: $reviewText
    }
  )
}

Data Connect 쿼리 자세히 알아보기 Data Connect 변형 자세히 알아보기 Data Connect 인증 자세히 알아보기

쿼리 및 변형 생성

Data Connect를 효과적으로 사용하기 위해 GraphQL 전문가일 필요는 없습니다. 자연어 설명에서 Data Connect 쿼리 및 변형을 생성할 수 있습니다.

.gql 파일에서 #을 입력하여 주석을 시작하고 쿼리 또는 변형을 설명합니다. 그런 다음 작업 생성/구체화 코드 렌즈 버튼을 사용하여 GraphQL 작업을 생성합니다.

**도움말:** 작업 생성은 Firebase Console 및 Firebase MCP 서버에서도 사용할 수 있습니다.

앱에서 생성된 SDK 사용

firebase init dataconnect 는 프로젝트의 앱에 강력한 유형의 SDK를 자동으로 설정합니다. 필요한 경우 Data Connect VS Code 확장 프로그램의 앱에 SDK 추가 버튼을 사용하거나 firebase init dataconnect:sdk를 실행하여 SDK를 수동으로 추가할 수 있습니다.

웹

1. 웹 앱에 Firebase를 추가합니다.

2. React 앱의 기본 파일에서 다음을 실행합니다.

   • 생성된 SDK를 가져옵니다.

   // Update as needed with the path to your generated SDK.
   import { listMovies, ListMoviesData } from '@dataconnect/generated';
   

   • Data Connect 에뮬레이터에 연결하도록 앱을 구현합니다.

   import { connectDataConnectEmulator } from 'firebase/data-connect';
   
   const dataConnect = getDataConnect(connectorConfig);
   connectDataConnectEmulator(dataConnect, 'localhost', 9399);
   

   • Data Connect 메서드를 호출합니다.

   function App() {
     const [movies, setMovies] = useState<ListMoviesData['movies']>([]);
     useEffect(() => {
       listMovies.then(res => setMovies(res.data));
     }, []);
     return (
       movies.map(movie => <h1>{movie.title}</h1>);
     );
   }
   
   const root = ReactDOM.createRoot(document.getElementById('root'));
   root.render(<App />);
   

   참고: 이 샘플에서 React 앱은 Firebase 자바스크립트 SDK를 사용하여 쿼리를 호출합니다. Data Connect는 React에서 Data Connect를 비동기식으로 사용할 수 있는 특수 결합도 제공합니다.

Swift

1. iOS 앱에 Firebase를 추가합니다.

2. 생성된 SDK를 사용하려면 Xcode에서 종속 항목으로 구성합니다.

   Xcode 상단 탐색 메뉴에서 파일 > 패키지 종속 항목 추가 > 로컬 추가 를 선택하고 생성된 Package.swift가 포함된 폴더를 선택합니다.

3. 앱의 기본 대리자에서 다음을 실행합니다.

   • Data Connect SDK 및 생성된 SDK를 가져옵니다.

     import FirebaseDataConnect
     // Generated queries.
     // Update as needed with the package name of your generated SDK.
     import <CONNECTOR-PACKAGE-NAME>
     
     let connector = DataConnect.moviesConnector
     

   • Data Connect 에뮬레이터에 연결하도록 앱을 구현합니다.

     // 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)
     

   • Data Connect 메서드를 호출합니다.

     struct ListMovieView: View {
         @StateObject private var queryRef = connector.listMovies.ref()
     
         var body: some View {
             VStack {
                 Button {
                     Task {
                         do {
                             try await refresh()
                         } catch {
                             print("Failed to refresh: \(error)")
                         }
                     }
                 } label: {
                     Text("Refresh")
                 }
     
                 // use the query results in a view
                 ForEach(queryRef.data?.movies ?? []) { movie in
                     Text(movie.title)
                 }
                 
             }
         }
     }
     
     @MainActor
     func refresh() async throws {
         _ = try await queryRef.execute()
     }
     
     struct ContentView_Previews: PreviewProvider {
         static var previews: some View {
             ListMovieView()
         }
     }
     

Kotlin Android

1. Android 앱에 Firebase를 추가합니다.

2. 생성된 SDK를 사용하려면 Gradle에서 Data Connect를 종속 항목 으로 구성합니다.

   app/build.gradle.kts에서 plugins 및 dependencies를 업데이트합니다.

   plugins {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest as of March 14, 2025.
     // Note, however, that the version of kotlin("plugin.serialization") must,
     // in general, match the version of kotlin("android").
     id("com.android.application") version "8.9.0"
     id("com.google.gms.google-services") version "4.4.2"
     val kotlinVersion = "2.1.10"
     kotlin("android") version kotlinVersion
     kotlin("plugin.serialization") version kotlinVersion
   }
   
   dependencies {
     // Use whichever versions of these dependencies suit your application.
     // The versions shown here were the latest versions as of March 14, 2025.
     implementation("com.google.firebase:firebase-dataconnect:16.0.0-beta04")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1")
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.7.3")
   
     // These dependencies are not strictly required, but will very likely be used
     // when writing modern Android applications.
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
     implementation("androidx.appcompat:appcompat:1.7.0")
     implementation("androidx.activity:activity-ktx:1.10.1")
     implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.8.7")
     implementation("com.google.android.material:material:1.12.0")
   }
   

3. 앱의 기본 활동에서 다음을 실행합니다.

   • 생성된 SDK에서 커넥터 인스턴스를 가져옵니다.

   private val connector = com.myapplication.MoviesConnector.instance
   

   • Data Connect 에뮬레이터에 연결하도록 앱을 구현합니다.

   private val connector = com.myapplication.MoviesConnector.instance
     .apply {
       // Connect to the emulator on "10.0.2.2:9399" (default port)
       dataConnect.useEmulator()
   
       // (alternatively) if you're running your emulator on non-default port:
       // dataConnect.useEmulator(port = 9999)
     }
   

   • Data Connect 메서드를 호출합니다.

   class MainActivity : AppCompatActivity() {
   
     override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       setContentView(R.layout.activity_main)
       val textView: TextView = findViewById(R.id.text_view)
   
       lifecycleScope.launch {
         lifecycle.repeatOnLifecycle(Lifecycle.State.STARTED) {
           
           val result = connector.listMovies.runCatching { execute { } }
           
           val newTextViewText = result.fold(
             onSuccess = {
               val titles = it.data.movies.map { it.title }
               "${titles.size} movies: " + titles.joinToString(", ")
             },
             onFailure = { "ERROR: ${it.message}" }
           )
           textView.text = newTextViewText
         }
       }
     }
   }
   

Flutter

1. Flutter 앱에 Firebase를 추가합니다.
2. flutterfire CLI dart pub global activate flutterfire_cli를 설치합니다.
3. flutterfire configure를 실행합니다.

4. 앱의 기본 함수에서 다음을 실행합니다.

   • 생성된 SDK를 가져옵니다.

   // Generated queries.
   // Update as needed with the path to your generated SDK
   
   import 'movies_connector/movies.dart';
   

   • Data Connect 에뮬레이터에 연결하도록 앱을 구현합니다.

   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await Firebase.initializeApp(
       options: DefaultFirebaseOptions.currentPlatform,
     );
     
     MoviesConnector.instance.dataConnect
         .useDataConnectEmulator(Uri.base.host, 443, isSecure: true);
     
     runApp(const MyApp());
   }
   

   • Data Connect 메서드를 호출합니다.

   class MyApp extends StatelessWidget {
     const MyApp({super.key});
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
           home: Scaffold(
               body: Column(children: [
         ConstrainedBox(
           constraints: const BoxConstraints(maxHeight: 200),
           child: FutureBuilder(
               future: MoviesConnector.instance.listMovies().execute(),
               builder: (context, snapshot) {
                 if (snapshot.connectionState == ConnectionState.done) {
                   return ListView.builder(
                     scrollDirection: Axis.vertical,
                     itemBuilder: (context, index) => Card(
                         child: Text(
                       snapshot.data!.data.movies[index].title,
                     )),
                     itemCount: snapshot.data!.data.movies.length,
                   );
                 }
                 return const CircularProgressIndicator();
               }),
         )
       ])));
     }
   }
   

프로덕션에 배포

스키마, 쿼리, 변형 을 프로덕션에 배포하려면 다음 단계를 따르세요.

1. 가격 책정 페이지에서 가격 및 무료 체험판 정보를 검토합니다. 프로젝트가 Firebase Data Connect 체험판 옵션 중 하나를 사용할 수 있는 자격 요건을 충족할 수도 있습니다.

2. Data Connect VS Code 확장 프로그램에서 프로덕션에 배포 버튼을 클릭하거나 터미널에서 다음을 실행합니다.

   firebase deploy --only dataconnect
   

   배포 후 Firebase 콘솔을 방문하여 스키마를 확인하고 쿼리 및 변형을 실행합니다.

   도움말: 배포 전에 Cloud SQL 리전, 인스턴스 이름, PostgreSQL 데이터베이스 이름을 dataconnect.yaml에서 구성할 수 있습니다.

dataconnect.yaml 자세히 알아보기 Data Connect가 Cloud SQL과 작동하는 방식 자세히 알아보기

다음 단계

이제 빠른 시작을 완료했으므로 다음 단계를 따르세요.

• 빠른 시작 앱 저장소를 살펴보고 모든 기능을 갖춘 Data Connect 앱을 웹용 Codelab, iOS용 Codelab, 또는 Android용 Codelab을 따라 빌드합니다.
• 데이터베이스에 데이터를 추가하고, 스키마를 검사하고, Connect 서비스를 Firebase console에서 모니터링합니다.
• Firebase MCP 서버 를 Gemini Code Assist와 같은 AI 기반 개발 도구로 설정합니다.
• 스키마, 쿼리, 변형 개발에 대해 자세히 알아봅니다.
• Data Connect PostgreSQL 스키마를 관리하는 방법 자세히 알아보기.
• 웹, Android, iOS, Flutter용 클라이언트 SDK와 Node.js용 Admin SDK에 대해 자세히 알아봅니다.