Data Connect-Schemas und ‑Connectors bereitstellen und verwalten

Ein Firebase Data Connect-Dienst hat drei Hauptkomponenten:

  • Eine zugrunde liegende PostgreSQL-Datenbank mit einem eigenen SQL-Schema
  • ein Data Connect Anwendungsschema (in Ihren .gql-Dateien deklariert)
  • eine Reihe von Connectors (in Ihren .gql-Dateien deklariert, in connector.yaml-Dateien konfiguriert).

Das SQL-Schema ist die Quelle der Wahrheit für Ihre Daten, das Data Connect-Schema gibt an, wie Ihre Connectors diese Daten sehen können, und die Connectors deklarieren die APIs, die Ihre Clients für den Zugriff auf diese Daten verwenden können.

Wenn Sie Ihren Data Connect-Dienst mit der CLI bereitstellen, migrieren Sie zuerst Ihr SQL-Schema, aktualisieren dann Ihr Data Connect-Schema und aktualisieren dann jeden Ihrer Connectors.

Wichtige Bereitstellungskonzepte

Um die Bereitstellung vollständig zu verstehen, ist es wichtig, die wichtigsten Konzepte zu Schemas und Connectors zu kennen.

Schemabereitstellungen

Die Bereitstellung eines Data Connect-Schemas wirkt sich auf das SQL-Schema für Ihre Cloud SQL-Datenbank aus. Data Connect hilft Ihnen, Ihre Schemas während der Bereitstellung zu migrieren, unabhängig davon, ob Sie mit einer neuen Datenbank arbeiten oder eine vorhandene Datenbank nicht destruktiv anpassen müssen.

Für Data Connect-Schemamigrationen gibt es zwei verschiedene Schemavalidierungsmodi: strict und compatible.

  • Für die Validierung im strengen Modus muss das Datenbankschema genau mit dem Anwendungsschema übereinstimmen, bevor das Anwendungsschema aktualisiert werden kann. Alle Tabellen oder Spalten, die nicht in Ihrem Data Connect-Schema verwendet werden, werden aus der Datenbank gelöscht.

  • Für die Validierung im kompatiblen Modus muss das Datenbankschema kompatibel mit dem Anwendungsschema sein, bevor das Anwendungsschema aktualisiert werden kann. Alle zusätzlichen Änderungen, bei denen Schemas, Tabellen oder Spalten entfernt werden, sind optional.

    „Kompatibel“ bedeutet, dass sich Schemamigrationen nur auf Tabellen und Spalten auswirken, auf die in Ihrem Anwendungsschema verwiesen wird. Elemente in Ihrer Datenbank, die nicht von Ihrem Anwendungsschema verwendet werden, bleiben unverändert. Daher kann Ihre Datenbank nach der Bereitstellung Folgendes enthalten:

    • Schemas
    • Tables
    • Spalten

Connector-Bereitstellungen

Data Connect-Abfragen und ‑Mutationen werden nicht vom Clientcode gesendet und auf dem Server ausgeführt. Stattdessen werden diese Data Connect-Vorgänge bei der Bereitstellung auf dem Server gespeichert, z. B. Cloud Functions. Das bedeutet, dass die Bereitstellung bestehende Nutzer beeinträchtigen kann.

Data Connect integriert die Analyse von Breaking Changes in Ihren Connector-Updates in die Firebase-Befehlszeile.

Die CLI analysiert Änderungen an jedem Connector in Bezug auf Ihr Schema und gibt eine Reihe von Prüfnachrichten zu Connector-Änderungen aus, die das Clientverhalten ändern (Nachrichten auf Warnstufe) oder vorherige Versionen des Clientcodes beschädigen können (Nachrichten auf Fehlerstufe).

Beispiel:

  • Zu Connector-Änderungen, die das Clientverhalten ändern können, gehört das Entfernen eines Nullable-Felds aus einer Abfrage ohne die Schemaanmerkung @retired.
  • Zu Connector-Änderungen, die Clients möglicherweise oder tatsächlich beeinträchtigen, gehören das Ändern einer nullable-Operationsvariablen in „non-null“ ohne Standardwert oder das Ändern des Datentyps eines Felds in einen inkompatiblen Typ (z.B. String in Int).

Eine ausführlichere Liste von Szenarien auf Warn- und Breaking-Ebene finden Sie im CLI-Referenzhandbuch.

Workflow für die Bereitstellung ausführen

Sie können sowohl in einem lokalen Projektverzeichnis als auch in der Firebase-Konsole an einem Data Connect-Projekt arbeiten.

