Esegui il deployment e la gestione di schemi e connettori di Data Connect

Un servizio Firebase Data Connect ha tre componenti principali:

  • Un database PostgreSQL sottostante con un proprio schema SQL
  • uno schema dell'applicazione (dichiarato nei file .gql)Data Connect
  • un numero di connettori (dichiarati nei file .gql, configurati nei file connector.yaml).

Lo schema SQL è l'origine attendibile dei tuoi dati, lo schema Data Connect è il modo in cui i connettori possono visualizzare i dati e i connettori dichiarano le API che i client possono utilizzare per accedere a questi dati.

Quando esegui il deployment del servizio Data Connect con la CLI, esegui la migrazione dello schema SQL, aggiorna lo schema Data Connect e poi aggiorna ciascun connettore.

Concetti importanti relativi al deployment

Per comprendere appieno il deployment, è importante notare i concetti chiave relativi a schemi e connettori.

Deployment dello schema

Il deployment di uno schema Data Connect influisce sullo schema SQL del tuo database Cloud SQL. Data Connect ti aiuta a eseguire la migrazione degli schemi durante il deployment, sia che tu stia lavorando con un nuovo database sia che tu debba adattare in modo non distruttivo un database esistente.

Le migrazioni dello schema Data Connect hanno due diverse modalità di convalida dello schema: rigida e compatibile.

  • La convalida in modalità Strict richiede che lo schema del database corrisponda esattamente allo schema dell'applicazione prima che quest'ultimo possa essere aggiornato. Tutte le tabelle o colonne non utilizzate nello schema Data Connect verranno eliminate dal database.

  • La convalida della modalità compatibile richiede che lo schema del database sia compatibile con lo schema dell'applicazione prima che quest'ultimo possa essere aggiornato; eventuali modifiche aggiuntive che eliminano schemi, tabelle o colonne sono facoltative.

    Compatibile significa che le migrazioni dello schema influiscono solo sulle tabelle e sulle colonne a cui viene fatto riferimento nello schema dell'applicazione. Gli elementi del database non utilizzati dallo schema dell'applicazione vengono lasciati invariati. Pertanto, dopo il deployment, il tuo database potrebbe contenere:

    • Schemi
    • Tabelle
    • Colonne

Deployment dei connettori

Le query e le mutazioni Data Connect non vengono inviate dal codice client ed eseguite sul server. Al momento del deployment, queste operazioni Data Connect vengono archiviate sul server, come Cloud Functions. Ciò significa che il deployment potrebbe interrompere l'accesso per gli utenti esistenti.

Data Connect integra l'analisi delle modifiche che causano interruzioni negli aggiornamenti dei connettori nell'interfaccia a riga di comando Firebase.

La CLI analizza le modifiche apportate a ogni connettore rispetto al tuo schema ed emette un insieme di messaggi di valutazione relativi alle modifiche del connettore che potrebbero alterare il comportamento del client (i messaggi sono di livello di avviso) o potrebbero o interromperanno (i messaggi sono di livello di interruzione) le versioni precedenti del codice client.

Ad esempio:

  • Le modifiche al connettore che potrebbero alterare il comportamento del client includono la rimozione di un campo accettante valori null da una query senza un'annotazione dello schema @retired.
  • Le modifiche al connettore che potrebbero o che interromperanno i client includono la modifica di una variabile dell'operazione Nullable in non Null senza un valore predefinito o la modifica del tipo di dati di un campo in qualcosa di incompatibile (ad es. String in Int).

Un elenco più completo di scenari a livello di avviso e di interruzione è disponibile nella guida di riferimento della CLI.

Segui il flusso di lavoro di deployment

Puoi lavorare a un progetto Data Connect sia in una directory di progetto locale sia nella console Firebase.

