Déployer et gérer les schémas et les connecteurs Data Connect

Un service Firebase Data Connect comporte trois composants principaux :

  • Une base de données PostgreSQL sous-jacente avec son propre schéma SQL
  • un Data Connect schéma d'application (déclaré dans vos .gql fichiers)
  • Un certain nombre de connecteurs (déclarés dans vos fichiers .gql et configurés dans les fichiers connector.yaml)

Le schéma SQL est la source de référence pour vos données, le Data Connect schéma indique comment vos connecteurs peuvent voir ces données, et les connecteurs déclarent les API que vos clients peuvent utiliser pour accéder à ces données.

Lorsque vous déployez votre service Data Connect avec la CLI, vous migrez votre schéma SQL, puis vous mettez à jour votre schéma Data Connect et enfin chacun de vos connecteurs.

Concepts de déploiement importants

Pour bien comprendre le déploiement, il est important de noter les concepts clés concernant les schémas et les connecteurs.

Déploiements de schéma

Le déploiement d'un Data Connect schéma affecte le schéma SQL de votre base de données Cloud SQL. Data Connect vous aide à migrer vos schémas lors du déploiement, que vous utilisiez une nouvelle base de données ou que vous deviez adapter une base de données existante de manière non destructive.

Data Connect les migrations de schéma comportent deux modes de validation de schéma différents : strict et compatible.

  • La validation en mode strict exige que le schéma de la base de données corresponde exactement au schéma de l'application avant que ce dernier puisse être mis à jour. Toutes les tables ou colonnes qui ne sont pas utilisées dans votre Data Connect schéma seront supprimées de la base de données.

  • La validation en mode compatible exige que le schéma de la base de données soit compatible avec le schéma de l'application avant que ce dernier puisse être mis à jour. Toutes les modifications supplémentaires qui suppriment des schémas, des tables ou des colonnes sont facultatives.

    Le mode compatible signifie que les migrations de schéma n'affectent que les tables et les colonnes référencées dans le schéma de votre application. Les éléments de votre base de données qui ne sont pas utilisés par le schéma de votre application ne sont pas modifiés. Par conséquent, après le déploiement, votre base de données peut contenir des éléments inutilisés :

    • Schémas
    • Tables
    • Colonnes

Déploiements de connecteur

Les requêtes et les mutations Data Connect ne sont pas envoyées par le code client et exécutées sur le serveur. Au lieu de cela, une fois déployées, ces Data Connect opérations sont stockées sur le serveur, comme les Cloud Functions. Cela signifie que le déploiement peut interrompre les utilisateurs existants.

Data Connect intègre l'analyse des modifications destructives dans vos mises à jour de connecteur dans la Firebase CLI.

La CLI analyse les modifications apportées à chaque connecteur par rapport à votre schéma et émet un ensemble de messages d'évaluation concernant les modifications de connecteur qui peuvent modifier le comportement du client (messages de niveau avertissement) ou interrompre (messages de niveau interruption) les versions précédentes du code client.

Exemple :

  • Les modifications de connecteur qui peuvent modifier le comportement du client incluent la suppression d'un champ pouvant être nul d'une requête sans annotation de schéma @retired.
  • Les modifications de connecteur qui peuvent interrompre les clients incluent la modification d'une variable d'opération pouvant être nulle en une variable non nulle sans valeur par défaut, ou la modification du type de données d'un champ en un type incompatible (par exemple, String en Int).

Une liste plus complète des scénarios de niveau avertissement et de niveau interruption est disponible dans le guide de référence de la CLI.

Suivre le workflow de déploiement

Vous pouvez travailler sur un Data Connect projet à la fois dans un répertoire de projet local et dans la console Firebase.

