Implementa y administra esquemas y conectores de Data Connect

Un servicio Firebase Data Connect tiene tres componentes principales:

  • Una base de datos PostgreSQL subyacente con su propio esquema de SQL
  • un Data Connect esquema de aplicación (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 información para tus datos, el Data Connect esquema 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 de 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 esquemas de Data Connect tienen dos modos diferentes de validación de esquemas: estricto y compatible.

  • La validación en 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. Cualquier tabla o columna que no se use en tu Data Connect esquema se borrará de la base de datos.

  • La validación en 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. Cualquier cambio adicional que quite esquemas, tablas o columnas es opcional.

    Compatible significa que las migraciones de esquemas solo afectan las tablas y las columnas a las que se hace referencia en el esquema de tu aplicación. Los elementos de tu base de datos que no usa 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 de cliente no envía las consultas y mutaciones de Data Connect, y estas no se ejecutan en el servidor. En cambio, cuando se implementan, estas Data Connect operaciones 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 cambios rotundos en las actualizaciones de tus conectores en Firebase CLI.

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 los conectores que podrían alterar el comportamiento del cliente (los mensajes son de nivel de advertencia) o podrían o van a interrumpir (los mensajes son de nivel de interrupción) las versiones anteriores del código de cliente.

Por ejemplo:

  • Los cambios en los conectores que podrían alterar el comportamiento del cliente incluyen quitar un campo anulable de una consulta sin una anotación de esquema @retired.
  • Los cambios en los conectores que podrían o van a interrumpir a los clientes incluyen cambiar una variable de operación anulable a no nula 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 Data Connect tanto en un directorio de proyecto local como en la consola Firebase.

Un flujo de implementación recomendado incluye lo siguiente:

  1. Enumerar los esquemas y conectores implementados actualmente con firebase dataconnect:services:list.
  2. Administrar cualquier actualización de esquema.
    1. Verificar las diferencias en el esquema de SQL entre tu base de datos de Cloud SQL y el esquema Data Connect local con firebase dataconnect:sql:diff.
    2. Si es necesario, realizar la migración del esquema de SQL con dataconnect:sql:migrate.
  3. Realizar 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 Data Connect recursos

Es una buena idea verificar los recursos de producción antes de realizar las 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 Data Connect implementaciones de otros productos de tu proyecto.

Implementación normal

firebase deploy --only dataconnect

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

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

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

Implementación de la marca --force

firebase deploy --only dataconnect --force

Si no te preocupan las validaciones de conectores ni de esquemas de 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 Data Connect esquema, advierte sobre la incompatibilidad y solicita información.

Implementa 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 especificados.

firebase deploy --only dataconnect:serviceId:connectorId

Por último, puedes implementar el esquema y todos los conectores de 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, 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 las herramientas de Data Connect para verificar los cambios y supervisar cómo se realizan las actualizaciones.

Compara 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 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, imprime los comandos de SQL que se ejecutarían para corregir esa diferencia.

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 las instrucciones de migración de SQL y las instrucciones de acción.

Migra en modo estricto o compatible

En un proyecto nuevo, el modo de validación de esquemas predeterminado se aplica. 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 quitan 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 si modificas tu 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, configura el comportamiento en STRICT para que se apliquen todos los cambios en el esquema y se fuerce que el esquema de tu base de datos coincida con el esquema de tu aplicación.

schemaValidation: "STRICT"

Consulta la referencia de la Data Connect CLI 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 de nivel de advertencia (puede afectar el comportamiento del cliente) y de nivel de interrupción (posible o seguramente interrumpirá).

Administra las actualizaciones de conectores con la CLI

La CLI tiene un comportamiento ligeramente diferente en el modo interactivo y 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 que no haya evaluaciones de nivel de interrupción. De lo contrario, tu secuencia de comandos saldrá con un registro de cambios rotundos. Puedes anular y realizar la implementación si configuras 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 para seguir en tus Data Connect proyectos.

Minimiza los cambios rotundos

  • Firebase recomienda mantener los archivos de esquemas y conectores Data Connect en el control de fuente.
  • Evita los cambios rotundos cuando sea posible. Estos son algunos ejemplos comunes de cambios rotundos:
    • 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 cualquier referencia al campo en tus conectores y, luego, implementa el cambio.
    • Luego, actualiza tus apps para que usen los SDK 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 tu base de datos se mantenga exactamente en línea 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 quiten 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 necesarios en la migración de esquemas.

  • 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 tu base de datos contiene una columna no nula que no está incluida en el esquema de tu aplicación, se quitará la restricción NOT NULL para que se puedan agregar datos a la tabla con los conectores definidos.

Próximos pasos