이 빠른 시작에서는 Firebase Data Connect를 사용하여 웹 및 모바일 앱을 PostgreSQL 데이터베이스에 연결하는 방법을 알아봅니다. 실습할 내용은 다음과 같습니다.
- VS Code 및 Firebase CLI를 사용하여 로컬 Firebase Data Connect 프로젝트 디렉터리를 설정합니다.
- 자연어로 된 앱 아이디어를 기반으로 Data Connect 스키마, 쿼리, 변형을 생성합니다.
- 앱에서 강력한 유형의 SDK를 사용하여 Data Connect 쿼리 및 변형을 실행합니다.
- PostgreSQL용 Cloud SQL 인스턴스, 데이터 커넥트 스키마, 쿼리, 변형을 프로비저닝합니다 (Blaze 요금제 필요).
로컬 프로젝트 디렉터리 설정
Data Connect용 로컬 개발 도구는 두 가지 방법으로 설치할 수 있습니다.
다음 기본 요건을 설치합니다.
Node.js: Windows의 경우 nvm-windows를 사용하고 macOS 또는 Linux의 경우 nvm을 사용합니다.
프로젝트 디렉터리를 만들고 Visual Studio Code에서 엽니다.
VS Code Marketplace에서 Firebase Data Connect 확장 프로그램을 설치합니다.
Google 계정으로 로그인 버튼을 클릭합니다.
Firebase 프로젝트 연결 버튼을 클릭합니다.
Run firebase init 버튼을 클릭합니다.
에뮬레이터 시작 버튼을 클릭하여 로컬 PGlite 데이터베이스로 Data Connect 에뮬레이터를 실행합니다.
스키마 검토
Firebase Data Connect는 GraphQL을 사용하여 데이터 모델을 정의합니다. @table 지시어는 GraphQL 유형을 PostgreSQL 테이블에 매핑합니다. 유형의 필드는 PostgreSQL 열에 매핑됩니다. 복합 기본 키가 있는 조인 테이블을 사용하는 다대다 관계를 비롯하여 다른 @table 유형을 참조하는 필드를 사용하여 테이블 간의 관계를 정의할 수 있습니다.
기본 설정에서는 dataconnect/schema/ 디렉터리에서 Data Connect 스키마 파일을 찾을 수 있습니다. 다음은 영화 템플릿 스키마의 두 가지 예시 테이블입니다. 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")
}
쿼리 및 변형 개발
Firebase Data Connect는 쿼리 및 변형에 GraphQL을 사용합니다. .gql 파일에서 이를 정의하고 앱에서 이름으로 호출합니다. GraphQL 구문은 앱에 필요한 정확한 데이터를 가져오는 강력한 유형의 SDK와 유연한 API를 제공합니다.
데이터베이스에 데이터 시드
에뮬레이터가 실행되면 초기 데이터로 시드할 수 있습니다. 제공된 dataconnect/seed_data.gql 파일을 사용하거나 직접 변이를 작성할 수 있습니다.
VS Code에서 Run (local) Code Lens 버튼을 사용하여 변형을 실행하고 로컬 PGlite 데이터베이스를 채웁니다.

쿼리 및 변형 검토
기본 설정에서는 dataconnect/example/ 디렉터리에서 Data Connect 쿼리와 변형을 확인할 수 있습니다.
중첩된 쿼리를 사용하면 관계형 데이터를 정확하게 쿼리할 수 있습니다.
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 Auth로 안전한 쿼리 및 변형을 빌드할 수 있습니다.
앱을 안전하게 유지하기 위해 웹 및 모바일 앱은 @auth 지시어를 사용하여 Data Connect 쿼리 및 변이에만 액세스할 수 있습니다. 쿼리와 변이는 {field}_expr: "auth.uid"와 같은 표현식을 사용하여 Firebase 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 파일에서 #를 입력하여 주석을 시작하고 쿼리 또는 변형을 설명합니다. 그런 다음 작업 생성/세분화 Code Lens 버튼을 사용하여 GraphQL 작업을 생성합니다.

앱에서 생성된 SDK 사용
firebase init dataconnect는 프로젝트의 앱에 유형 안전 SDK를 자동으로 설정합니다. 필요한 경우 VS Code 확장 프로그램의 앱에 SDK 추가 버튼을 사용하거나 firebase init
dataconnect:sdk를 실행하여 SDK를 수동으로 추가할 수 있습니다.
웹
- 웹 앱에 Firebase를 추가합니다.
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 />);
Swift
- iOS 앱에 Firebase를 추가합니다.
생성된 SDK를 사용하려면 Xcode에서 종속 항목으로 구성하세요.
Xcode 상단 탐색 메뉴에서 File > Add Package Dependencies > Add Local을 선택하고 생성된
Package.swift가 포함된 폴더를 선택합니다.앱의 기본 대리자에서 다음을 실행합니다.
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.moviesConnectorData 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
- Android 앱에 Firebase를 추가합니다.
생성된 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") }앱의 기본 활동에서 다음을 실행합니다.
- 생성된 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
- Flutter 앱에 Firebase를 추가합니다.
- flutterfire CLI
dart pub global activate flutterfire_cli를 설치합니다. flutterfire configure를 실행합니다.앱의 main 함수에서 다음을 실행합니다.
- 생성된 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(); }), ) ]))); } }
프로덕션에 배포
스키마, 쿼리, 변형을 프로덕션에 배포하려면 다음 단계를 따르세요.
Blaze 요금제를 사용하도록 Firebase 프로젝트를 업그레이드합니다.
Data Connect VS Code 확장 프로그램에서 프로덕션에 배포 버튼을 클릭하거나 터미널에서 다음을 실행합니다.
firebase deploy --only dataconnect배포 후 Firebase 콘솔로 이동하여 스키마를 확인하고 쿼리 및 변이를 실행합니다.
dataconnect.yaml에 대해 자세히 알아보기 Data Connect이 Cloud SQL과 작동하는 방식 자세히 알아보기
다음 단계
빠른 시작을 완료했으므로 다음 단계를 진행하세요.
- 빠른 시작 앱 저장소를 살펴보고 웹용 Codelab, iOS용 Codelab 또는 Android용 Codelab을 따라 모든 기능을 갖춘 Data Connect 앱을 빌드하세요.
- Firebase 콘솔에서 데이터베이스에 데이터를 추가하고, 스키마를 검사하고, 데이터 커넥트 서비스를 모니터링합니다.
- Gemini Code Assist와 같은 AI 기반 개발 도구를 사용하여 Firebase MCP 서버를 설정합니다.
- 스키마, 쿼리, 변형 개발에 대해 자세히 알아보세요.
- Data Connect가 PostgreSQL 스키마를 관리하는 방법을 자세히 알아보세요.
- 웹, Android, iOS, Flutter용 클라이언트 SDK와 Node.js용 Admin SDK에 대해 자세히 알아보세요.