Un flux de déploiement recommandé implique les étapes suivantes :

  1. Répertorier les schémas et connecteurs actuellement déployés avec firebase dataconnect:services:list.
  2. Gérer les mises à jour de schéma.
    1. Rechercher les différences de schéma SQL entre votre base de données Cloud SQL et le schéma Data Connect local avec firebase dataconnect:sql:diff.
    2. Si nécessaire, effectuez la migration du schéma SQL avec dataconnect:sql:migrate.
  3. Effectuer des déploiements de schéma et de connexion en exécutant firebase deploy, que ce soit uniquement pour votre schéma, uniquement pour vos connecteurs ou pour des combinaisons de ressources.

Déployer et gérer des ressources Data Connect

Il est recommandé de vérifier les ressources de production avant d'effectuer des déploiements.

firebase dataconnect:services:list

Lorsque vous travaillez dans un répertoire de projet local, vous utilisez généralement la commande firebase deploy pour déployer votre schéma et vos connecteurs en production, avec un retour interactif.

En utilisant n'importe quelle commande deploy, l'option --only dataconnect vous permet de séparer Data Connect les déploiements des autres produits de votre projet.

Déploiement normal

firebase deploy --only dataconnect

Dans ce déploiement normal, la Firebase CLI tente de déployer votre schéma et vos connecteurs.

Elle valide que le nouveau schéma n'interrompt aucun connecteur existant. Suivez les bonnes pratiques lorsque vous apportez des modifications destructives.

Elle vérifie également que le schéma SQL est déjà migré avant de mettre à jour le Data Connect schéma. Si ce n'est pas le cas, elle vous guide automatiquement dans les étapes nécessaires pour migrer les schémas.

Déploiement de l'option --force

firebase deploy --only dataconnect --force

Si les validations de connecteur ou de schéma SQL ne vous concernent pas, vous pouvez réexécuter la commande avec --force pour les ignorer.

Le déploiement --force vérifie toujours si le schéma SQL correspond au Data Connect schéma, avertit en cas d'incompatibilité et vous invite à agir.

Déployer des ressources sélectionnées

Pour déployer avec un contrôle plus précis, utilisez l'option --only avec l'argument serviceId. Pour ne déployer que les modifications de schéma pour un service particulier :

firebase deploy --only dataconnect:serviceId:schema

Vous pouvez également déployer toutes les ressources d'un connecteur et d'un service spécifiés.

firebase deploy --only dataconnect:serviceId:connectorId

Enfin, vous pouvez déployer le schéma et tous les connecteurs d'un seul service.

firebase deploy --only dataconnect:serviceId

Annuler un déploiement

Pour effectuer une restauration manuelle, extrayez une version précédente de votre code et déployez-la. Si le déploiement d'origine comprenait des modifications destructives, vous ne pourrez peut-être pas récupérer complètement les données supprimées.

Migrer des schémas de base de données

Si vous créez rapidement des prototypes, que vous expérimentez avec des schémas et que vous savez que vos modifications de schéma sont destructives, vous pouvez prévoir d'utiliser les outils Data Connectpour vérifier les modifications et superviser leur mise en œuvre.

Différencier les modifications de schéma SQL

Vous pouvez vérifier les modifications :

firebase dataconnect:sql:diff

Vous pouvez transmettre une liste de services séparés par une virgule.

La commande compare le schéma local d'un service avec le schéma actuel de la base de données Cloud SQL correspondante. En cas de différence, elle affiche les commandes SQL qui seraient exécutées pour corriger cette différence.

Appliquer les modifications

Lorsque vous êtes satisfait et prêt à déployer les modifications dans l'instance Cloud SQL du schéma, exécutez la commande firebase dataconnect:sql:migrate. Vous serez invité à approuver les modifications.

firebase dataconnect:sql:migrate [serviceId]

Dans les environnements interactifs, les instructions de migration SQL et les invites d'action s'affichent.

Migrer en mode strict ou compatible

Dans un tout nouveau projet, le mode de validation de schéma par défaut s'applique. Le comportement de la commande migrate consiste à appliquer toutes les modifications de schéma de base de données requises par le schéma de votre application, puis à vous inviter à approuver les opérations facultatives qui suppriment des schémas, des tables ou des colonnes pour forcer la correspondance exacte entre le schéma de votre base de données et le schéma de votre application.

