Riferimento ai comandi dell'interfaccia a riga di comando di Firebase per Data Connect

Firebase CLI è uno strumento che ti consente di gestire e configurare i prodotti e i servizi Firebase dalla riga di comando.

La CLI fornisce comandi che possono essere utilizzati per eseguire una serie di attività di Data Connect, ad esempio creare un nuovo progetto Data Connect, inizializzare una directory di lavoro locale corrispondente, configurare l'emulatore Data Connect, elencare le risorse Data Connect, generare SDK client e altro ancora.

Comandi di configurazione

Aggiungere Data Connect a un progetto Firebase

firebase init

Usa firebase init per configurare una nuova configurazione del progetto locale. Questo flusso di lavoro crea o aggiorna i file di configurazione di Firebase nella directory.

firebase init

Il flusso firebase init ti guida nella configurazione di un servizio e di un database, nonché, facoltativamente, nell'installazione dell'emulatore firebase init e nella configurazione degli SDK generati.Data Connect

Configurazione del servizio e del database

Se selezioni dataconnect per la configurazione del prodotto, l'interfaccia a riga di comando ti chiede un nuovo nome e una nuova posizione del servizio e se collegare un'istanza Cloud SQL per PostgreSQL esistente o crearne una nuova.

Se è collegata un'istanza esistente, la CLI controlla la presenza di impostazioni compatibili, come l'autenticazione IAM e gli indirizzi IP pubblici.

Configurazione di Local Emulator Suite

Il flusso dell'interfaccia a riga di comando offre la possibilità di configurare gli emulatori, incluso l'emulatore Data Connect.

Data Connect comandi dell'emulatore

Avvia l'emulatore Data Connect

emulators:start/exec

firebase emulators:start/exec

Utilizza la versione Local Emulator Suite dell'emulatore Data Connect in modalità interattiva con start o in modalità non interattiva basata su script con exec.

Esportare e importare i dati PostgreSQL locali

Per supportare la prototipazione e i test locali e l'integrazione continua, puoi esportare i dati archiviati in un'istanza di database locale e importarli tra le iterazioni di sviluppo e le esecuzioni di test.

Le esportazioni vengono archiviate come snapshot del database PostgreSQL locale.

Data Connect offre tre approcci all'esportazione/all'importazione:

  • Esportazione/importazione automatica configurata in firebase.json per fornire backup degli snapshot all'arresto e all'avvio dell'emulatore
  • Esportazione/importazione manuale tramite l'interfaccia a riga di comando
  • Esportazione/importazione manuale utilizzando l'interfaccia dell'estensione VS Code

Esportazione e importazione automatiche configurate in firebase.json

Per eseguire il backup dei dati tra le sessioni di sviluppo, specifica una posizione di backup automatico durante la sequenza firebase init. Questa posizione è memorizzata nel tuo firebase.json nel campo emulators.dataconnect.dataDir. Le modifiche ai dati apportate verranno salvate automaticamente qui tra le esecuzioni dell'emulatore, pertanto è utile durante i test e le esplorazioni locali.

Esportazione manuale: emulators:export e emulators:start/exec --import

Mentre l'emulatore Data Connect è in esecuzione, in un terminale separato, esegui il comando firebase emulators:export per salvare uno snapshot dei dati. Dopodiché puoi avviare l'emulatore da questo snapshot utilizzando il flag --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>

Esportazione/importazione manuale: estensione VS Code

Nell'interfaccia utente dell'estensione VS Code, mentre l'emulatore è in esecuzione, utilizza il pulsante Esporta dati dell'emulatore per esportare i dati per esportare i contenuti del database corrente. La posizione di esportazione predefinita è la directory exportedData nella directory principale del progetto.

Puoi importare questi dati utilizzando l'interfaccia a riga di comando, come descritto nella sezione precedente. Puoi anche importare questi dati prima di avviare l'emulatore tramite VS Code facendo clic sul link Configura emulatore e impostando Percorso di importazione.

Comandi per la gestione di schemi e connettori

Questa sezione contiene informazioni di riferimento della CLI per i comandi che utilizzi per gestire schemi e connettori.

Per casi d'uso e best practice consigliate relativi a questi comandi, consulta la guida alla gestione di schemi e connettori.

Esegui il deployment di schemi e connettori

esegui il deployment

firebase deploy

