Começar a usar o Firebase SQL Connect

Este guia de início rápido ajuda você a começar a usar o Firebase SQL Connect para conectar seus apps da Web e para dispositivos móveis a um banco de dados PostgreSQL. Você vai:

• Configure o diretório do projeto local do Firebase SQL Connect com o VS Code e a CLI do Firebase.
• Gere esquemas, consultas e mutações do SQL Connect com base nas suas ideias de app em linguagem natural.
• Use os SDKs de tipagem forte nos seus apps para executar consultas e mutações do SQL Connect.
• Provisione uma instância do Cloud SQL para PostgreSQL, um esquema do SQL Connect, consultas e mutações.

Configurar o diretório do projeto local

É possível instalar ferramentas para desenvolvedores local para o SQL Connect de duas maneiras.

Instalação automática (macOS ou Linux) Instalação manual (Windows)

1. Em um diretório de projeto, execute o comando a seguir.

   O script instala a CLI do Firebase e a extensão do VS Code do SQL Connect e orienta você pelo firebase init dataconnect para configurar o projeto. Se você não tiver o VS Code para computador instalado, o script vai abrir o editor em um navegador.

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

2. Abra a tela da extensão do VS Code do SQL Connect clicando no ícone do Firebase no painel esquerdo do Visual Studio Code.

3. Clique em Iniciar emuladores para executar o emulador com um banco de dados PGlite local.

Analisar esquema

O Firebase SQL Connect usa o GraphQL para definir seu modelo de dados. A diretiva @table mapeia um tipo do GraphQL para uma tabela do PostgreSQL. Os campos no tipo são mapeados para colunas do PostgreSQL. É possível definir relações entre tabelas usando campos que fazem referência a outros tipos de @table, incluindo relações de muitos para muitos usando tabelas de mesclagem com chaves primárias compostas.

Na configuração padrão, os arquivos de esquema SQL Connect estão no diretório dataconnect/schema/. Veja duas tabelas de exemplo do esquema de modelo de filme. Seu esquema pode ser diferente se você usou o Gemini para gerá-lo.

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")
}

Saiba mais sobre os esquemas do SQL Connect

Desenvolver consultas e mutações

O Firebase SQL Connect usa o GraphQL para consultas e mutações. Você os define em arquivos .gql e os chama pelo nome no app. A sintaxe do GraphQL oferece SDKs fortemente tipados e uma API flexível para buscar os dados exatos de que seu app precisa.

Inserir dados no banco de dados

Com o emulador em execução, é possível preenchê-lo com dados iniciais. Você pode usar o arquivo dataconnect/seed_data.gql fornecido ou escrever suas próprias mutações.

Use o botão Executar (local) do CodeLens no VS Code para executar as mutações e preencher o banco de dados PGlite local.

Analisar consultas e mutações

Na configuração padrão, as consultas e mutações de SQL Connect estão no diretório dataconnect/example/.

É possível consultar dados relacionais com precisão usando consultas aninhadas.

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 }
    }
  }
}

O SQL Connect ajuda a criar consultas e mutações seguras com o Firebase Auth.

Para manter a segurança do seu app, os apps da Web e para dispositivos móveis só podem acessar consultas e mutações do SQL Connect com diretivas @auth. As consultas e mutações podem acessar com segurança o UID do Firebase Auth usando uma expressão como {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
    }
  )
}

Saiba mais sobre as consultas do SQL Connect Saiba mais sobre as mutações do SQL Connect Saiba mais sobre a autenticação do SQL Connect

Gerar consultas e mutações

Não é preciso ser especialista em GraphQL para usar o SQL Connect de forma eficaz. É possível gerar consultas e mutações do SQL Connect com base em descrições em linguagem natural.

Em qualquer arquivo .gql, digite # para iniciar um comentário e descrever uma consulta ou mutação. Em seguida, use o botão Generate/Refine Operation do CodeLens para gerar a operação do GraphQL.

