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 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 esquemas Data Connect tienen dos modos de validación de esquemas 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. Todas las tablas o columnas que no se usen en tu esquema Data Connect se borrarán de la base de datos.

  • 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. Los cambios adicionales que eliminen esquemas, tablas o columnas son opcionales.

    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 use el esquema de tu aplicación no se modifican. 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 de proyectos local y en la consola de Firebase.

Un flujo de implementación recomendado implica lo siguiente:

  1. Enumera los esquemas y conectores implementados actualmente con firebase dataconnect:services:list.
  2. Administrar las actualizaciones de esquemas
    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. Ejecuta firebase deploy para realizar implementaciones de esquemas y conexiones, ya sea solo para tu esquema, solo para tus conectores o combinaciones de recursos.

Implementa y administra recursos de Data Connect

Es recomendable 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 tu esquema y 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 de 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 se haya 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 de un conector y un servicio específicos.

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, consulta una versión anterior de tu código y implementala. 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 instrucciones de migración de SQL y mensajes de acción.

Cómo migrar en modo estricto o compatible

En un proyecto nuevo, se aplica el modo de validación de esquemas predeterminada. 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 los cambios bruscos siempre que sea posible. Estos son algunos ejemplos comunes de cambios que generan errores:
    • 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 realizar la implementación.

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 permanezca exactamente alineado con 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 a tu base de datos los cambios de migración de esquema necesarios.

  • 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