Implementa y administra esquemas y conectores de Data Connect

Un servicio Firebase Data Connect tiene tres componentes principales:

  • Una base de datos subyacente de PostgreSQL con su propio esquema de SQL
  • un esquema de aplicación Data Connect (declarado en tus archivos .gql)
  • una serie de conectores (declarados en tus archivos .gql).

El esquema SQL es la fuente de información de tus datos, el esquema Data Connect es la forma en que tus conectores pueden ver esos datos, y los conectores declaran las APIs que tus clientes pueden usar para acceder a esos datos.

Cuando implementes tu servicio de Data Connect con la CLI, migrarás tu esquema de SQL, luego actualizarás tu esquema de Data Connect y, luego, actualizarás cada uno de tus conectores.

Conceptos importantes de la implementación

Para comprender completamente la implementación, es importante tener en cuenta los conceptos clave sobre los esquemas y los conectores.

Implementaciones de esquemas

La implementación de un esquema Data Connect afecta el esquema SQL de tu base de datos de Cloud SQL. Data Connect te ayuda a migrar tus esquemas durante la implementación, ya sea que trabajes con una base de datos nueva o necesites adaptar una base de datos existente de forma no destructiva.

Las migraciones de esquema Data Connect tienen dos modos de validación de esquema diferentes: estricto y compatible.

  • La validación del modo estricto requiere que el esquema de la base de datos coincida exactamente con el esquema de la aplicación antes de que se pueda actualizar. Se borrarán de la base de datos todas las tablas o columnas que no se usen en el esquema Data Connect.

  • La validación del modo compatible requiere que el esquema de la base de datos sea compatible con el esquema de la aplicación antes de que se pueda actualizar el esquema de la aplicación. Cualquier cambio adicional que quite esquemas, tablas o columnas es opcional.

    Compatible significa que las migraciones de esquemas solo afectan a las tablas y columnas a las que se hace referencia en el esquema de tu aplicación. Los elementos de la base de datos que no usa el esquema de la aplicación se dejan sin modificar. Por lo tanto, después de la implementación, es posible que tu base de datos contenga lo siguiente sin usar:

    • Esquemas
    • Tables
    • Columnas

Implementaciones de conectores

El código del cliente no envía las consultas ni las mutaciones de Data Connect, y no se ejecutan en el servidor. En cambio, cuando se implementan, estas operaciones Data Connect se almacenan en el servidor, como Cloud Functions. Esto significa que la implementación puede dañar a los usuarios existentes.

Sigue el flujo de trabajo de implementación

Puedes trabajar en un proyecto Data Connect en un directorio del proyecto local y en la consola de Firebase.

Un flujo de implementación recomendado implica lo siguiente:

  1. Muestra una lista de los esquemas y conectores implementados actualmente con firebase dataconnect:services:list.
  2. Administrar cualquier actualización de esquema
    1. Verifica si hay diferencias en el esquema de SQL entre tu base de datos de Cloud SQL y el esquema local de Data Connect con firebase dataconnect:sql:diff.
    2. Si es necesario, realiza la migración del esquema de SQL con dataconnect:sql:migrate.
  3. Realizar implementaciones de esquemas y conexiones mediante la ejecución de firebase deploy, ya sea solo para tu esquema, solo para tus conectores o combinaciones de recursos.

Implementa y administra recursos de Data Connect

Es una buena idea verificar los recursos de producción antes de realizar implementaciones.

firebase dataconnect:services:list

Cuando trabajes en un directorio de proyecto local, por lo general, usarás el comando firebase deploy para implementar el esquema y los conectores en producción, con comentarios interactivos.

Con cualquier comando deploy, la marca --only dataconnect te permite separar las implementaciones de Data Connect de otros productos en tu proyecto.

Implementación normal

firebase deploy --only dataconnect

En esta implementación normal, la CLI de Firebase intenta implementar tu esquema y conectores.

Valida que el esquema nuevo no rompa ningún conector existente. Sigue las prácticas recomendadas cuando realices cambios que generen interrupciones.

También verifica que el esquema SQL ya esté migrado antes de actualizar el esquema Data Connect. De lo contrario, se te solicitará automáticamente que realices los pasos necesarios para migrar los esquemas.

Implementación de la marca --force

firebase deploy --only dataconnect --force

Si no te preocupan las validaciones del conector ni del esquema de SQL, puedes volver a ejecutar el comando con --force para ignorarlas.

La implementación de --force aún verifica si el esquema SQL coincide con el esquema Data Connect, advierte sobre la incompatibilidad y muestra mensajes.

Implementa los recursos seleccionados

Para implementar con un control más detallado, usa la marca --only con el argumento serviceId. Para implementar solo los cambios de esquema de un servicio en particular, haz lo siguiente:

firebase deploy --only dataconnect:serviceId:schema