Un flusso di deployment consigliato prevede:

  1. Elenco degli schemi e dei connettori attualmente implementati con firebase dataconnect:services:list.
  2. Gestione di eventuali aggiornamenti dello schema.
    1. Verifica le differenze dello schema SQL tra il database Cloud SQL e lo schema Data Connect locale con firebase dataconnect:sql:diff.
    2. Se necessario, esegui la migrazione dello schema SQL con dataconnect:sql:migrate.
  3. Eseguendo deployment di schemi e connessioni eseguendo firebase deploy, per il solo schema, i soli connettori o combinazioni di risorse.

Esegui il deployment e gestisci le risorse Data Connect

È consigliabile verificare le risorse di produzione prima di eseguire i deployment.

firebase dataconnect:services:list

Quando lavori in una directory di progetto locale, in genere utilizzi il comando firebase deploy per eseguire il deployment dello schema e dei connettori in produzione, con feedback interattivo.

Utilizzando qualsiasi comando deploy, il flag --only dataconnect consente di separare i deployment Data Connect dagli altri prodotti del progetto.

Deployment normale

firebase deploy --only dataconnect

In questo deployment normale, la CLI Firebase tenta di eseguire il deployment dello schema e dei connettori.

Verifica che il nuovo schema non interrompa i connettori esistenti. Segui le best practice quando apporti modifiche che causano interruzioni.

Verifica inoltre che lo schema SQL sia già stato migrato prima di aggiornare lo schema Data Connect. In caso contrario, ti guida automaticamente attraverso i passaggi necessari per migrare gli schemi.

--force deployment dei flag

firebase deploy --only dataconnect --force

Se le convalide dello schema del connettore o SQL non ti preoccupano, puoi eseguire nuovamente il comando con --force per ignorarle.

Il deployment --force verifica comunque se lo schema SQL corrisponde allo schema Data Connect, avvisa di incompatibilità e richiede l'intervento dell'utente.

Esegui il deployment delle risorse selezionate

Per eseguire il deployment con un controllo più granulare, utilizza il flag --only con l'argomento serviceId. Per eseguire il deployment solo delle modifiche allo schema per un servizio specifico:

firebase deploy --only dataconnect:serviceId:schema

Puoi anche eseguire il deployment di tutte le risorse per un servizio e un connettore specifici.

firebase deploy --only dataconnect:serviceId:connectorId

Infine, puoi eseguire il deployment dello schema e di tutti i connettori per un singolo servizio.

firebase deploy --only dataconnect:serviceId

Eseguire il rollback di un deployment

Per eseguire un rollback manuale, controlla una versione precedente del codice e implementala. Se l'implementazione originale includeva modifiche distruttive, potresti non essere in grado di recuperare completamente i dati eliminati.

Esegui la migrazione degli schemi di database

Se crei prototipi rapidamente, sperimenti con gli schemi e sai che le modifiche allo schema sono distruttive, puoi pianificare l'utilizzo degli strumenti Data Connect per verificare le modifiche e supervisionare la modalità di esecuzione degli aggiornamenti.

Visualizzare le differenze tra le modifiche allo schema SQL

Puoi verificare le modifiche:

firebase dataconnect:sql:diff

Puoi passare un elenco di servizi separati da virgole.

Il comando confronta lo schema locale di un servizio con lo schema attuale del database Cloud SQL corrispondente. Se viene rilevata una differenza, vengono stampati i comandi SQL che verranno eseguiti per risolvere il problema.

Applica le modifiche

Quando sei soddisfatto e pronto a implementare le modifiche allo schema dell'istanza Cloud SQL, esegui il comando firebase dataconnect:sql:migrate. Ti verrà chiesto di approvare le modifiche.

firebase dataconnect:sql:migrate [serviceId]

Negli ambienti interattivi, vengono visualizzate le istruzioni di migrazione SQL e i prompt di azione.

Eseguire la migrazione in modalità rigorosa o compatibile

In un progetto nuovo di zecca, viene applicata la modalità di convalida dello schema predefinita. Il comportamento del comando migrate consiste nell'applicare tutte le modifiche allo schema del database richieste dallo schema dell'applicazione, quindi ti chiede di approvare le operazioni facoltative che eliminano schemi, tabelle o colonne per forzare la corrispondenza esatta tra lo schema del database e lo schema dell'applicazione.

