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

Un servizio Firebase Data Connect è costituito da tre componenti principali:

  • Un database PostgreSQL sottostante con il proprio schema SQL
  • uno schema di applicazione Data Connect (dichiarato nei file .gql)
  • un numero di connettori (dichiarati nei file .gql).

Lo schema SQL è la fonte attendibile dei dati, lo schema Data Connect è il modo in cui i connettori possono vedere questi dati e i connettori dichiarano le API che i client possono utilizzare per accedere ai 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 ciascun connettore.

Concetti importanti di deployment

Per comprendere appieno il deployment, è importante prendere nota dei 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 eseguire la migrazione dei tuoi schemi durante il deployment, indipendentemente dal fatto che tu stia utilizzando un nuovo database o debba adattare in modo non distruttivo un database esistente.

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 quest'ultimo possa essere aggiornato. Tutte le tabelle o le 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.

    Con compatibile si intende che le migrazioni dello schema influiscono solo sulle tabelle e sulle colonne a cui si fa riferimento nello schema dell'applicazione. Gli elementi del database che non vengono utilizzati dallo schema dell'applicazione vengono lasciati invariati. Pertanto, dopo il deployment, il 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 contrario, quando vengono implementate, queste operazioni Data Connect vengono archiviate sul server, ad esempio Cloud Functions. Ciò significa che il deployment potrebbe interrompere gli utenti esistenti.

Segui il flusso di lavoro di deployment

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

Un flusso di deployment consigliato prevede:

  1. Elenco di schemi e connettori attualmente di cui è stato eseguito il deployment con firebase dataconnect:services:list.
  2. Gestire 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. Esegui deployment di schema e connessione eseguendo firebase deploy, per solo lo schema, solo i connettori o combinazioni di risorse.

Esegui il deployment e gestisci le risorse Data Connect

Ti consigliamo di 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 di Data Connect dagli altri prodotti nel tuo progetto.

Deployment normale

firebase deploy --only dataconnect

In questo normale deployment, l'interfaccia a riga di comando Firebase tenta di eseguire il deployment dello schema e dei connettori.

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

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

--force deployment del flag

firebase deploy --only dataconnect --force

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

Il deployment di --force controlla comunque se lo schema SQL corrisponde allo schema Data Connect, avvisa di incompatibilità e richiede.

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 determinato servizio:

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, controlla una versione precedente del codice e implementala. Se il deployment originale includeva modifiche distruttive, potresti non essere in grado di recuperare completamente i dati eliminati.

Esegui la migrazione degli schemi di database

Se stai creando rapidamente prototipi, esegui esperimenti 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 aggiornamento.

Confronta 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 corrente del database Cloud SQL corrispondente. Se esiste una differenza, vengono stampati i comandi SQL che verranno eseguiti per correggerla.

Applica le modifiche

Quando hai finito e vuoi 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 visualizzati comandi di migrazione SQL e richieste di azione.

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 è applicare tutte le modifiche allo schema del database richieste dallo schema dell'applicazione, quindi ti chiede di approvare operazioni facoltative che eliminano schemi, tabelle o colonne per forzare lo schema del database a corrispondere esattamente allo 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 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 ulteriori informazioni, consulta il riferimento all'interfaccia a riga di comando di Data Connect.

Best practice per la gestione di schemi e connettori

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

Riduci al minimo le modifiche che provocano un errore

  • Firebase consiglia di mantenere i file dello schema e del connettore Data Connect nel controllo del codice sorgente.
  • Se possibile, evita le modifiche che provocano errori. Ecco alcuni esempi comuni di modifiche che comportano interruzioni:
    • Rimozione di un campo dallo schema
    • Impostare un campo nullable nello schema come non nullable (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 e esegui il deployment della modifica.
    • Aggiorna le app in modo che utilizzino gli SDK appena generati.
    • Infine, rimuovi il campo nel file dello schema .gql, esegui la migrazione dello schema SQL e esegui di nuovo il deployment.

Utilizza la modalità rigorosa 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à compatibile se nel database sono presenti dati di produzione

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 necessarie per la migrazione dello schema.

  • DROP SCHEMA, DROP TABLE e DROP COLUMN sono considerati comandi facoltativi e non verranno generati per il piano, anche se lo schema del database contiene schemi, tabelle o colonne non definiti nello schema dell'applicazione.
  • Se la tabella di database contiene una colonna non null non inclusa nello schema dell'applicazione, la limitazione NOT NULL verrà rimossa in modo che i dati possano essere comunque aggiunti alla tabella con i connettori definiti.

Quali sono i passaggi successivi?