Questo comando esegue il deployment delle risorse per i servizi Data Connect indicizzati in firebase.json. Se necessario, vengono eseguite una migrazione dello schema e un aggiornamento del connettore.

Comando Descrizione

firebase deploy

Bandiera Descrizione

–-only dataconnect

Esegui il deployment di schemi e connettori per tutti i servizi Data Connect per questo progetto, ma non per altre risorse dei prodotti Firebase.

–-only dataconnect:serviceId

Esegui il deployment dello schema e dei connettori per il servizio Data Connect specificato.

–-only dataconnect:serviceId:connectorId

Esegui il deployment di un singolo connettore per il servizio Data Connect specificato.

–-only dataconnect:serviceId:schema

Esegui il deployment dello schema per il servizio Data Connect specificato.

Con i flag –-only, puoi passare valori separati da virgole per eseguire il deployment di qualsiasi sottoinsieme di risorse.

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

Elenca i servizi, gli schemi e i connettori Data Connect

dataconnect:services:list

firebase dataconnect:services:list

Questo comando stampa informazioni di base su servizi, schemi e connettori impiegati in un progetto.

Confronta ed esegui la migrazione degli schemi SQL

Quando esegui firebase deploy, l'interfaccia a riga di comando esegue un confronto dello schema SQL prima di implementare gli aggiornamenti. Puoi anche eseguire il confronto e l'aggiornamento direttamente con un insieme di comandi dataconnect:sql.

dataconnect:sql:diff

firebase dataconnect:sql:diff

Questo comando confronta lo schema locale di un servizio con lo schema corrente del database Cloud SQL corrispondente. Stampa i comandi che verranno eseguiti per eseguire la migrazione del database al nuovo schema.

Comando Descrizione

firebase dataconnect:sql:diff

Flag/parametro Descrizione

serviceId

Specifica il servizio. Se omesso, stampa la differenza per tutti i servizi in firebase.json.

dataconnect:sql:migrate

firebase dataconnect:sql:migrate

Questo comando applica le modifiche dello schema locale al database Cloud SQL di un servizio.

Quando configuri un nuovo progetto Data Connect locale con il file dataconnect.yaml predefinito, il comportamento del comando dataconnect:sql:migrate è chiederti le modifiche necessarie e poi quelle facoltative prima di eseguirle. Puoi modificare questo comportamento in modo da includere o ignorare sempre le modifiche facoltative aggiornando la configurazione di dataconnect.yaml, come descritto in Eseguire la migrazione di uno schema in modalità rigorosa o compatibile.

Negli ambienti interattivi, l'interfaccia a riga di comando mostra ogni istruzione SQL di migrazione (e se è distruttiva) e chiede le modifiche da applicare. Il passaggio del flag --force è equivalente all'accettazione di tutti i prompt.

In ambienti non interattivi:

  • Senza --force, vengono apportate solo modifiche non distruttive. Se sono presenti modifiche dannose, l'interfaccia a riga di comando viene interrotta senza apportare modifiche.
  • Con --force, vengono apportate tutte le modifiche. Se sono incluse modifiche dannose, queste vengono stampate e ti viene chiesto se vuoi continuare, a meno che non venga fornito il flag --force.
Comando Descrizione

firebase dataconnect:sql:migrate

Bandiera Descrizione

serviceId

Esegui la migrazione del database per il servizio specificato. Il valore serviceId viene ricavato se il progetto ha un solo servizio.

–-force

Accettare automaticamente i prompt.

Come per altri flag --only, puoi fornire più servizi separati da virgole.

Eseguire la migrazione di uno schema in modalità rigorosa o compatibile

Le migrazioni dello schema Data Connect hanno due diverse modalità di convalida dello schema: rigorosa e compatibile. La convalida in modalità rigorosa richiede che lo schema del database corrisponda esattamente allo schema dell'applicazione prima che lo schema dell'applicazione possa essere implementato. La convalida della modalità compatibile richiede che lo schema del database sia compatibile con lo schema dell'applicazione, il che significa che gli elementi del database non utilizzati dallo schema dell'applicazione vengono lasciati invariati.

Queste modalità di convalida dello schema e le best practice per la migrazione dello schema sono descritte nella guida alla gestione di schemi e connettori

La modalità di convalida è definita utilizzando la chiave schemaValidation nel dataconnect.yaml file. Se schemaValidation non è specificato, la CLI applica le modifiche compatibili e ti chiede conferma prima di eseguire eventuali modifiche rigorose. Consulta la guida di riferimento alla configurazione.