Vous pouvez ajuster ce comportement en modifiant votre fichier dataconnect.yaml. Supprimez la mise en commentaire de la clé schemaValidation et déclarez COMPATIBLE afin que seules les modifications requises soient appliquées lors des migrations.

schemaValidation: "COMPATIBLE"

Vous pouvez également définir le comportement sur STRICT afin que toutes les modifications de schéma soient appliquées et que le schéma de votre base de données soit forcé de correspondre au schéma de votre application.

schemaValidation: "STRICT"

Pour en savoir plus, consultez la documentation de référence de la Data Connect CLI.

Mettre à jour les connecteurs

Lorsque vous exécutez firebase deploy, la CLI lance une mise à jour des connecteurs applicables et émet des messages d'évaluation de niveau avertissement (peut avoir un impact sur le comportement du client) et de niveau interruption (interruption possible ou certaine).

Gérer les mises à jour de connecteur avec la CLI

La CLI a un comportement légèrement différent en mode interactif et en mode non interactif.

Comme vous pouvez vous y attendre, en mode interactif, la CLI vous invite à accepter tous les messages. Vous pouvez remplacer et forcer le déploiement du connecteur avec l'option --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 mode non interactif, la CLI déploie votre connecteur tant qu'il n'y a pas d'évaluation de niveau interruption. Sinon, votre script se ferme avec un journal des modifications destructives. Vous pouvez remplacer et déployer en définissant l'option --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

Pour en savoir plus, consultez le guide de référence de la CLI.

Bonnes pratiques de gestion des schémas et des connecteurs

Firebase recommande de suivre certaines pratiques dans vos Data Connect projets.

Minimiser les modifications destructives

  • Firebase recommande de conserver vos fichiers de schéma Data Connect et de connecteur dans le contrôle des sources.
  • Évitez les modifications destructives dans la mesure du possible. Voici quelques exemples courants de modifications destructives :
    • Supprimer un champ de votre schéma
    • Rendre un champ pouvant être nul dans votre schéma non nul (par exemple, Int -> Int!)
    • Renommer un champ dans votre schéma
  • Si vous devez supprimer un champ de votre schéma, envisagez de le diviser en plusieurs déploiements pour minimiser l'impact :
    • Tout d'abord, supprimez toutes les références au champ dans vos connecteurs et déployez la modification.
    • Ensuite, mettez à jour vos applications pour qu'elles utilisent les SDK nouvellement générés.
    • Enfin, supprimez le champ de votre fichier de schéma .gql, migrez votre schéma SQL et déployez-le une nouvelle fois.

Utiliser le mode strict lorsque vous travaillez avec de nouvelles bases de données

Si vous utilisez Data Connect avec une nouvelle base de données et que vous développez activement le schéma de votre application, et que vous souhaitez vous assurer que le schéma de votre base de données reste exactement conforme au schéma de votre application, vous pouvez spécifier schemaValidation: "STRICT" dans votre dataconnect.yaml.

Cela garantit que les modifications facultatives sont également appliquées.

Utiliser le mode compatible lorsque vous avez des données de production dans votre base de données

Si vous apportez des modifications à une base de données contenant des données de production, nous vous recommandons d'exécuter vos migrations de schéma en mode compatible pour vous assurer que les données existantes ne sont pas supprimées. Vous pouvez spécifier schemaValidation: "COMPATIBLE" dans votre dataconnect.yaml.

En mode compatible, seules les modifications de migration de schéma requises sont appliquées à votre base de données.

  • DROP SCHEMA, DROP TABLE et DROP COLUMN sont considérées comme des instructions facultatives et ne seront pas générées pour votre plan, même si le schéma de votre base de données contient des schémas, des tables ou des colonnes non définis dans le schéma de votre application.
  • Si votre table de base de données contient une colonne non nulle qui n'est pas incluse dans le schéma de votre application, la contrainte NOT NULL sera supprimée, afin que des données puissent toujours être ajoutées à la table avec vos connecteurs définis.

Étape suivante