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 il proprio schema SQL.
  • Uno Data Connect schema dell'applicazione (dichiarato nei file .gql).
  • Un numero di connettori (dichiarati nei file .gql, configurati nei file connector.yaml).

Lo schema SQL è l'origine di riferimento per i dati, lo Data Connect schema è 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, poi aggiorni lo schema Data Connect e infine aggiorni ciascuno dei connettori.

Concetti di deployment importanti

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 database Cloud SQL. Data Connect ti aiuta a migrare gli 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.

Data Connect le migrazioni dello schema hanno due diverse modalità di convalida dello schema: strict e compatible.

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

  • La convalida in modalità Compatible 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 fa riferimento lo schema dell'applicazione. Gli elementi del database non utilizzati dallo schema dell'applicazione rimangono invariati. Pertanto, dopo il deployment, il database potrebbe contenere elementi non utilizzati:

    • Schemi
    • Tabelle
    • Colonne

Deployment del connettore

Data Connect query e mutazioni non vengono inviate dal codice client ed eseguite sul server. Quando vengono sottoposte a deployment, queste Data Connect operazioni vengono archiviate sul server, come Cloud Functions. Ciò significa che il deployment potrebbe interrompere il funzionamento per gli utenti esistenti.

Data Connect integra l'analisi delle modifiche che causano interruzioni negli aggiornamenti dei connettori nella Firebase CLI.

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

Ad esempio:

  • Le modifiche del connettore che potrebbero alterare il comportamento del client includono la rimozione di un campo nullable da una query senza un'annotazione dello schema @retired.
  • Le modifiche del connettore che potrebbero o interromperanno il funzionamento dei client includono la modifica di una variabile di 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).

Nella guida di riferimento della CLI è riportato un elenco più completo di scenari a livello di avviso e di interruzione.

Segui il flusso di lavoro di deployment

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

Un flusso di deployment consigliato prevede:

  1. Elencare gli schemi e i connettori attualmente sottoposti a deployment con firebase dataconnect:services:list.
  2. Gestire gli aggiornamenti dello schema.
    1. Verificare 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. Eseguire il deployment dello schema e della connessione eseguendo firebase deploy, solo per lo schema, solo per i connettori o per 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 ti consente di separare i deployment Data Connect da altri prodotti del progetto.

Deployment normale

firebase deploy --only dataconnect

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

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

Verifica anche che la migrazione dello schema SQL sia già stata eseguita prima di aggiornare lo Data Connect schema. In caso contrario, ti guida automaticamente attraverso i passaggi necessari per eseguire la migrazione degli schemi.

Deployment del flag --force

firebase deploy --only dataconnect --force

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

Il deployment --force verifica comunque se lo schema SQL corrisponde allo schema Data Connect avvisa in caso di incompatibilità e ti chiede di eseguire l'operazione.

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 dello schema per un servizio specifico:

firebase deploy --only dataconnect:serviceId:schema

Puoi anche eseguire il deployment di tutte le risorse per un connettore e un servizio 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

Esegui il rollback di un deployment

Per eseguire un rollback manuale, estrai una versione precedente del codice ed eseguine il deployment. Se il deployment originale includeva modifiche che causano interruzioni distruttive, potresti non essere in grado di recuperare completamente i dati eliminati.

Esegui la migrazione degli schemi di database

Se stai prototipando rapidamente, sperimentando con gli schemi e sai che le modifiche dello schema sono distruttive, puoi pianificare l'utilizzo degli strumenti Data Connect per verificare le modifiche e supervisionare l'esecuzione degli aggiornamenti.

Visualizza le modifiche dello 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 c'è una differenza, stampa i comandi SQL che verrebbero eseguiti per correggere la differenza.

Applica le modifiche

Quando sei soddisfatto e pronto a eseguire il deployment delle modifiche all'istanza Cloud SQL dello schema, 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 le richieste di azione.

Esegui la migrazione in modalità Strict o Compatible

In un progetto nuovo, viene applicata la modalità di convalida dello schema. Il comportamento del comando migrate consiste nell'applicare tutte le modifiche dello 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 nelle migrazioni vengano applicate solo le modifiche obbligatorie.

schemaValidation: "COMPATIBLE"

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

schemaValidation: "STRICT"

Per maggiori informazioni, consulta la documentazione di riferimento della Data Connect CLI.

Aggiorna i 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 a livello di interruzione (probabilmente o sicuramente interruzione).

Gestisci gli aggiornamenti dei connettori con la CLI

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

Come previsto, 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 esegue 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 maggiori informazioni, consulta la guida di riferimento della CLI.

Best practice per la gestione di schemi e connettori

Firebase consiglia di seguire alcune pratiche nei progetti Data Connect.

Riduci al minimo le modifiche che causano interruzioni

  • Firebase consiglia di conservare i file dello Data Connect schema e del connettore nel controllo della sorgente.
  • Se possibile, evita le modifiche che causano interruzioni. Di seguito sono riportati alcuni esempi comuni di modifiche che causano interruzioni:
    • Rimozione di un campo dallo schema
    • Rendere non nullable un campo nullable nello schema (ad es. Int -> Int!)
    • Rinominare un campo nello schema.
  • Se devi rimuovere un campo dallo schema, valuta la possibilità di suddividerlo in alcuni deployment per ridurre al minimo l'impatto:
    • Innanzitutto, rimuovi tutti i riferimenti al campo nei connettori ed esegui il deployment della modifica.
    • Poi, aggiorna le app in modo che utilizzino gli SDK appena generati.
    • Infine, rimuovi il campo nel file .gql dello schema, esegui la migrazione dello schema SQL ed esegui di nuovo il deployment.

Utilizza la modalità StrictMode quando lavori con nuovi database

Se utilizzi Data Connect con un nuovo database e stai sviluppando 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à Compatible 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à Compatible per assicurarti che i dati esistenti non vengano eliminati. Puoi specificare schemaValidation: "COMPATIBLE" in dataconnect.yaml.

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

  • DROP SCHEMA, DROP TABLE e DROP COLUMN sono considerati 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 null 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