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).

Le schéma SQL est la source de référence pour vos données, le schéma Data Connect détermine 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, mettez à jour votre schéma Data Connect, puis mettez à jour chacun de vos connecteurs.

Concepts de déploiement importants

Pour bien comprendre le déploiement, il est important de connaître les concepts clés liés aux schémas et aux 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 utilisiez 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 comportent deux modes de validation de schéma différents : strict et compatible.

  • La validation en mode strict nécessite que le schéma de la base de données corresponde exactement au schéma de l'application pour que celui-ci 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 le schéma de l'application puisse être mis à jour. Toute modification supplémentaire qui supprime des schémas, des tables ou des colonnes est facultative.

    "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 les mutations Data Connect ne sont pas envoyées par le code client et exécutées sur le serveur. Au lieu de cela, lors du déploiement, ces opérations Data Connect sont stockées sur le serveur, comme Cloud Functions. Par conséquent, le déploiement peut affecter les utilisateurs existants.

Suivre 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. 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. Recherchez 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 connecteurs 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 des commentaires interactifs.

À l'aide de n'importe quelle commande deploy, l'option --only dataconnect 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 vérifie 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 est déjà migré avant de mettre à jour le schéma Data Connect. Si ce n'est pas le cas, vous êtes automatiquement invité à suivre les étapes nécessaires pour migrer les schémas.

Déploiement de l'option --force

firebase deploy --only dataconnect --force

Si ni le connecteur ni la validation du schéma SQL ne posent 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, émet un avertissement en cas d'incompatibilité et affiche des invites.

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 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 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 un rollback manuel, vérifiez une version précédente de votre code et déployez-la. Si le déploiement d'origine incluait 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 effectuez des prototypes rapidement, testez des schémas et savez que vos modifications de schéma sont destructives, vous pouvez planifier l'utilisation d'outils Data Connect pour vérifier les modifications et superviser la manière dont les mises à jour sont effectuées.

Différences entre 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 au 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 résoudre cette différence sont affichées.

Appliquer les modifications

Lorsque vous êtes satisfait et prêt à déployer les modifications apportées à 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 votre schéma de base de données à correspondre exactement à celui 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 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 votre schéma de base de données soit forcé de correspondre à votre schéma d'application.

schemaValidation: "STRICT"

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

Bonnes pratiques pour la gestion des schémas et des connecteurs

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

Limiter les modifications destructives

  • Firebase vous recommande de conserver votre schéma et vos fichiers de connecteur Data Connect dans un système de gestion de code source.
  • Dans la mesure du possible, évitez les modifications importantes. Voici quelques exemples courants de modifications non conformes :
    • Supprimer un champ de votre schéma
    • Rendre un champ pouvant avoir une valeur nulle dans votre schéma (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 :
    • 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 le fichier .gql de votre schéma, migrez votre schéma SQL, puis 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 votre schéma d'application, et que vous souhaitez vous assurer que votre schéma de base de données reste exactement conforme à votre schéma d'application, vous pouvez spécifier schemaValidation: "STRICT" dans votre dataconnect.yaml.

Ainsi, les modifications facultatives seront également appliquées.

Utilisez le mode compatible lorsque votre base de données contient des données de production

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, afin de vous assurer que les données existantes ne sont pas supprimées. Vous pouvez spécifier schemaValidation: "COMPATIBLE" dans votre fichier 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és comme des instructions facultatives et ne seront pas générés pour votre plan, même si votre schéma de base de données contient des schémas, des tables ou des colonnes qui ne sont pas définis dans votre schéma d'application.
  • Si votre table de base de données contient une colonne non nulle qui n'est pas incluse dans votre schéma d'application, la contrainte NOT NULL sera supprimée afin que les données puissent toujours être ajoutées à la table avec les connecteurs définis.

Étape suivante