En esta guía de inicio rápido, aprenderás a realizar las siguientes tareas:
- Agrega Firebase Data Connect a tu proyecto de Firebase.
- Configura un entorno de desarrollo que incluya una extensión de Visual Studio Code para trabajar con una instancia de producción.
- A continuación, te mostraremos cómo hacer lo siguiente:
- Crea un esquema para una app de correo electrónico y, luego, impleméntalo en producción.
- Define consultas y mutaciones para tu esquema.
- Implementa tu prototipo final en producción.
Requisitos previos
Para usar esta guía de inicio rápido, necesitarás lo siguiente.
- Linux, macOS o Windows
- Visual Studio Code
Agrega Data Connect a tu proyecto y crea una fuente de datos
- Si aún no lo has hecho, crea un proyecto de Firebase.
- En Firebase console, haz clic en Agregar proyecto y sigue las instrucciones en pantalla.
Actualiza tu proyecto al plan Blaze. Esto te permite crear una instancia de Cloud SQL para PostgreSQL.
Ve a la sección Conexión de datos de Firebase console y sigue el flujo de trabajo para la configuración del producto.
Selecciona una ubicación para tu base de datos de Cloud SQL para PostgreSQL.
Toma nota de los nombres y los IDs del proyecto, el servicio y la base de datos para confirmarlos más tarde.
Sigue el flujo de configuración restante y haz clic en Listo.
Elige y configura un entorno de desarrollo
Data Connect admite dos experiencias de desarrollo para el prototipado:
- Si eres desarrollador con Kotlin para Android o la Web, puedes usar el desarrollo de VS Code para crear prototipos de esquemas y operaciones a nivel local mientras te conectas a tu instancia de Cloud SQL para PostgreSQL.
Si eres desarrollador web, puedes usar IDX Development para crear un prototipo en un lugar de trabajo de IDX usando una plantilla de IDX preconfigurada con PostgreSQL, una extensión VS Code con el emulador de Data Connect y un código de inicio rápido configurado para ti.
Desarrollo de VS Code
Si deseas desarrollar de forma local en lugar de usar IDX, configura la extensión Firebase VS Code para iterar el desarrollo con rapidez.
- Crea un directorio nuevo para tu proyecto local.
- Abre VS Code en el directorio nuevo.
Descarga la extensión, incluida como un paquete VSIX, desde Firebase Storage.
En VS Code, en el menú View, selecciona Extensions.
En la barra de título del panel Extensiones, haz clic en el ícono de menú more_horiz y, luego, en Instalar desde VSIX....
Desarrollo de IDX
IDX es un entorno optimizado para el desarrollo de apps web. Si eres desarrollador de Kotlin para Android, sigue los pasos que se indican en la pestaña Desarrollo de VS Code.
Para configurar una plantilla de IDX de Data Connect, haz lo siguiente:
- Accede a la plantilla en el sitio de Project IDX.
- Sigue el flujo de configuración.
De manera opcional, puedes instalar una base de datos de PostgreSQL local para el desarrollo local con el emulador de Data Connect. Esta configuración se explica al final de esta guía de inicio rápido.
Configura tu proyecto local
Instala la CLI siguiendo las instrucciones habituales. Si ya instalaste npm, ejecuta el siguiente comando:
npm install -g firebase-tools
Para configurar tu proyecto local, inicializa el directorio del proyecto.
Configura el directorio de tu proyecto
Para configurar tu proyecto local, inicializa el directorio del proyecto.
En el panel izquierdo de VS Code, haz clic en el ícono de Firebase para abrir la IU de la extensión de Firebase VS Code.
En la IU de la extensión de Firebase:
- Asegúrate de que accediste a tu cuenta.
- Haz clic en el botón Run firebase init.
- Revisa la pestaña Terminal en el panel inferior de VS Code para ver los mensajes.
- Selecciona Conexión de datos como función para usar en este directorio.
- Cuando se te solicite, proporciona los IDs del proyecto, del servicio y de la base de datos del proyecto de Conexión de datos que creaste antes en la consola.
Crea un esquema y consulta de Data Connect
Comienza a usar GraphQL para modelar usuarios y correos electrónicos. Actualizarás las fuentes en las siguientes ubicaciones:
/dataconnect/schema/schema.gql
/dataconnect/default-connector/queries.gql
Comienza a desarrollar un esquema
En el directorio de tu proyecto de Firebase, anota la carpeta dataconnect
. Aquí es donde defines tu modelo de datos para una base de datos de Cloud SQL con GraphQL.
En el archivo /dataconnect/schema/schema.gql
, comienza a definir un esquema que incluya usuarios y correos electrónicos.
Usuario
En Data Connect, los campos de GraphQL se asignan a columnas. Los usuarios tienen un uid
, una name
y un correo electrónico de address
. Data Connect reconoce varios tipos de datos primitivos: String
y Date
.
Copia el siguiente fragmento o quita el comentario de las líneas correspondientes del archivo.
# File `/dataconnect/schema/schema.gql`
type User @table(key: "uid") {
uid: String!
name: String!
address: String!
}
Según la configuración predeterminada, Firebase Data Connect agregará una clave id
de UUID si no se proporciona ninguna. Sin embargo, en este caso, quieres que uid
sea la clave primaria, lo que puedes hacer a través de la directiva @table(key: "uid")
.
Correo electrónico
Ahora que tienes usuarios, puedes modelar los correos electrónicos. Aquí puedes agregar los campos típicos (o columnas) para los datos de correo electrónico. Esta vez, omitimos agregar una clave primaria porque puedes confiar en que Data Connect la administrará.
# File `/dataconnect/schema/schema.gql`
type Email @table {
subject: String!
sent: Date!
text: String!
from: User!
}
Ten en cuenta que el campo from
está asignado a un tipo de User
.
Data Connect entiende que esta es una relación entre Email
y User
, y la administrará por ti.
Implementa tu esquema en producción.
Si usas la extensión de Firebase VS Code para trabajar con tu base de datos de producción, debes implementar el esquema antes de continuar. Después de implementar el esquema en la base de datos de producción, deberías poder verlo en la consola.
- Puedes usar la extensión de Firebase VS Code para la implementación.
- En la IU de la extensión, en el panel de Firebase Data Connect, haz clic en Implementar todo.
- Es posible que debas revisar los cambios de esquema y aprobar las modificaciones potencialmente destructivas. Se te pedirá que hagas lo siguiente:
- Revisa los cambios de esquema con
firebase dataconnect:sql:diff
- Cuando estés conforme con los cambios, aplícalos mediante el flujo que inicia
firebase dataconnect:sql:migrate
.
- Revisa los cambios de esquema con
Ejecuta mutaciones para agregar datos a tus tablas
En el panel del editor de VS Code, puedes ver que aparecen los botones de CodeLens sobre los tipos de GraphQL en /dataconnect/schema/schema.gql
. Dado que implementaste el esquema en producción, puedes usar los botones Agregar datos y Ejecutar (producción) de los archivos generados resultantes para realizar estas acciones en tu backend.
Para agregar registros a las tablas User
y Email
, haz lo siguiente:
- En
schema.gql
, haz clic en el botón Agregar datos ubicado sobre la declaración de tipoUser
.
- En el archivo
User_insert.gql
que se genera, codifica los datos para los tres campos. - Haz clic en el botón Run (Production).
- Repite los pasos anteriores para agregar un registro a la tabla
Email
y proporciona eluid
del usuario en el campofromUid
, como se solicita en la mutaciónEmail_insert
generada.
Escribe una consulta para enumerar los correos electrónicos
Ahora la parte divertida, las consultas. Como desarrollador, estás acostumbrado a escribir consultas en SQL en lugar de consultas de GraphQL, por lo que esto puede parecer un poco diferente al principio. Sin embargo, GraphQL es mucho más tersa y segura de tipos que SQL sin procesar. Y la extensión de VS Code facilita la experiencia de desarrollo.
Comienza a editar el archivo /dataconnect/default-connector/queries.gql
. Si quieres obtener todos los correos electrónicos, usa una consulta como esta.
# File `/dataconnect/default-connector/queries.gql`
query ListEmails @auth(level: NO_ACCESS) {
emails {
id, subject, text, sent
from {
name
}
}
}
Ejecuta la consulta con el botón cercano de CodeLens.
Una función muy interesante es la capacidad de tratar las relaciones de la base de datos como un gráfico. Dado que un correo electrónico tiene un campo from
que hace referencia a un usuario, puedes anidar en el campo y obtener información sobre el usuario.
Implementa el prototipo completo en producción
Trabajaste en una iteración de desarrollo. Ahora puedes implementar tu esquema, datos y consultas en el servidor con la IU de extensión de Firebase o Firebase CLI, tal como lo hiciste con tu esquema.
Si usas la extensión de Firebase VS Code para realizar la implementación, haz clic en el botón Implementar todo.
Una vez implementado, también deberías poder ver y ejecutar tus operaciones en la consola. Tu servicio de Data Connect estará listo para procesar operaciones de clientes. La instancia de Cloud SQL para PostgreSQL se actualizará con su esquema y datos generados finales implementados.
Instala PostgreSQL de forma local (opcional)
Instalar PostgreSQL de forma local y, luego, integrarlo en el emulador te permite crear prototipos en un entorno de desarrollo completamente local.
Puedes instalar una instancia nueva de PostgreSQL o usar una existente.
Instala PostgreSQL
Instala la versión 15.x de PostgreSQL siguiendo las instrucciones para tu plataforma.
- macOS Descarga e instala Postgres.app.
- Windows: Usa el instalador de EDB de la página de descargas de PostgreSQL.
- Docker: extrae y ejecuta la imagen
pgvector/pgvector:15
, que viene con PostgreSQL 15.x y compatibilidad con vectores. - Linux: Recomendamos usar Docker con la imagen anterior, pero también puedes seguir instrucciones alternativas para distribuciones populares.
Ten en cuenta el resultado de nombre de host, puerto, nombre de usuario y contraseña, además de los parámetros relacionados, durante la secuencia de instalación.
Para conectarse a tu instancia de PostgreSQL, el emulador necesita:
- Estos parámetros de configuración
- El nombre de la base de datos de tu
dataconnect.yaml
y una base de datos con el nombre correspondiente inicializados en tu instancia local.
Actualiza tu .firebaserc
con la cadena de conexión.
Usa los detalles de configuración de PostgreSQL locales, incluidos tu nombre de usuario y contraseña locales de PostgreSQL, para que una string de conexión agregue a la siguiente clave en tu archivo .firebaserc
.
{
"projects": {},
...,
...,
"dataconnectEmulatorConfig": {
"postgres": {
"localConnectionString": "postgresql://postgresusername:postgrespassword@localhost:5432?sslmode=disable"
}}
}
Conéctate a tu instancia de PostgreSQL local
Una vez que esta configuración esté lista, sigue estos pasos para conectarte a tu base de datos local:
- En VS Code, en el panel del lado izquierdo, haz clic en el ícono de Firebase para abrir la IU de la extensión Firebase VS Code.
- Haz clic en el botón Connect to Local PostgreSQL.