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 schéma d'application Data Connect (déclaré dans vos fichiers .gql)
  • 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 vérité pour vos données, le schéma Data Connect est la façon dont 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, puis 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émas

Le déploiement d'un schéma Data Connect 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 travailliez avec une nouvelle base de données ou que vous deviez adapter une base de données existante de manière non destructive.

Les migrations de schéma Data Connect disposent de 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 schéma Data Connect seront supprimées de la base de données.

  • La validation du 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. Les modifications supplémentaires qui suppriment des schémas, des tables ou des colonnes sont facultatives.

    "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 connecteurs

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

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

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 susceptibles de modifier le comportement du client (messages de niveau avertissement) ou de casser ou casseront (messages de niveau cassant) les versions précédentes du code client.

Exemple :

  • Les modifications apportées au connecteur qui peuvent altérer 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 apportées au connecteur qui peuvent ou vont casser les clients incluent le changement d'une variable d'opération pouvant être nulle en variable non nulle sans valeur par défaut, ou le changement 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 "incompatibilité" est disponible dans le guide de référence de la CLI.

Suivez le workflow de déploiement.

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

Voici le flux de déploiement recommandé :

  1. Lister les schémas et connecteurs actuellement déployés avec firebase dataconnect:services:list.
  2. Gérer les mises à jour de schéma
    1. Vérifiez 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, migrez le schéma SQL avec dataconnect:sql:migrate.
  3. Effectuez des déploiements de schémas et de connexions en exécutant firebase deploy, 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.

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

Déploiement normal

firebase deploy --only dataconnect

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

Il valide le fait que le nouveau schéma ne casse aucun connecteur existant. Suivez les bonnes pratiques lorsque vous apportez des modifications incompatibles.

Il vérifie également que le schéma SQL a déjà été migré avant de mettre à jour le schéma Data Connect. Si ce n'est pas le cas, il vous invite automatiquement à suivre les étapes nécessaires pour migrer les schémas.

Déploiement de l'option --force

firebase deploy --only dataconnect --force

Si les validations du connecteur et du schéma SQL ne vous posent pas de problème, 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 schéma Data Connect, avertit en cas d'incompatibilité et invite l'utilisateur à agir.

Déployer les ressources sélectionnées

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

Effectuer le rollback d'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, il est possible que vous ne puissiez pas récupérer entièrement les données supprimées.

Migrer des schémas de base de données

Si vous créez rapidement des prototypes, que vous testez des schémas et que vous savez que vos modifications de schéma sont destructives, vous pouvez prévoir d'utiliser les outils Data Connect pour vérifier les modifications et superviser la façon dont les mises à jour sont effectuées.

Comparer les modifications du 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, les commandes SQL qui seraient exécutées pour la corriger sont affichées.

Appliquer les modifications

Lorsque vous êtes satisfait des modifications et que vous êtes prêt à les déployer sur 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 du 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 le schéma de votre base de données à correspondre exactement au schéma de votre application.

Vous pouvez ajuster ce comportement en modifiant votre fichier dataconnect.yaml. Décommentez la clé schemaValidation et déclarez COMPATIBLE afin que seules les modifications requises soient appliquées dans les 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 à celui de votre application.

schemaValidation: "STRICT"

Pour en savoir plus, consultez la documentation de référence de l'interface de ligne de commande Data Connect.

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 applicables de niveau avertissement (pouvant avoir un impact sur le comportement du client) et de niveau rupture (rupture possible ou certaine).

Gérer les mises à jour des connecteurs avec la CLI

Le comportement de l'interface de ligne de commande est légèrement différent en mode interactif et 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'évaluations de niveau "breaking". Sinon, votre script se fermera avec un journal des modifications incompatibles. 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 pour gérer les schémas et les connecteurs

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

Minimiser les modifications destructives

  • Firebase vous recommande de conserver vos fichiers de schéma et de connecteur Data Connect dans le contrôle de code source.
  • Évitez les modifications importantes dans la mesure du possible. Voici quelques exemples courants de modifications incompatibles :
    • Supprimer un champ de votre schéma
    • Rendre un champ pouvant être nul dans votre schéma non nul (c'est-à-dire 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 :
    • Commencez par supprimer toutes les références au champ dans vos connecteurs, puis déployez la modification.
    • Ensuite, mettez à jour vos applications pour qu'elles utilisent les SDK nouvellement générés.
    • Enfin, supprimez le champ dans votre fichier de schéma .gql, migrez votre schéma SQL et déployez-le à nouveau.

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 permettra de s'assurer 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 modifiez 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 compatibilité, 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 votre schéma de base de données contient des schémas, des tables ou des colonnes non définis dans votre schéma d'application.
  • Si la table de votre 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. Vous pourrez ainsi continuer à ajouter des données à la table avec les connecteurs que vous avez définis.

Étape suivante