Documentation de référence sur les commandes de la CLI Firebase pour Data Connect

Remarque :Firebase Data Connect est en version Preview publique. Data Connect sera soumis aux "Conditions des offres de pré-DG" de la section Conditions spécifiques du service des conditions d'utilisation de Google Cloud Platform. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

La CLI Firebase est un outil qui vous permet de gérer et de configurer les produits et services Firebase à partir de la ligne de commande.

La CLI fournit des commandes permettant d'effectuer diverses tâches Data Connect, comme créer un projet Data Connect, initialiser un répertoire de travail local correspondant, configurer l'émulateur Data Connect, lister les ressources Data Connect, générer des SDK client, etc.

Commandes de configuration

Ajouter Data Connect à un projet Firebase

firebase init

Utilisez firebase init pour configurer une nouvelle configuration de projet local. Ce workflow crée ou met à jour des fichiers de configuration Firebase dans votre répertoire.

firebase init

Le flux firebase init vous guide dans la configuration d'un service et d'une base de données, et éventuellement dans l'installation de l'émulateur Data Connect et la configuration des SDK générés.

Configuration du service et de la base de données

Si vous sélectionnez dataconnect pour la configuration du produit, la CLI vous invite à indiquer un nouveau nom et un nouvel emplacement de service, et à associer une instance Cloud SQL pour PostgreSQL existante ou à en créer une.

Si une instance existante est associée, la CLI recherche des paramètres compatibles, tels que l'authentification IAM et les adresses IP publiques.

Remarque :Le provisionnement d'une nouvelle instance Cloud SQL pendant le flux peut prendre jusqu'à 15 minutes.

Configuration de Local Emulator Suite

Le flux de la CLI propose de configurer des émulateurs, y compris l'émulateur Data Connect.

Commandes de l'émulateur Data Connect

Démarrer l'émulateur Data Connect

emulators:start/exec

firebase emulators:start/exec

Utilisez la version Local Emulator Suite de l'émulateur Data Connect en mode interactif avec start ou en mode non interactif basé sur un script avec exec.

Exporter et importer des données PostgreSQL locales

Pour faciliter le prototypage et les tests locaux, ainsi que l'intégration continue, vous pouvez exporter les données stockées dans une instance de base de données locale et les importer entre les itérations de développement et les exécutions de test.

Les exportations sont stockées sous forme d'instantanés de votre base de données PostgreSQL locale.

Data Connect propose trois approches d'exportation/d'importation:

• Exportation/importation automatique configurée dans votre firebase.json pour fournir des sauvegardes d'instantanés lors de l'arrêt et du démarrage de l'émulateur
• Exportation/importation manuelle à l'aide de la CLI
• Exportation/importation manuelle à l'aide de l'interface de l'extension VS Code

L'exportation et l'importation automatiques sont configurées dans votre firebase.json.

Pour sauvegarder les données entre les sessions de développement, spécifiez un emplacement de sauvegarde automatique lors de la séquence firebase init. Cet emplacement est stocké dans votre firebase.json, dans le champ emulators.dataconnect.dataDir. Toutes les modifications de données que vous apportez sont automatiquement enregistrées ici entre les exécutions de l'émulateur. Il est donc utile lors des tests et des explorations locaux.

Exportation manuelle: emulators:export et emulators:start/exec --import

Lorsque l'émulateur Data Connect est en cours d'exécution, exécutez la commande firebase emulators:export dans un terminal distinct pour enregistrer un instantané de vos données. Vous pouvez ensuite démarrer l'émulateur à partir de cet instantané à l'aide de l'indicateur --import.

# Export data from local emulator from a separate terminal
firebase emulators:export --only dataconnect <export_directory>

# Import data from local directory, here using emulators:exec
firebase emulators:exec ./<your-test-script>.sh --only dataconnect --import <import_directory>

Remarque:Un répertoire d'importation que vous spécifiez lors d'une importation manuelle avec l'option emulators:start --import de la CLI remplace le répertoire de sauvegarde par défaut configuré dans firebase.json.

Remarque:L'importation et l'exportation manuelles sont un bon moyen de fournir des données aux tests dans le cadre du CI/CD.

Exportation/importation manuelle: extension VS Code

Dans l'interface utilisateur de l'extension VS Code, lorsque l'émulateur est en cours d'exécution, utilisez le bouton Exporter les données de l'émulateur pour exporter les données afin d'exporter le contenu actuel de la base de données. L'emplacement d'exportation par défaut est le répertoire exportedData à la racine de votre répertoire de projet.

Remarque :Pour modifier cet emplacement d'exportation, avant de démarrer l'émulateur à l'aide de l'extension, cliquez sur le lien Configurer l'émulateur.

