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

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.

L'interface de ligne de commande fournit des commandes qui peuvent être utilisées pour 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 les 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, l'interface CLI vous invite à saisir un nouveau nom et un nouvel emplacement de service, et à indiquer si vous souhaitez associer une instance Cloud SQL pour PostgreSQL existante ou en créer une.

Si une instance existante est associée, la CLI vérifie la présence de paramètres compatibles, tels que l'authentification IAM et les adresses IP publiques.

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 piloté par script avec exec.

Exporter et importer des données PostgreSQL locales

Pour prendre en charge 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 tests.

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

Data Connect propose trois approches pour l'exportation/importation :

  • Exportation/importation automatiques configurés dans votre firebase.json pour fournir des sauvegardes instantanées à l'arrêt et au 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

Exportation et importation automatiques configurées dans votre firebase.json

Pour sauvegarder des 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. Cette fonctionnalité est donc utile lors des tests et de l'exploration en local.

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

Pendant que 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>

Exportation/importation manuelles : extension VS Code

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

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 les commandes de l'interface de ligne de commande que vous utilisez pour gérer les schémas et les connecteurs.

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

Déployer des schémas et des connecteurs

déployer

firebase deploy

Cette commande déploie les ressources pour les services Data Connect indexés dans firebase.json. Une migration de schéma et une mise à jour du connecteur sont effectuées si nécessaire.

Commande Description

firebase deploy

Option Description

--only dataconnect

Déployez les schémas et les connecteurs pour tous les services Data Connect de ce projet, mais ne déployez pas les 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é.

Les indicateurs –-only vous permettent de transmettre des valeurs séparées par une virgule pour déployer le sous-ensemble de ressources de votre choix.

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

Lister 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 dans un projet.

Comparer et migrer des schémas SQL

Lorsque vous exécutez firebase deploy, la CLI effectue une comparaison du schéma SQL avant de déployer les mises à jour. Vous pouvez également effectuer la comparaison et la mise à jour directement avec un ensemble de commandes dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

Cette commande compare le schéma local d'un service avec le 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 ce paramètre est omis, la différence pour tous les services dans firebase.json est affichée.

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, la commande dataconnect:sql:migrate vous invite à apporter 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 Migrer un schéma en mode strict ou compatible.

Dans les environnements interactifs, la CLI affiche chaque instruction SQL de migration (et indique si elle est destructrice) et vous invite à indiquer 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 sans apporter de modifications.
  • Toutes les modifications sont apportées avec --force. Si cela inclut des modifications destructives, elles sont imprimées et vous êtes invité à indiquer si vous souhaitez continuer, sauf si l'indicateur --force est fourni.
Commande Description

firebase dataconnect:sql:migrate

Option Description

ID du service

Migre la base de données pour le service spécifié. L'ID de service est déduit si votre projet ne comporte qu'un seul service.

--force

Acceptez automatiquement les invites.

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 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 base de données corresponde exactement au schéma d'application avant que ce dernier puisse être déployé. 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, ce qui signifie que 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.

Ces modes de validation de schéma et les bonnes pratiques de migration de schéma sont abordés 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 à confirmer avant d'exécuter des modifications strictes. Consultez la documentation de référence sur la configuration.

Gérer les modifications apportées aux connecteurs

Lorsque vous exécutez firebase deploy, la CLI lance une mise à jour des connecteurs applicables. L'interface de ligne de commande analyse les modifications apportées à chaque connecteur et émet un ensemble de messages d'évaluation concernant les modifications de connecteur qui peuvent entraîner un comportement inattendu (messages de niveau "avertissement") ou des dysfonctionnements (messages de niveau "erreur") dans les versions précédentes du code client.

Évaluation de l'impact Scénario
Niveau d'avertissement (compatible avec les câbles, le comportement peut changer)
  • Suppression d'un champ pouvant être nul d'une requête sans annotation @retired.
Niveau de rupture (câble incompatible, peut casser les clients)
  • Modification d'une variable nullable en variable non nulle sans valeur par défaut.
  • Modifier le type de données d'un champ pour le rendre compatible avec JSON (par exemple, Int en Float).
  • Passer d'une colonne non nulle à une colonne pouvant accepter des valeurs nulles
  • Suppression d'une variable nullable sans annotation @retired.
  • Suppression d'une variable non nulle avec une valeur par défaut sans annotation @retired.
Niveau de rupture (câble incompatible, cassera les clients)
  • Suppression d'une opération sans annotation @retired.
  • Suppression d'un champ non nul d'une requête sans annotation @retired.
  • Ajout d'une variable non nulle sans valeur par défaut.
  • Modifier le type de données d'un champ pour le remplacer par un type incompatible (par exemple, String par Int).
  • Suppression d'une variable non nulle sans valeur par défaut ni annotation @retired.