Ein empfohlener Bereitstellungsablauf umfasst Folgendes:

  1. Auflisten der derzeit bereitgestellten Schemas und Connectors mit firebase dataconnect:services:list.
  2. Schemaaktualisierungen verwalten.
    1. Prüfen Sie mit firebase dataconnect:sql:diff, ob es Unterschiede zwischen dem SQL-Schema Ihrer Cloud SQL-Datenbank und dem lokalen Data Connect-Schema gibt.
    2. Führen Sie bei Bedarf die SQL-Schemamigration mit dataconnect:sql:migrate durch.
  3. Schema- und Connector-Bereitstellungen können mit dem Befehl firebase deploy ausgeführt werden, entweder nur für Ihr Schema, nur für Ihre Connectors oder für Kombinationen von Ressourcen.

Data Connect-Ressourcen bereitstellen und verwalten

Es empfiehlt sich, Produktionsressourcen vor der Bereitstellung zu überprüfen.

firebase dataconnect:services:list

Wenn Sie in einem lokalen Projektverzeichnis arbeiten, verwenden Sie in der Regel den Befehl firebase deploy, um Ihr Schema und Ihre Connectors mit interaktivem Feedback in der Produktion bereitzustellen.

Mit dem Flag --only dataconnect können Sie mit einem beliebigen deploy-Befehl Data Connect-Bereitstellungen von anderen Produkten in Ihrem Projekt trennen.

Normale Bereitstellung

firebase deploy --only dataconnect

Bei dieser normalen Bereitstellung versucht die Firebase CLI, Ihr Schema und Ihre Connectors bereitzustellen.

Es wird geprüft, ob das neue Schema vorhandene Connectors beeinträchtigt. Halten Sie sich bei grundlegenden Änderungen an die Best Practices.

Außerdem wird geprüft, ob das SQL-Schema bereits migriert wurde, bevor das Data Connect-Schema aktualisiert wird. Andernfalls werden Sie automatisch durch alle erforderlichen Schritte zur Migration von Schemas geführt.

Bereitstellung des --force-Flags

firebase deploy --only dataconnect --force

Wenn weder die Connector- noch die SQL-Schema-Validierungen ein Problem darstellen, können Sie den Befehl mit --force noch einmal ausführen, um sie zu ignorieren.

Beim --force-Deployment wird weiterhin geprüft, ob das SQL-Schema mit dem Data Connect-Schema übereinstimmt. Bei Inkompatibilität wird eine Warnung ausgegeben und der Nutzer wird aufgefordert, das Problem zu beheben.

Ausgewählte Ressourcen bereitstellen

Wenn Sie die Bereitstellung genauer steuern möchten, verwenden Sie das Flag --only mit dem Argument serviceId. So stellen Sie nur Schemaänderungen für einen bestimmten Dienst bereit:

firebase deploy --only dataconnect:serviceId:schema

Sie können auch alle Ressourcen für einen bestimmten Connector und Dienst bereitstellen.

firebase deploy --only dataconnect:serviceId:connectorId

Schließlich können Sie das Schema und alle Connectors für einen einzelnen Dienst bereitstellen.

firebase deploy --only dataconnect:serviceId

Deployment rückgängig machen

Für ein manuelles Rollback müssen Sie eine frühere Version Ihres Codes auschecken und bereitstellen. Wenn die ursprüngliche Bereitstellung destruktive Änderungen enthielt, können Sie möglicherweise nicht alle gelöschten Daten vollständig wiederherstellen.

Datenbankschemas migrieren

Wenn Sie schnell Prototypen erstellen, mit Schemas experimentieren und wissen, dass Ihre Schemaänderungen destruktiv sind, können Sie Data Connect-Tools verwenden, um die Änderungen zu überprüfen und zu überwachen, wie die Updates ausgeführt werden.

SQL-Schemaänderungen vergleichen

Sie können Änderungen so überprüfen:

firebase dataconnect:sql:diff

Sie können eine durch Kommas getrennte Liste von Diensten übergeben.

Mit dem Befehl wird das lokale Schema für einen Dienst mit dem aktuellen Schema der entsprechenden Cloud SQL-Datenbank verglichen. Wenn es einen Unterschied gibt, werden die SQL-Befehle ausgegeben, die zum Beheben dieses Unterschieds ausgeführt werden.

Änderungen übernehmen

Wenn Sie zufrieden sind und bereit sind, Änderungen an der Cloud SQL-Instanz des Schemas bereitzustellen, führen Sie den Befehl firebase dataconnect:sql:migrate aus. Sie werden aufgefordert, Änderungen zu genehmigen.

firebase dataconnect:sql:migrate [serviceId]

In interaktiven Umgebungen werden SQL-Migrationsanweisungen und Aktionsaufforderungen angezeigt.

Im strengen oder kompatiblen Modus migrieren

In einem brandneuen Projekt gilt der Standard-Schema-Validierungsmodus. Der Befehl migrate wendet alle Datenbankschemaänderungen an, die für Ihr Anwendungsschema erforderlich sind, und fordert Sie dann auf, optionale Vorgänge zu genehmigen, mit denen Schemas, Tabellen oder Spalten gelöscht werden, damit Ihr Datenbankschema genau mit Ihrem Anwendungsschema übereinstimmt.

