Comienza a usar Firebase Data Connect

Sugerencia: Únete al programa de versión preliminar privada de Firebase Data Connect para obtener más información sobre la primera solución de SQL de Firebase. Tendrás la oportunidad de ser un usuario pionero de este producto y obtener información de primera mano sobre la nueva iniciativa de Firebase para modernizar tu experiencia de desarrollo de apps. Regístrate en la página del producto Firebase Data Connect.

Vista previa: Firebase Data Connect se encuentra en la versión preliminar privada, lo que significa que el producto no está sujeto a ningún ANS ni a ninguna política de baja, y podría cambiar de formas que generen incompatibilidad con versiones anteriores. En la Versión preliminar privada, se actualizará Data Connect y su documentación. Las versiones preliminares privadas de los productos no deben usarse en apps de producción.

Nota: Para acceder al servicio de Firebase Data Connect, así como a la mayoría de las herramientas y fuentes que se mencionan en esta guía, deberás registrarte en el programa de versión preliminar privada.

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

1. Si aún no lo has hecho, crea un proyecto de Firebase.
   1. En Firebase console, haz clic en Agregar proyecto y sigue las instrucciones en pantalla.

2. Actualiza tu proyecto al plan Blaze. Esto te permite crear una instancia de Cloud SQL para PostgreSQL.

   Nota: Aunque configures la facturación en la actualización de Blaze, no se te cobrará por el uso de Data Connect ni la configuración predeterminada de Cloud SQL para PostgreSQL durante la vista previa.

3. Ve a la sección Conexión de datos de Firebase console y sigue el flujo de trabajo para la configuración del producto.

4. Selecciona una ubicación para tu base de datos de Cloud SQL para PostgreSQL.

5. Toma nota de los nombres y los IDs del proyecto, el servicio y la base de datos para confirmarlos más tarde.

6. Sigue el flujo de configuración restante y haz clic en Listo.

   Nota: El aprovisionamiento de tu instancia de Cloud SQL para PostgreSQL puede tardar hasta 20 minutos.

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.

1. Crea un directorio nuevo para tu proyecto local.
2. Abre VS Code en el directorio nuevo.
3. Descarga la extensión, incluida como un paquete VSIX, desde Firebase Storage.
4. En VS Code, en el menú View, selecciona Extensions.
5. En la barra de título del panel Extensiones, haz clic en el ícono de menú more_horiz y, luego, en Instalar desde VSIX....

Nota: La extensión incluye la extensión de GraphQL Syntax Highlighting de Marketplace. Otras extensiones de GraphQL que instales pueden entrar en conflicto con la compatibilidad de GraphQL incluida en el archivo 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:

1. Accede a la plantilla en el sitio de Project IDX.
2. 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

Nota: Si no usas IDX, sigue los pasos que se indican en esta sección.

Instala la CLI siguiendo las instrucciones habituales.

Nota: Si usas una instalación de CLI existente, asegúrate de actualizar a la versión más reciente.

Luego, habilita el experimento de Firebase Data Connect.

firebase experiments:enable dataconnect

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:

1. Asegúrate de que accediste a tu cuenta.
2. Confirma que el flujo de configuración de Data Connect, incluido el aprovisionamiento de bases de datos, se haya completado con la consola de Google Cloud.
3. Haz clic en el botón Run firebase init.
4. Revisa la pestaña Terminal en el panel inferior de VS Code para ver los mensajes.
5. Selecciona Conexión de datos como función para usar en este directorio.
6. 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.

Este flujo creará archivos firebase.json y .firebaserc, y subdirectorios dataconnect, incluidos los archivos dataconnect.yaml y connector.yaml importantes en tu directorio de trabajo local.

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.

Nota: El aprovisionamiento de tu instancia de Cloud SQL para PostgreSQL puede tardar hasta 20 minutos. No podrás realizar implementaciones hasta que la instancia esté lista. Antes de implementar el esquema, confirma que se haya completado el flujo de configuración de Data Connect, incluido el aprovisionamiento de bases de datos, con la consola de Google Cloud.

1. 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.

2. También puedes usar Firebase CLI.

   firebase deploy
   

3. En el flujo de la extensión o de la CLI, 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.

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.

Consultas y mutaciones de tiempo de desarrollo

Las operaciones sin nombre asociadas con estos botones de CodeLens son acciones rápidas y útiles, en este caso, la adición de datos a la tabla. Data Connect usa mutaciones de GraphQL para describir cómo y quién puede operar en la base de datos. Con este botón, se crea una operación de tiempo de desarrollo para una propagación de datos rápida.

Dado que implementaste tu esquema en producción, puedes usar los botones Add data de CodeLens en los botones schema.gql y Run (Production) en los archivos generados resultantes para realizar estas acciones en tu backend.

Para agregar registros a las tablas User y Email, haz lo siguiente:

1. En schema.gql, haz clic en el botón Agregar datos ubicado sobre la declaración de tipo User.
2. En el archivo User_insert.gql que se genera, codifica los datos para los tres campos.
3. Haz clic en el botón Run (Production).
   
4. Repite los pasos anteriores para agregar un registro a la tabla Email y proporciona el uid del usuario en el campo fromUid, como se solicita en la mutación Email_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.

Nota: Asegúrate de anotar el nombre de usuario y la contraseña para acceder en el futuro.

• 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:

1. 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.
2. Haz clic en el botón Connect to Local PostgreSQL.

Próximos pasos

Nota: ¿Esta explicación te interesó en participar en el Programa de versión preliminar privada? Si es así, regístrate en la página del producto Firebase Data Connect.