Vous pouvez importer ces données à l'aide de la CLI, comme décrit dans la section précédente. Vous pouvez également importer ces données avant de démarrer l'émulateur via VS Code en cliquant sur le lien Configurer l'émulateur et en définissant Chemin d'importation.

Commandes de gestion des schémas et des connecteurs

Cette section contient des informations de référence sur la CLI pour les commandes que vous utilisez pour gérer les schémas et les connecteurs.

Pour connaître les cas d'utilisation et les bonnes pratiques à suivre concernant ces commandes, consultez le guide de gestion des schémas et des connecteurs.

Déployer des ressources de schéma et de connecteur

déployer

firebase deploy

Cette commande déploie des ressources pour les services Data Connect indexés dans firebase.json. Une migration de schéma est effectuée si nécessaire.

Commande	Description
"firebase deploy"	Option	Description
	–-only dataconnect	Déployez des schémas et des connecteurs pour tous les services Data Connect de ce projet, mais ne déployez pas d'autres ressources de produits Firebase.
	–-only dataconnect:serviceId	Déployez le schéma et les connecteurs pour le service Data Connect spécifié.
	–-only dataconnect:serviceId:connectorId	Déployez un seul connecteur pour le service Data Connect spécifié.
	–-only dataconnect:serviceId:schema	Déployez le schéma pour le service Data Connect spécifié.

Avec les indicateurs –-only, vous pouvez transmettre des valeurs séparées par une virgule pour déployer n'importe quel sous-ensemble de ressources.

firebase deploy --only dataconnect:service1:schema,dataconnect:service2

Répertorier les services, schémas et connecteurs Data Connect

dataconnect:services:list

firebase dataconnect:services:list

Cette commande affiche des informations de base sur les services, les schémas et les connecteurs déployés sur un projet.

Comparer et migrer des schémas SQL

dataconnect:sql:diff

firebase dataconnect:sql:diff

Cette commande compare le schéma local d'un service au schéma actuel de la base de données Cloud SQL correspondante. Il affiche les commandes qui seraient exécutées pour migrer la base de données vers votre nouveau schéma.

Commande	Description
firebase dataconnect:sql:diff	Indicateur/Paramètre	Description
	ID du service	Spécifiez le service. Si elle est omise, imprimez la différence pour tous les services dans firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

Cette commande applique les modifications de schéma locales à la base de données Cloud SQL d'un service.

Lorsque vous configurez un nouveau projet Data Connect local avec le fichier dataconnect.yaml par défaut, le comportement de la commande dataconect:sql:migrate consiste à vous demander les modifications requises, puis les modifications facultatives, avant d'exécuter les modifications. Vous pouvez modifier ce comportement pour toujours inclure ou ignorer les modifications facultatives en mettant à jour votre configuration dataconnect.yaml, comme indiqué dans la section Migrer un schéma en mode strict ou compatible.

Dans les environnements interactifs, la CLI affiche chaque instruction SQL de migration (et si elle est destructive) et demande les modifications que vous souhaitez appliquer. Transmettre l'indicateur --force équivaut à accepter toutes les invites.

Dans les environnements non interactifs:

• Sans --force, seules les modifications non destructives sont apportées. En cas de modifications destructives, la CLI s'arrête et aucune modification n'est apportée.
• Avec --force, toutes les modifications sont effectuées. Si des modifications destructives sont incluses, elles sont imprimées et vous êtes invité à continuer, sauf si l'indicateur --force est fourni.

Commande	Description
firebase dataconnect:sql:migrate	Option	Description
	ID du service	Migrez la base de données du service spécifié. Le serviceId est inféré si votre projet ne comporte qu'un seul service.
	–-force	Accepter automatiquement les requêtes

Comme pour les autres indicateurs --only, vous pouvez fournir plusieurs services séparés par des virgules.

Migrer un schéma en mode strict ou compatible

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 exige que le schéma de la base de données corresponde exactement au schéma de l'application avant que le schéma de l'application puisse être déployé. La validation du mode compatible nécessite que le schéma de la base de données soit compatible avec le schéma de l'application. Cela signifie que les éléments de votre base de données qui ne sont pas utilisés par votre schéma d'application ne sont pas modifiés.

Ces modes de validation de schéma et les bonnes pratiques de migration de schéma sont décrits dans le guide de gestion des schémas et des connecteurs.

Le mode de validation est défini à l'aide de la clé schemaValidation dans votre fichier dataconnect.yaml. Si schemaValidation n'est pas spécifié, la CLI applique les modifications compatibles et vous invite avant d'exécuter les modifications strictes. Consultez la documentation de référence sur la configuration.

