Data Connect-Schemas und ‑Connectors bereitstellen und verwalten

Ein Firebase Data Connect-Dienst besteht aus drei Hauptkomponenten:

  • Eine zugrunde liegende PostgreSQL-Datenbank mit einem eigenen SQL-Schema
  • ein Data Connect-Anwendungsschema (deklariert in den .gql-Dateien)
  • über mehrere Connectors, die in deinen .gql-Dateien deklariert sind.

Das SQL-Schema ist die "Source of Truth" für Ihre Daten. Das Schema Data Connect gibt an, wie Ihre Connectors diese Daten sehen können und die Connectors die APIs deklarieren, mit denen Ihre Clients auf diese Daten zugreifen können.

Wenn Sie Ihren Data Connect-Dienst über die Befehlszeile bereitstellen, migrieren Sie Ihr SQL-Schema, aktualisieren dann das Data Connect-Schema und anschließend jeden Ihrer Connectors.

Wichtige Bereitstellungskonzepte

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

Schemabereitstellungen

Die Bereitstellung eines Data Connect-Schemas wirkt sich auf das SQL-Schema für Ihre Cloud SQL-Datenbank aus. Mit Data Connect können Sie Ihre Schemas während der Bereitstellung migriert werden, unabhängig davon, ob Sie mit einer neuen Datenbank arbeiten oder eine vorhandene Datenbank nicht zerstörend anpassen müssen.

Data Connect-Schemamigrationen haben zwei verschiedene Schemavalidierungsmodi: strikt und kompatibel.

  • Im strikten 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 des kompatiblen Modus muss das Datenbankschema mit dem Anwendungsschema kompatibel sein, bevor das Anwendungsschema aktualisiert werden kann. Alle weiteren Ä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:

    • 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 für bestehende Nutzer möglicherweise nicht funktioniert.

Deployment-Workflow ausführen

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

Ein empfohlener Bereitstellungsablauf umfasst:

  1. Derzeit bereitgestellte Schemas und Connectors mit firebase dataconnect:services:list auflisten
  2. Schemaupdates verwalten
    1. Prüfen Sie mit firebase dataconnect:sql:diff, ob sich das SQL-Schema zwischen Ihrer Cloud SQL-Datenbank und dem lokalen Data Connect-Schema unterscheidet.
    2. Führen Sie bei Bedarf eine SQL-Schemamigration mit dataconnect:sql:migrate aus.
  3. Führen Sie Schema- und Verbindungsbereitstellungen aus, indem Sie firebase deploy entweder nur für Ihr Schema, nur für Ihre Connectors oder für Kombinationen von Ressourcen ausführen.

Data Connect-Ressourcen bereitstellen und verwalten

Es empfiehlt sich, Produktionsressourcen zu prüfen, bevor Sie Bereitstellungen ausführen.

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 Verbindungen mit interaktivem Feedback in der Produktion bereitzustellen.

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

Normale Bereitstellung

firebase deploy --only dataconnect

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

Dabei wird geprüft, ob das neue Schema vorhandene Connectors nicht abbricht. Beachten Sie bei bahnbrechenden Änderungen 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.

--force-Flag-Bereitstellung

firebase deploy --only dataconnect --force

Wenn weder die Validierung des Connectors noch die SQL-Schemavalidierung ein Problem sind, können Sie den Befehl mit --force noch einmal ausführen, um sie zu ignorieren.

Beim --force-Bereitstellen wird weiterhin geprüft, ob das SQL-Schema mit dem Data Connect-Schema übereinstimmt. Außerdem werden Inkompatibilitäten erkannt und entsprechende Aufforderungen angezeigt.

Ausgewählte Ressourcen bereitstellen

Wenn Sie die Bereitstellung detaillierter 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

Wenn Sie ein manuelles Rollback ausführen möchten, rufen Sie eine vorherige Version Ihres Codes ab und implementieren Sie sie. Wenn die ursprüngliche Bereitstellung zerstörerische Änderungen umfasste, können Sie die gelöschten Daten möglicherweise nicht vollständig wiederherstellen.

Datenbankschemata migrieren

Wenn Sie schnell Prototypen erstellen, mit Schemas experimentieren und wissen, dass Ihre Schemaänderungen zerstörerisch 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

So können Sie Änderungen prüfen:

firebase dataconnect:sql:diff

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

Der Befehl vergleicht das lokale Schema für einen Dienst mit dem aktuellen Schema der entsprechenden Cloud SQL-Datenbank. Falls ein Unterschied besteht, werden die SQL-Befehle ausgegeben, die zur Behebung des Unterschieds ausgeführt werden würden.

Änderungen übernehmen

Wenn Sie mit den Änderungen zufrieden sind und sie in der Cloud SQL-Instanz des Schemas bereitstellen möchten, geben Sie den Befehl firebase dataconnect:sql:migrate ein. Sie werden aufgefordert, Änderungen zu genehmigen.

firebase dataconnect:sql:migrate [serviceId]

In interaktiven Umgebungen werden SQL-Migrationsanweisungen und Aufforderungen zu Aktionen angezeigt.

Migration im strengen oder kompatiblen Modus

In einem brandneuen Projekt gilt der standardmäßige 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, bei 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 dataconnect.yaml-Datei ändern. Entfernen Sie die Kommentarzeichen des Schlüssels schemaValidation und deklarieren Sie COMPATIBLE, damit bei Migrationen nur die erforderlichen Änderungen angewendet werden.

schemaValidation: "COMPATIBLE"

Alternativ können Sie das Verhalten auf STRICT festlegen, damit alle Schemaänderungen angewendet werden und das Datenbankschema mit dem Anwendungsschema übereinstimmt.

schemaValidation: "STRICT"

Weitere Informationen finden Sie in der Data Connect-Befehlszeilenreferenz.

Best Practices für das Verwalten von Schemas und Verbindungen

Firebase empfiehlt einige Vorgehensweisen, die Sie in Ihren Data Connect-Projekten beachten sollten.

funktionsgefährdende Änderungen minimieren

  • Firebase empfiehlt, die Data Connect-Schema- und ‑Verbindungsdateien in der Versionskontrolle zu verwalten.
  • Vermeiden Sie nach Möglichkeit funktionsgefährdende Änderungen. Beispiele für solche Änderungen:
    • Feld aus dem Schema entfernen
    • Ein Feld in Ihrem Schema, für das Nullwerte zulässig sind, so ändern, dass keine Nullwerte zulässig sind (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 implementieren Sie die Änderung.
    • Aktualisieren Sie als Nächstes Ihre Apps, um neu generierte SDKs zu verwenden.
    • Entfernen Sie abschließend das Feld in der Schemadatei .gql, migrieren Sie das SQL-Schema und stellen Sie es noch einmal bereit.

strengen Modus bei der Arbeit mit neuen Datenbanken verwenden

Wenn Sie Data Connect mit einer neuen Datenbank verwenden, Ihr Anwendungsschema aktiv entwickeln und 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.

Kompatiblen Modus verwenden, wenn Produktionsdaten in der Datenbank vorhanden sind

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 Ihrem dataconnect.yaml angeben.

Im Kompatibilitätsmodus werden nur die erforderlichen Änderungen für die Schemamigration auf Ihre Datenbank angewendet.

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

Nächste Schritte