Dica: a geração de operações também está disponível no console do Firebase e no servidor MCP do Firebase.

Usar o SDK gerado no app

O firebase init dataconnect configura automaticamente SDKs de segurança de tipos para apps no seu projeto. Se necessário, adicione o SDK manualmente com o botão Adicionar SDK ao app na extensão do VS Code do SQL Connect ou executando firebase init dataconnect:sdk.

Web

1. Adicione o Firebase ao seu app da Web.

2. No arquivo principal do app React:

   • Importe o SDK gerado:

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

   • Instrua o app a se conectar ao emulador do SQL Connect:

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

   • Chame os métodos SQL 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 />);
   

   Observação: neste exemplo, o app React chama sua consulta usando o SDK do Firebase para JavaScript. O SQL Connect também oferece vinculações especiais para trabalhar com o SQL Connect de forma assíncrona no React.

Swift

1. Adicione o Firebase ao seu app iOS.

2. Para usar o SDK gerado, configure-o como uma dependência no Xcode.

   Na barra de navegação superior do Xcode, selecione File > Add Package Dependencies > Add Local e escolha a pasta que contém o Package.swift gerado.

3. No delegado principal do app:

   • Importe o SDK do SQL Connect e o SDK gerado:

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

   • Instrua o app a se conectar ao emulador do SQL 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)
     

   • Chame os métodos SQL 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. Adicione o Firebase ao seu app Android.

2. Para usar o SDK gerado, configure SQL Connect como uma dependência no Gradle.

   Atualize plugins e dependencies no seu app/build.gradle.kts.

   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. Na atividade principal do app:

   • Receba uma instância de conector do SDK gerado:

   private val connector = com.myapplication.MoviesConnector.instance
   

   • Instrua o app a se conectar ao emulador do SQL 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)
     }
   

   • Chame os métodos SQL 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. Adicione o Firebase ao seu app Flutter.
2. Instale a CLI do flutterfire dart pub global activate flutterfire_cli.
3. Execute flutterfire configure.

4. Na função principal do app:

   • Importe o SDK gerado:

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

   • Instrua o app a se conectar ao emulador do SQL 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());
   }
   

   • Chame os métodos SQL 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();
               }),
         )
       ])));
     }
   }
   

Implantar para a produção

Para implantar o esquema, as consultas e as mutações na produção:

1. Confira as informações sobre preços e o período de teste sem custo financeiro na página Preços. Seu projeto pode estar qualificado para uma das opções de teste do Firebase SQL Connect.

2. Clique no botão Implantar na produção na extensão do SQL Connect para VS Code ou execute em um terminal:

   firebase deploy --only dataconnect
   

   Depois da implantação, é possível conferir o esquema e executar consultas e mutações no console do Firebase (acesse Bancos de dados e armazenamento > SQL Connect).

   Dica: é possível configurar a região do Cloud SQL, o nome da instância e o nome do banco de dados PostgreSQL em dataconnect.yaml antes da implantação.

Saiba mais sobre dataconnect.yaml Saiba mais sobre como o SQL Connect funciona com o Cloud SQL

Próximas etapas

Agora que você concluiu o guia de início rápido, confira as próximas etapas:

• Explore um repositório de apps de início rápido e crie um app SQL Connect completo seguindo nosso codelab para Web, codelab para iOS ou codelab para Android.
• Adicione dados ao banco de dados, inspecione os esquemas e monitore o serviço SQL Connect no console do Firebase.
• Configure o servidor MCP do Firebase com ferramentas para desenvolvedores com tecnologia de IA, como Antigravity, Claude Code ou Cursor.
• Saiba mais sobre o desenvolvimento de esquemas, consultas e mutações.
• Saiba mais sobre como o SQL Connect gerencia o esquema do PostgreSQL.
• Saiba mais sobre os SDKs de cliente para Web, Android, iOS e Flutter, além dos SDKs Admin para Node.js.