Implementa y administra esquemas y conectores de Data Connect

Un servicio de Firebase Data Connect tiene tres componentes principales:

  • Una base de datos de PostgreSQL subyacente con su propio esquema SQL
  • Un esquema de aplicación Data Connect (declarado en tus archivos .gql)
  • Una cantidad de conectores (declarados en tus archivos .gql y configurados en archivos connector.yaml)

El esquema de SQL es la fuente de verdad para tus datos, el esquema de 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, por último, actualizarás cada uno de tus conectores.

Conceptos importantes sobre 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 de 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 de forma no destructiva una base de datos existente.

Las migraciones de esquema de Data Connect tienen dos modos diferentes de validación de esquemas: 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 el esquema de la aplicación. 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 el esquema de la aplicación. Cualquier cambio adicional que quite esquemas, tablas o columnas es opcional.

    Compatible significa que las migraciones de esquema solo afectan a las tablas y columnas a las que se hace referencia en el esquema de tu aplicación. Los elementos de tu base de datos que no se usan en el esquema de tu aplicación no se modifican. Por lo tanto, después de la implementación, tu base de datos puede contener 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 estas 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 afectar a los usuarios existentes.

Data Connect integra el análisis de los cambios que generan errores en las actualizaciones de tu conector en la CLI de Firebase.

La CLI analiza los cambios en cada conector con respecto a tu esquema y emite un conjunto de mensajes de evaluación con respecto a los cambios en el conector que podrían alterar el comportamiento del cliente (los mensajes son de nivel de advertencia) o podrían o romperán (los mensajes son de nivel de interrupción) las versiones anteriores del código del cliente.

Por ejemplo:

  • Los cambios en el conector que podrían alterar el comportamiento del cliente incluyen quitar un campo anulable de una consulta sin una anotación de esquema @retired.
  • Entre los cambios en el conector que podrían o generarán errores en los clientes, se incluyen cambiar una variable de operación anulable a no anulable sin un valor predeterminado o cambiar el tipo de datos de un campo a algo incompatible (p.ej., String a Int).

En la guía de referencia de la CLI, se proporciona una lista más extensa de situaciones de nivel de advertencia y de nivel de interrupción.

Sigue el flujo de trabajo de implementación

Puedes trabajar en un proyecto de Data Connect tanto en un directorio de proyecto local como 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 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. Realiza implementaciones de esquemas y conectores ejecutando 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 tu esquema y tus 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 tus conectores.

Valida que el nuevo esquema no interrumpa ningún conector existente. Sigue las prácticas recomendadas cuando realices cambios que interrumpan la compatibilidad.

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

Implementación de la marca --force

firebase deploy --only dataconnect --force

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

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

Implementa los recursos seleccionados

Para realizar la implementación 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, extrae una versión anterior de tu código y, luego, impleméntala. Si la implementación original incluía cambios rotundos destructivos, es posible que no puedas recuperar por completo los datos borrados.

Migra esquemas de bases de datos

Si creas prototipos rápidamente, experimentas con esquemas y sabes que los cambios en el esquema 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.

Compara los cambios del esquema de SQL

Puedes verificar los cambios de la siguiente manera:

firebase dataconnect:sql:diff

Puedes pasar una lista de servicios separada 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, se imprimen los comandos SQL que se ejecutarían para corregirla.

Aplica cambios

Cuando estés satisfecho y listo para implementar los cambios en la instancia de Cloud SQL del esquema, ejecuta 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.

Migra 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 de esquema de la base de datos que requiere el esquema de tu aplicación y, luego, solicitarte que apruebes las operaciones opcionales que descartan esquemas, tablas o columnas para forzar que el esquema de tu base de datos coincida exactamente con el esquema de tu aplicación.

Puedes ajustar este comportamiento modificando 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"

También puedes establecer el comportamiento en STRICT para que se apliquen todos los cambios de esquema y se fuerce a que el esquema de la base de datos coincida con el esquema de la aplicación.

schemaValidation: "STRICT"

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

Actualizar conectores

Cuando ejecutas firebase deploy, la CLI inicia una actualización de los conectores aplicables y emite mensajes de evaluación aplicables a nivel de advertencia (puede afectar el comportamiento del cliente) y a nivel de interrupción (posible o ciertamente interrumpido).

Administra las actualizaciones del conector con la CLI

La CLI tiene un comportamiento ligeramente diferente en el modo interactivo y en el modo no interactivo.

Como es de esperar, en el modo interactivo, la CLI te solicita que aceptes todos los mensajes. Puedes anular y forzar la implementación del conector con la marca --force.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

En el modo no interactivo, la CLI implementará tu conector siempre y cuando no haya evaluaciones de nivel de interrupción. De lo contrario, el script se cerrará con un registro de los cambios que generan errores. Puedes anular y realizar la implementación configurando la marca --force.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

Para obtener más información, consulta la guía de referencia de la CLI.

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 los archivos de esquema y conector de Data Connect en el control de código fuente.
  • Evita los cambios que generen interrupciones cuando sea posible. Algunos ejemplos comunes de cambios que generan interrupciones son los siguientes:
    • Cómo quitar un campo de tu esquema
    • Hacer que un campo anulable en tu esquema sea no 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 varias 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 de tu esquema, migra tu esquema de SQL y 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 activamente el esquema de tu aplicación, y quieres asegurarte de que el esquema de la base de datos se mantenga exactamente en línea con el esquema de la aplicación, puedes especificar schemaValidation: "STRICT" en tu dataconnect.yaml.

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

Usa el modo de compatibilidad 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 garantizar 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 no 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 se puedan seguir agregando datos a la tabla con los conectores definidos.

Próximos pasos