Puoi modificare questo comportamento modificando il file dataconnect.yaml. Rimuovi il commento dalla chiave schemaValidation e dichiara COMPATIBLE in modo che solo le modifiche richieste vengano applicate nelle migrazioni.

schemaValidation: "COMPATIBLE"

In alternativa, imposta il comportamento su STRICT in modo che tutte le modifiche allo schema vengano applicate e lo schema del database venga forzato in modo che corrisponda allo schema dell'applicazione.

schemaValidation: "STRICT"

Per maggiori informazioni, consulta il riferimento all'interfaccia a riga di comando Data Connect.

Aggiornamento connettori

Quando esegui firebase deploy, la CLI avvia un aggiornamento dei connettori applicabili ed emette messaggi di valutazione a livello di avviso (potrebbe influire sul comportamento del client) e di interruzione (interruzione possibile o certa).

Gestire gli aggiornamenti dei connettori con la CLI

La CLI ha un comportamento leggermente diverso in modalità interattiva e non interattiva.

Come puoi immaginare, in modalità interattiva, la CLI ti chiede di accettare tutti i messaggi. Puoi eseguire l'override e forzare il deployment del connettore con il flag --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

In modalità non interattiva, la CLI eseguirà il deployment del connettore a condizione che non siano presenti valutazioni a livello di interruzione. In caso contrario, lo script verrà chiuso con un log delle modifiche che causano interruzioni. Puoi eseguire l'override e il deployment impostando il flag --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

Per ulteriori informazioni, consulta la guida di riferimento della CLI.

Best practice per la gestione di schemi e connettori

Firebase consiglia alcune pratiche da seguire nei tuoi progetti Data Connect.

Ridurre al minimo le modifiche che provocano un errore

  • Firebase consiglia di mantenere i file di schema e connettore Data Connect nel controllo del codice sorgente.
  • Evita modifiche che provocano errori, se possibile. Alcuni esempi comuni di modifiche che causano interruzioni includono:
    • Rimuovere un campo dallo schema
    • Rendere un campo nullable nello schema non nullable (ad es. Int -> Int!)
    • Rinominare un campo nello schema.
  • Se devi rimuovere un campo dallo schema, valuta la possibilità di suddividerlo in più deployment per ridurre al minimo l'impatto:
    • Innanzitutto, rimuovi tutti i riferimenti al campo nei connettori e implementa la modifica.
    • Poi, aggiorna le tue app in modo che utilizzino gli SDK appena generati.
    • Infine, rimuovi il campo nel file .gql dello schema, esegui la migrazione dello schema SQL e il deployment di nuovo.

Utilizza la modalità rigorosa quando lavori con nuovi database

Se utilizzi Data Connect con un nuovo database e sviluppi attivamente lo schema dell'applicazione e vuoi assicurarti che lo schema del database rimanga esattamente in linea con lo schema dell'applicazione, puoi specificare schemaValidation: "STRICT" in dataconnect.yaml.

In questo modo, verranno applicate anche le modifiche facoltative.

Utilizza la modalità compatibile quando hai dati di produzione nel database

Se apporti modifiche a un database che contiene dati di produzione, ti consigliamo di eseguire le migrazioni dello schema in modalità compatibile per assicurarti che i dati esistenti non vengano eliminati. Puoi specificare schemaValidation: "COMPATIBLE" nel tuo dataconnect.yaml.

In modalità compatibile, al database vengono applicate solo le modifiche di migrazione dello schema richieste.

  • DROP SCHEMA, DROP TABLE e DROP COLUMN sono considerate istruzioni facoltative e non verranno generate per il tuo piano, anche se lo schema del database contiene schemi, tabelle o colonne non definiti nello schema dell'applicazione.
  • Se la tabella del database contiene una colonna non nulla che non è inclusa nello schema dell'applicazione, il vincolo NOT NULL verrà rimosso, in modo che i dati possano comunque essere aggiunti alla tabella con i connettori definiti.

Passaggi successivi