Commandes du SDK

Générer des SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

Cette commande génère les SDK typés déclarés dans connector.yaml.

Consultez également les guides sur l'utilisation des SDK Web, des SDK Android et des SDK iOS.

Commande	Description
firebase dataconnect:sdk:generate	Option	Description
	–-watch	Maint le processus en cours d'exécution et génère de nouveaux SDK chaque fois que vous enregistrez des modifications apportées à votre schéma et à vos fichiers GQL de connecteur. Si la génération échoue, des erreurs sont imprimées sur la sortie standard, le code généré n'est pas modifié et la commande continue de s'exécuter.
	–-only connectorId:platform	Ne générez des SDK que pour une seule plate-forme et un seul connecteur.

Avec les options –only, vous pouvez transmettre des valeurs séparées par une virgule.

firebase dataconnect:sdk:generate –-only connector1, connector1:kotlin

Commandes de gestion Cloud SQL

Accorder des rôles SQL pour Cloud SQL

dataconnect:sql:grant

firebase dataconnect:sql:grant

Data Connect s'exécute sur votre propre instance PostgreSQL hébergée sur Cloud SQL. Dans certains cas, vous pouvez accéder directement à votre base de données pour interroger ou mettre à jour les données générées par vos applications Data Connect. Pour ce faire, vous devez attribuer l'un des rôles définis dans cette section à l'utilisateur ou au compte de service requis.

Pour en savoir plus sur les rôles accordés, consultez la section Rôles utilisateur PostgreSQL.

Remarque :En plus de définir des rôles PostgreSQL avec la CLI Firebase, vous devez attribuer le rôle IAM roles/cloudsql.client. Consultez le guide de gestion des services et des bases de données.

Rôle	Rôle SQL	Autorisations	Utilisation	Accordable
lecteur	firebasereader_<db_name>_<schema_name>	Accès en lecture seule à la base de données.  Peut effectuer des opérations SELECT sur toutes les tables du schéma spécifié.	Idéal pour les utilisateurs ou les services qui nécessitent la récupération de données, mais pas leur modification.	Oui
écrivain	firebasewriter_<db_name>_<schema_name>	Accès en lecture et en écriture à la base de données.  : peut effectuer des opérations SELECT, INSERT, UPDATE, DELETE et TRUNCATE sur toutes les tables du schéma.	Convient aux utilisateurs ou services qui doivent modifier les données de la base de données.	Oui
owner	firebaseowner_<db_name>_<schema_name>	Propriétaire du schéma. Possède tous les droits sur toutes les tables et séquences du schéma.	Ce rôle, associé au rôle IAM roles/cloudsql.client, permet d'effectuer la migration de la base de données. Par exemple, lors de l'appel de firebase dataconnect:sql:migrate.	Oui
super-utilisateur	cloudsqlsuperuser	Rôle de super-utilisateur intégré avec des droits complets sur la base de données. En plus des autorisations de propriétaire, il peut créer des schémas, en supprimer, installer des extensions et effectuer d'autres tâches administratives.  Accessible dans la CLI en se connectant en tant que "firebasesuperuser".	Obligatoire pour installer des extensions, créer le schéma initial et accorder l'un des rôles SQL pouvant être accordés à d'autres utilisateurs. Si un utilisateur non administrateur a besoin de droits de super-utilisateur, la migration échoue et l'utilisateur est invité à demander à l'administrateur de la base de données (c'est-à-dire un utilisateur disposant de roles/cloudsql.admin) d'exécuter les commandes SQL privilégiées.	Accordé aux utilisateurs avec roles/cloudsql.admin et ne peut pas être accordé directement à partir de la CLI Firebase

Remarque :Ces rôles SQL sont distincts des rôles IAM Cloud SQL. Les rôles IAM contrôlent qui peut accéder à une base de données. Les rôles SQL contrôlent les opérations que vous pouvez effectuer avec cet accès et les tables que vous pouvez modifier.

Commande	Description
firebase dataconnect:sql:grant	Indicateur/Paramètre	Description
	-R, --role role	Rôle SQL à attribuer: propriétaire, rédacteur ou lecteur.
	-E, --email adresse_e-mail	Adresse e-mail d'un utilisateur ou d'un compte de service auquel attribuer le rôle.

Options globales

Les options globales suivantes s'appliquent à toutes les commandes:

• --json convertit la sortie de la CLI au format JSON pour l'analyse par d'autres outils.
• --noninteractive et --interactive remplacent, si nécessaire, la détection automatique des environnements autres que TTY.