Gestire le modifiche ai connettori

Quando esegui firebase deploy, l'interfaccia a riga di comando avvia un aggiornamento dei connettori applicabili. La CLI analizza le modifiche apportate a ciascun connettore e genera un insieme di messaggi di valutazione relativi alle modifiche apportate ai connettori che potrebbero causare comportamenti imprevisti (messaggi di livello avviso) o interruzioni (messaggi di livello interruzione) nelle versioni precedenti del codice client.

Valutazione dell'impatto Scenario
Livello di avviso (compatibile con cavo, il comportamento potrebbe cambiare)
  • Rimozione di un campo nullable da una query senza un'annotazione @retired.
Livello di interruzione (cavo incompatibile, potrebbe causare l'interruzione dei client)
  • Modifica di una variabile nullable in non null senza un valore predefinito.
  • Modificare il tipo di dati di un campo in modo che sia compatibile con JSON (ad es. da Int a Float).
  • Modifica di una colonna non null in una nullable.
  • Rimozione di una variabile nullable senza un'annotazione @retired.
  • Rimozione di una variabile non null con un valore predefinito senza un'annotazione @retired.
Livello di interruzione (cavo incompatibile, causerà l'interruzione dei client)
  • Rimozione di un'operazione senza un'annotazione @retired.
  • Rimozione di un campo non nullo da una query senza un'annotazione @retired.
  • Aggiunta di una variabile non null senza un valore predefinito.
  • Modificare il tipo di dati di un campo in un tipo incompatibile (ad es. da String a Int).
  • Rimozione di una variabile non null senza un valore predefinito e senza un'annotazione @retired.

Negli ambienti interattivi, la CLI mostra ogni valutazione del connettore e chiede le modifiche da applicare. Il passaggio del flag --force è equivalente all'accettazione di tutte le valutazioni.

In ambienti non interattivi:

  • Se si verificano solo valutazioni a livello di avviso (possibili modifiche del comportamento), tutti i connettori verranno di cui verranno registrati gli avvisi nel terminale.
  • Se si verificano valutazioni di livello di interruzione, non verrà eseguito il deployment di alcun connettore e gli avvisi verranno registrati nel terminale. Puoi eseguire l'override con il --force flag.

Codice di autorizzazione per la revisione

Data Connect ti aiuta a eseguire il controllo della tua strategia di autorizzazione analizzando il codice del connettore quando esegui il deployment sul server utilizzando firebase deploy dalla CLI Firebase. Puoi utilizzare questo controllo per esaminare la base di codice.

Quando esegui il deployment dei connettori, la CLI genera valutazioni per il codice di operazioni esistenti, modificate e nuove nel connettore.

Per le operazioni modificate e nuove, l'interfaccia a riga di comando emette avvisi e ti chiede conferma quando utilizzi determinati livelli di accesso nelle nuove operazioni o quando modifichi le operazioni esistenti per utilizzare questi livelli di accesso.

Gli avvisi e le richieste vengono sempre visualizzati per:

  • PUBLIC

Inoltre, vengono visualizzati avvisi e prompt nei seguenti livelli di accesso se non li aumenti con i filtri che utilizzano auth.uid:

  • USER
  • USER_ANON
  • USER_EMAIL_VERIFIED

Per ulteriori informazioni sull'autorizzazione, consulta la guida all'autorizzazione e all'attestazione.

Comandi SDK

Genera SDK

dataconnect:sdk:generate

firebase dataconnect:sdk:generate

Questo comando genera gli SDK con tipi dichiarati in connector.yaml.

Consulta anche le guide per l'utilizzo degli SDK web, degli SDK Android e degli SDK iOS.

Comando Descrizione

firebase dataconnect:sdk:generate

Bandiera Descrizione

–-watch

Mantiene in esecuzione il processo e genera nuovi SDK ogni volta che salvi le modifiche ai file GQL di schema e connettore.

Se la generazione non riesce, gli errori verranno stampati su stdout, il codice generato non verrà modificato e il comando continuerà a essere eseguito.

–-only connectorId:platform

Genera SDK solo per una singola piattaforma e un singolo connettore.

Con i flag –only, puoi passare valori separati da virgole.

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

Comandi di gestione di Cloud SQL

Concedi i ruoli SQL per Cloud SQL

Data Connect opera sulla tua istanza PostgreSQL ospitata su Cloud SQL. I comandi dei ruoli SQL ti aiutano a gestire le autorizzazioni per le tabelle del database.

dataconnect:sql:setup

firebase dataconnect:sql:setup

Questo comando configura le autorizzazioni globali iniziali per le tabelle nel database.

Il flusso di provisioning e gestione del database predefinito presuppone che il progetto utilizzi un nuovo database (greenfield) e, quando richiami firebase deploy, Data Connect mostrerà le modifiche dello schema del database da apportare ed eseguirà eventuali migrazioni dopo la tua approvazione. Se questo è il flusso che preferisci, dataconnect:sql:setup ti chiede di concedere le autorizzazioni, tra cui la proprietà dello schema di superuser.

Per i database esistenti (brownfield), potresti avere un tuo flusso di lavoro per la migrazione degli schemi e voler mantenere la proprietà dello schema. Se questo è il flusso che preferisci, assicurati di rifiutare quando dataconnect:sql:setup ti chiede se Data Connect deve gestire le migrazioni SQL per te. A seguito del rifiuto, Data Connect acquisirà solo l'accesso read e write alle tabelle del database, ma le migrazioni e la proprietà dello schema rimarranno di tua responsabilità.

Per ulteriori discussioni e casi d'uso, consulta Gestire servizi e database.

dataconnect:sql:grant

firebase dataconnect:sql:grant

In alcuni casi, potresti voler accedere direttamente al database per eseguire query o aggiornare i dati generati dalle tue app Data Connect. Per farlo, devi concedere uno dei ruoli definiti in questa sezione all'utente o all'account di servizio necessario.

Per informazioni dettagliate sui ruoli concessi, consulta Ruoli utente PostgreSQL.

Ruolo Ruolo SQL Autorizzazioni Utilizzo Concedibile
Lettore firebasereader_<db_name>_<schema_name> Accesso di sola lettura al database.

Può eseguire operazioni SELECT su tutte le tabelle all'interno dello schema specificato.		 Ideale per utenti o servizi che richiedono il recupero dei dati, ma non la loro modifica. Sì
writer firebasewriter_<db_name>_<schema_name> Accesso in lettura e scrittura al database.

Può eseguire operazioni SELECT, INSERT, UPDATE, DELETE e TRUNCATE su tutte le tabelle all'interno dello schema.		 Adatto a utenti o servizi che devono modificare i dati all'interno del database. Sì
proprietario firebaseowner_<db_name>_<schema_name> Proprietario dello schema.

Ha tutti i privilegi su tutte le tabelle e le sequenze nello schema.		 Questo ruolo, in combinazione con il ruolo IAM roles/cloudsql.client, concede l'autorizzazione per eseguire la migrazione sul database.

Ad esempio, quando chiami firebase dataconnect:sql:migrate.		 Sì
super user cloudsqlsuperuser Ruolo superutente integrato con privilegi completi sul database.

Oltre alle autorizzazioni del proprietario, può creare schemi, eliminarli, installare estensioni ed eseguire qualsiasi altra attività amministrativa.

Accesso nell'interfaccia a riga di comando accedendo come "firebasesuperuser".		 Obbligatorio per installare le estensioni, creare lo schema iniziale e concedere a altri utenti uno dei ruoli SQL concedibili.

Se un utente non amministratore ha bisogno di privilegi di superutente, la migrazione non andrà a buon fine e l'utente verrà invitato a chiedere all'amministratore del database (ovvero a un utente con roles/cloudsql.admin) di eseguire i comandi SQL con privilegi.		 Concessi agli utenti con roles/cloudsql.admin e non possono essere concessi direttamente dalla CLI Firebase
Comando Descrizione

firebase dataconnect:sql:grant

Flag/parametro Descrizione

-R, --role ruolo

Il ruolo SQL da concedere, uno dei seguenti: proprietario, autore o lettore.

-E, --email indirizzo_email

Indirizzo email di un utente o di un account di servizio a cui concedere il ruolo.

Opzioni globali

Le seguenti opzioni globali si applicano a tutti i comandi:

  • --json imposta l'output della CLI su JSON per l'analisi da parte di altri strumenti.
  • --noninteractive e --interactive sostituiscono, se necessario, il rilevamento automatico degli ambienti non TTY.