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 den .gql Dateien deklariert)
  • eine Reihe von Connectors (in den .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 Ihr SQL-Schema, aktualisieren dann Ihr Data Connect Schema und schließlich jeden Ihrer Connectors.

Wichtige Bereitstellungskonzepte

Um die Bereitstellung vollständig zu verstehen, müssen Sie die wichtigsten Konzepte zu Schemas und Connectors 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.

Data Connect Schemamigrationen haben zwei verschiedene Schemavalidierungs modi: streng und kompatibel.

  • 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 mit dem Anwendungsschema kompatibel sein, bevor das Anwendungsschema aktualisiert werden kann. Zusätzliche Änderungen, durch die Schemas, Tabellen oder Spalten gelöscht 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, das nicht verwendet wird:

    • Schemas
    • Tabellen
    • 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, wie Cloud Functions. Das bedeutet, dass die Bereitstellung vorhandene Nutzer beeinträchtigen kann.

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

Die CLI analysiert Änderungen an jedem Connector in Bezug auf Ihr Schema und gibt eine Reihe von Bewertungsnachrichten zu Connector Änderungen aus, die das Clientverhalten ändern können (Nachrichten auf Warnungsebene) oder vorherige Versionen des Clientcodes möglicherweise oder mit Sicherheit beeinträchtigen (Nachrichten auf Breaking-Ebene).

Beispiel:

  • Connector-Änderungen, die das Clientverhalten ändern können, sind beispielsweise das Entfernen eines Nullable-Felds aus einer Abfrage ohne @retired-Schemaanmerkung.
  • Connector-Änderungen, die Clients möglicherweise oder mit Sicherheit beeinträchtigen, sind beispielsweise das Ändern einer Nullable-Vorgangsvariable in „Nicht null“ ohne Standardwert oder das Ändern des Datentyps eines Felds in etwas Inkompatibles (z.B. String in Int).

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

Deployment-Workflow folgen

Sie können sowohl in einem lokalen Projekt verzeichnis als auch in der Firebase Console 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. Verwalten von Schemaaktualisierungen.
    1. Nach Unterschieden im SQL-Schema zwischen Ihrer Cloud SQL Datenbank und dem lokalen Data Connect Schema mit firebase dataconnect:sql:diff suchen.
    2. Bei Bedarf SQL-Schemamigration mit dataconnect:sql:migrate durchführen.
  3. Schema- und Connector-Bereitstellungen durch Ausführen von firebase deploy durchführen, 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 Produktionsumgebung bereitzustellen.

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

Normale Bereitstellung

firebase deploy --only dataconnect

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

Es wird geprüft, ob das neue Schema keine vorhandenen Connectors beeinträchtigt. Befolgen Sie Best Practices bei Breaking Changes.

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

Bereitstellung mit dem Flag --force

firebase deploy --only dataconnect --force

Wenn Sie sich keine Sorgen um die Validierung des Connectors oder des SQL-Schemas machen, können Sie den Befehl mit --force noch einmal ausführen, um sie zu ignorieren.

Bei der Bereitstellung mit --force wird weiterhin geprüft, ob das SQL-Schema mit dem Data Connect Schema übereinstimmt, und Sie werden bei Inkompatibilität gewarnt und aufgefordert, eine Aktion auszuführen.

Ausgewählte Ressourcen bereitstellen

Verwenden Sie das Flag --only mit dem Argument serviceId, um die Bereitstellung genauer zu steuern. 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

Bereitstellung zurücksetzen

Für ein manuelles Rollback rufen Sie eine frühere Version Ihres Codes ab und stellen Sie sie bereit. Wenn die ursprüngliche Bereitstellung destruktive Breaking Changes 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 die Durchführung der Updates zu überwachen.

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 ausgeführt werden müssten, um diesen Unterschied zu beheben.

Änderungen übernehmen

Wenn Sie zufrieden sind und Änderungen an der Schema-Cloud SQL-Instanz bereitstellen möchten, führen Sie den Befehl firebase dataconnect:sql:migrate aus. Sie werden aufgefordert, die Ä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 neuen Projekt wird der Standardmodus für die Schemavalidierung angewendet. Der Befehl migrate wendet alle Datenbank-Schemaänderungen an, die für Ihr Anwendungsschema erforderlich sind, und fordert Sie dann auf, optionale Vorgänge zu genehmigen, durch die 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 Schlüssels schemaValidation 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 Ihr Datenbankschema mit Ihrem Anwendungsschema übereinstimmt.

schemaValidation: "STRICT"

Weitere Informationen finden Sie in der Data Connect CLI-Referenz.

Connectors aktualisieren

Wenn Sie firebase deploy ausführen, initiiert die CLI eine Aktualisierung der entsprechenden Connectors und gibt entsprechende Bewertungsnachrichten auf Warnungs- (kann sich auf das Clientverhalten auswirken) und Breaking-Ebene (möglicherweise oder mit Sicherheit beeinträchtigend) aus.

Connector-Updates mit der CLI verwalten

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

Wie erwartet, fordert die CLI Sie im interaktiven Modus auf, 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 stellt die CLI Ihren Connector bereit, solange es keine Bewertungen auf Breaking-Ebene gibt. Andernfalls wird Ihr Skript mit einem Log der Breaking Changes beendet. Sie können die Bereitstellung überschreiben und erzwingen, indem Sie das Flag --force festlegen.

# 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 CLI-Referenzleitfaden.

Best Practices für die Verwaltung von Schemas und Connectors

Firebase empfiehlt einige Best Practices für Ihre Data Connect Projekte.

Breaking Changes minimieren

  • Firebase empfiehlt, Ihre Data Connect Schema- und Connector Dateien in der Versionsverwaltung zu speichern.
  • Vermeiden Sie Breaking Changes, wenn möglich. Einige häufige Beispiele für Breaking Changes:
    • Entfernen eines Felds aus Ihrem Schema
    • Ändern eines Nullable-Felds in Ihrem Schema in „Nicht null“ (z. B. Int -> Int!)
    • Umbenennen eines Felds in Ihrem Schema
  • 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, um neu generierte SDKs zu verwenden.
    • Entfernen Sie schließlich das Feld in Ihrer .gql-Schemadatei, migrieren Sie Ihr SQL-Schema und stellen Sie es noch einmal bereit.

Im strengen Modus arbeiten, wenn Sie neue 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 in Ihrer dataconnect.yaml-Datei schemaValidation: "STRICT" angeben.

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

Kompatiblen Modus verwenden, wenn Ihre Datenbank Produktionsdaten enthält

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

Im kompatiblen Modus werden nur erforderliche Änderungen an der Schemamigration auf Ihre Datenbank angewendet.

  • DROP SCHEMA, DROP TABLE und DROP COLUMN gelten als 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 vom Typ „Nicht null“ enthält, die nicht in Ihrem Anwendungsschema enthalten ist, wird die Einschränkung NOT NULL entfernt, sodass mit den von Ihnen definierten Connectors weiterhin Daten zur Tabelle hinzugefügt werden können.

Nächste Schritte