Sie können dieses Verhalten anpassen, indem Sie die Datei dataconnect.yaml ändern. Entfernen Sie die Auskommentierung des schemaValidation-Schlüssels und deklarieren Sie COMPATIBLE, damit bei Migrationen nur erforderliche Änderungen angewendet werden.

schemaValidation: "COMPATIBLE"

Alternativ können Sie das Verhalten auf STRICT festlegen, damit alle Schemaänderungen angewendet werden und das Datenbankschema an das Anwendungsschema angepasst wird.

schemaValidation: "STRICT"

Weitere Informationen finden Sie in der Data Connect-Befehlszeilenreferenz.

Connectors aktualisieren

Wenn Sie firebase deploy ausführen, wird mit der CLI ein Update der entsprechenden Connectors initiiert und es werden entsprechende Meldungen zur Bewertung auf Warnungsebene (kann sich auf das Clientverhalten auswirken) und auf Breaking-Ebene (möglicherweise oder sicher Breaking) ausgegeben.

Connector-Updates mit der CLI verwalten

Die CLI verhält sich im interaktiven und nicht interaktiven Modus etwas anders.

Wie zu erwarten, werden Sie im interaktiven Modus von der CLI aufgefordert, alle Nachrichten zu akzeptieren. Sie können die Connector-Bereitstellung mit dem Flag --force überschreiben und erzwingen.

# 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

Im nicht interaktiven Modus wird Ihr Connector über die CLI bereitgestellt, sofern keine Bewertungen auf Breaking-Ebene vorhanden sind. Andernfalls wird das Skript mit einem Log der Breaking Changes beendet. Sie können die Überschreibung und Bereitstellung durch Festlegen des Flags --force erzwingen.

# 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

Weitere Informationen finden Sie im Referenzhandbuch für die Befehlszeile.

Best Practices für die Verwaltung von Schemas und Connectors

Firebase empfiehlt einige Vorgehensweisen für Ihre Data Connect-Projekte.

Nicht abwärtskompatible Änderungen minimieren

  • Firebase empfiehlt, das Data Connect-Schema und die Connector-Dateien in der Versionsverwaltung zu speichern.
  • Vermeiden Sie nach Möglichkeit funktionsgefährdende Änderungen. Hier einige häufige Beispiele für Breaking Changes:
    • Feld aus dem Schema entfernen
    • Ein Feld, das Nullwerte zulässt, in Ihrem Schema so ändern, dass es keine Nullwerte zulässt (d. h. Int -> Int!)
    • Sie benennen ein Feld in Ihrem Schema um.
  • Wenn Sie ein Feld aus Ihrem Schema entfernen müssen, sollten Sie es in mehrere Bereitstellungen aufteilen, um die Auswirkungen zu minimieren:
    • Entfernen Sie zuerst alle Verweise auf das Feld in Ihren Connectors und stellen Sie die Änderung bereit.
    • Aktualisieren Sie dann Ihre Apps, damit sie die neu generierten SDKs verwenden.
    • Entfernen Sie das Feld schließlich aus der Datei .gql Ihres Schemas, migrieren Sie Ihr SQL-Schema und stellen Sie die App noch einmal bereit.

Strengen Modus bei der Arbeit mit neuen Datenbanken verwenden

Wenn Sie Data Connect mit einer neuen Datenbank verwenden und Ihr Anwendungsschema aktiv entwickeln und sicherstellen möchten, dass Ihr Datenbankschema genau mit Ihrem Anwendungsschema übereinstimmt, können Sie schemaValidation: "STRICT" in Ihrer dataconnect.yaml angeben.

So wird sichergestellt, dass auch optionale Änderungen angewendet werden.

Kompatibilitätsmodus verwenden, wenn Produktionsdaten in der Datenbank vorhanden sind

Wenn Sie Änderungen an einer Datenbank mit Produktionsdaten vornehmen, empfehlen wir, die Schemamigrationen im kompatiblen Modus auszuführen, damit keine vorhandenen Daten gelöscht werden. Sie können schemaValidation: "COMPATIBLE" in Ihrer dataconnect.yaml angeben.

Im Kompatibilitätsmodus werden nur erforderliche Schemaänderungen auf Ihre Datenbank angewendet.

  • DROP SCHEMA, DROP TABLE und DROP COLUMN sind optionale Anweisungen und werden nicht für Ihren Plan generiert, auch wenn Ihr Datenbankschema Schemas, Tabellen oder Spalten enthält, die nicht in Ihrem Anwendungsschema definiert sind.
  • Wenn Ihre Datenbanktabelle eine Spalte enthält, die nicht null ist und nicht in Ihrem Anwendungsschema enthalten ist, wird die NOT NULL-Einschränkung entfernt, sodass der Tabelle weiterhin Daten mit Ihren definierten Connectors hinzugefügt werden können.

Nächste Schritte