Dans les environnements interactifs, l'interface de ligne de commande affiche chaque évaluation du connecteur et vous invite à appliquer les modifications souhaitées. Transmettre l'indicateur --force équivaut à accepter toutes les évaluations.

Dans les environnements non interactifs :

  • Si seules des évaluations de niveau avertissement (changements de comportement possibles) se produisent, tous les connecteurs seront déployés et les avertissements seront consignés dans le terminal.
  • Si des évaluations de niveau "breaking" se produisent, aucun connecteur ne sera déployé et des avertissements seront consignés dans le terminal. Vous pouvez remplacer cette valeur par l'option --force.

Auditer le code d'autorisation

Data Connect vous aide à auditer votre stratégie d'autorisation en analysant le code de votre connecteur lorsque vous le déployez sur le serveur à l'aide de firebase deploy à partir de l'interface de ligne de commande Firebase. Vous pouvez utiliser cet audit pour vous aider à examiner votre code.

Lorsque vous déployez vos connecteurs, l'interface CLI génère des évaluations pour le code d'opération existant, modifié et nouveau dans votre connecteur.

Pour les opérations modifiées et nouvelles, la CLI émet des avertissements et vous invite à confirmer lorsque vous utilisez certains niveaux d'accès dans vos nouvelles opérations ou lorsque vous modifiez des opérations existantes pour utiliser ces niveaux d'accès.

Des avertissements et des invites s'affichent toujours pour les cas suivants :

  • PUBLIC

De plus, des avertissements et des invites s'affichent pour les niveaux d'accès suivants lorsque vous ne les augmentez pas avec des filtres utilisant auth.uid :

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

Pour en savoir plus sur l'autorisation, consultez le guide sur l'autorisation et l'attestation.

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 pour utiliser les SDK Web, les SDK Android et les SDK iOS.

Commande Description

firebase dataconnect:sdk:generate

Option Description

– regarder

Maintient le processus en cours d'exécution et génère de nouveaux SDK chaque fois que vous enregistrez des modifications apportées à vos fichiers GQL de schéma et de connecteur.

Si la génération échoue, les 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 indicateurs –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

Data Connect fonctionne sur votre propre instance PostgreSQL hébergée sur Cloud SQL. Les commandes de rôle SQL vous aident à gérer les autorisations sur les tables de votre base de données.

dataconnect:sql:setup

firebase dataconnect:sql:setup

Cette commande configure les autorisations globales initiales pour les tables de votre base de données.

Le flux de provisionnement et de gestion de base de données par défaut suppose que votre projet utilise une nouvelle base de données (greenfield). Lorsque vous appelez firebase deploy, Data Connect affiche les modifications de schéma de base de données à apporter et effectue les migrations après votre approbation. Si vous préférez ce flux, dataconnect:sql:setup vous invite à accorder des autorisations, y compris les droits de propriété du schéma superuser.

Pour les bases de données existantes (brownfield), vous pouvez avoir votre propre workflow pour migrer les schémas et vouloir conserver vous-même la propriété des schémas. Si vous préférez ce flux, assurez-vous de refuser l'invite dataconnect:sql:setup vous demandant si Data Connect doit gérer les migrations SQL pour vous. Si vous refusez, Data Connect n'aura accès qu'à read et write de vos tables de base de données, mais vous resterez responsable des propriétés et des migrations de schéma.

Pour en savoir plus et découvrir d'autres cas d'utilisation, consultez Gérer les services et les bases de données.

dataconnect:sql:grant

firebase dataconnect:sql:grant

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 devrez attribuer l'un des rôles définis dans cette section à l'utilisateur ou au compte de service concerné.

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

Rôle Rôle SQL Autorisations Utilisation Autorisable
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 ont besoin de récupérer des données, mais pas de les modifier. 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 aux services qui doivent modifier des données dans la base de données. Oui
owner firebaseowner_<db_name>_<schema_name> Propriétaire du schéma.

 Dispose de tous les droits d'accès 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 sur la base de données.

 Par exemple, lorsque vous appelez 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 et supprimer des schémas, installer des extensions et effectuer toute autre tâche administrative.

 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 privilèges de super-utilisateur, la migration échouera et l'utilisateur sera 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ée aux utilisateurs disposant de roles/cloudsql.admin et ne pouvant pas être accordée directement à partir de l'interface de ligne de commande Firebase
Commande Description

firebase dataconnect:sql:grant

Indicateur/Paramètre Description

-R, --role role

Rôle SQL à accorder (propriétaire, rédacteur ou lecteur).

-E, --email email_address

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 permet de passer la sortie de l'interface de ligne de commande au format JSON pour l'analyse par d'autres outils.
  • --noninteractive et --interactive remplacent, si nécessaire, la détection automatique des environnements non-TTY.