También puedes implementar todos los recursos para un conector y un servicio especificados.

firebase deploy --only dataconnect:serviceId:connectorId

Por último, puedes implementar el esquema y todos los conectores para un solo servicio.

firebase deploy --only dataconnect:serviceId

Revierte una implementación

Para realizar una reversión manual, revisa una versión anterior de tu código y, luego, impleméntala. Si la implementación original incluyó cambios destructivos, es posible que no puedas recuperar por completo los datos borrados.

Migra esquemas de bases de datos

Si creas prototipos con rapidez, experimentas con esquemas y sabes que los cambios en ellos son destructivos, puedes planificar el uso de herramientas de Data Connect para verificar los cambios y supervisar cómo se llevan a cabo las actualizaciones.

Diferencia los cambios en el esquema de SQL

Puedes verificar los cambios de la siguiente manera:

firebase dataconnect:sql:diff

Puedes pasar una lista de servicios separados por comas.

El comando compara el esquema local de un servicio con el esquema actual de la base de datos de Cloud SQL correspondiente. Si hay una diferencia, imprime los comandos SQL que se ejecutarían para corregirla.

Aplica cambios

Cuando estés conforme y listo para implementar los cambios en la instancia de Cloud SQL del esquema, emite el comando firebase dataconnect:sql:migrate. Se te pedirá que apruebes los cambios.

firebase dataconnect:sql:migrate [serviceId]

En los entornos interactivos, se muestran las instrucciones de migración de SQL y las instrucciones de acción.

Cómo migrar en modo estricto o compatible

En un proyecto nuevo, se aplica el modo de validación de esquema predeterminado. El comportamiento del comando migrate es aplicar todos los cambios en el esquema de la base de datos que requiere el esquema de tu aplicación y, luego, solicitarte que apruebes las operaciones opcionales que eliminan esquemas, tablas o columnas para forzar que el esquema de la base de datos coincida exactamente con el esquema de tu aplicación.

Para ajustar este comportamiento, modifica el archivo dataconnect.yaml. Quita el comentario de la clave schemaValidation y declara COMPATIBLE para que solo se apliquen los cambios necesarios en las migraciones.

schemaValidation: "COMPATIBLE"

O bien establece el comportamiento en STRICT para que se apliquen todos los cambios de esquema y el esquema de la base de datos se vea obligado a coincidir con el esquema de la aplicación.

schemaValidation: "STRICT"

Consulta la referencia de la CLI de Data Connect para obtener más información.

Prácticas recomendadas para administrar esquemas y conectores

Firebase recomienda algunas prácticas que debes seguir en tus proyectos de Data Connect.

Minimiza los cambios rotundos

  • Firebase recomienda mantener el esquema y los archivos del conector Data Connect en el control de código fuente.
  • Evita hacer cambios rotundos siempre que sea posible. Estos son algunos ejemplos comunes de cambios rotundos:
    • Cómo quitar un campo de tu esquema
    • Hacer que un campo anulable en tu esquema no sea anulable (es decir, Int -> Int!)
    • Cambiar el nombre de un campo en tu esquema
  • Si necesitas quitar un campo de tu esquema, considera dividirlo en algunas implementaciones para minimizar el impacto:
    • Primero, quita todas las referencias al campo en tus conectores y, luego, implementa el cambio.
    • A continuación, actualiza tus apps para que usen los SDKs recién generados.
    • Por último, quita el campo del archivo .gql del esquema, migra el esquema SQL y, luego, vuelve a implementarlo.

Usa el modo estricto cuando trabajes con bases de datos nuevas

Si usas Data Connect con una base de datos nueva y desarrollas de forma activa el esquema de tu aplicación, y deseas asegurarte de que el esquema de la base de datos siga exactamente el esquema de tu aplicación, puedes especificar schemaValidation: "STRICT" en tu dataconnect.yaml.

Esto garantizará que también se apliquen los cambios opcionales.

Usa el modo compatible cuando tengas datos de producción en tu base de datos

Si realizas cambios en una base de datos que contiene datos de producción, te recomendamos que ejecutes las migraciones de esquemas en modo compatible para asegurarte de que no se descarten los datos existentes. Puedes especificar schemaValidation: "COMPATIBLE" en tu dataconnect.yaml.

En el modo compatible, solo se aplican los cambios de migración de esquema necesarios a tu base de datos.

  • DROP SCHEMA, DROP TABLE y DROP COLUMN se consideran instrucciones opcionales y no se generarán para tu plan, incluso si el esquema de tu base de datos contiene esquemas, tablas o columnas que no están definidos en el esquema de tu aplicación.
  • Si la tabla de la base de datos contiene una columna no nula que no se incluye en el esquema de la aplicación, se quitará la restricción NOT NULL para que los datos se puedan agregar a la tabla con los conectores definidos.

Próximos pasos