SQL Connect-Schemas und -Connectors bereitstellen und verwalten

Ein Firebase SQL Connect Dienst hat drei Hauptkomponenten:

  • Eine zugrunde liegende PostgreSQL-Datenbank mit einem eigenen SQL-Schema
  • ein SQL 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 SQL 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 SQL Connect Dienst mit der CLI bereitstellen, migrieren Sie Ihr SQL-Schema, aktualisieren dann Ihr SQL Connect Schema und schließlich jeden Ihrer Connectors.

Wichtige Konzepte für die Bereitstellung

Um die Bereitstellung vollständig zu verstehen, müssen Sie die wichtigsten Konzepte zu Schemas und Connectors kennen.

Schemabereitstellungen

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

SQL Connect Schemamigrationen haben zwei verschiedene Schemavalidierungs modi: Streng und Kompatibel.

  • Für die Validierung 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 SQL 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:

    • Schemas
    • Tabellen
    • Spalten

Connector-Bereitstellungen

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

SQL 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önnten (Nachrichten auf Warnungsebene) oder vorherige Versionen des Clientcodes möglicherweise oder mit Sicherheit beeinträchtigen (Nachrichten auf Breaking-Ebene).

Beispiel:

  • Zu den Connector-Änderungen, die das Clientverhalten ändern könnten, gehört das Entfernen eines Nullable-Felds aus einer Abfrage ohne die Schemaanmerkung @retired.
  • Zu den Connector-Änderungen, die Clients möglicherweise oder mit Sicherheit beeinträchtigen, gehören 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 SQL Connect Projekt arbeiten.

Ein empfohlener Deployment-Ablauf umfasst Folgendes:

  1. Auflisten der derzeit bereitgestellten Schemas und Connectors mit firebase dataconnect:services:list.
  2. Verwalten von Schemaaktualisierungen.
    1. Nach Unterschieden zwischen dem SQL-Schema Ihrer Cloud SQL Datenbank und dem lokalen SQL 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 für nur Ihr Schema, nur Ihre Connectors oder Kombinationen von Ressourcen durchführen.

SQL Connect-Ressourcen bereitstellen und verwalten

Es empfiehlt sich, Produktionsressourcen zu überprüfen, bevor Sie Bereitstellungen durchfü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 Connectors mit interaktivem Feedback in der Produktion bereitzustellen.

Mit dem Flag --only dataconnect können Sie bei jedem deploy-Befehl SQL 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 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 SQL 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 von Connectors oder 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 SQL Connect Schema übereinstimmt. Sie werden vor Inkompatibilitäten gewarnt und aufgefordert, die Bereitstellung zu bestätigen.

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

Rollback eines Deployments durchführen

Für ein manuelles Rollback checken Sie eine frühere Version Ihres Codes aus und stellen 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 SQL Connect Tools verwenden, um die Änderungen zu überprüfen und die Durchführung der Updates zu überwachen.

Unterschiede bei SQL-Schemaänderungen

Sie können Änderungen so überprü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. 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, geben Sie den Befehl firebase dataconnect:sql:migrate aus. Sie werden aufgefordert, die Änderungen zu bestätigen.

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 bestätigen, 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 setzen, damit alle Schemaänderungen angewendet werden und Ihr Datenbankschema mit Ihrem Anwendungsschema übereinstimmt.

schemaValidation: "STRICT"

Weitere Informationen finden Sie in der Referenz zur SQL Connect CLI.

Connectors aktualisieren

Wenn Sie firebase deploy ausführen, initiiert die CLI ein Update 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, werden Sie im interaktiven Modus von der CLI aufgefordert, alle Nachrichten zu bestätigen. 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 mit dem Flag --force überschreiben und 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 CLI-Referenzleitfaden.

Best Practices für die Verwaltung von Schemas und Connectors

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

Breaking Changes minimieren

  • Firebase empfiehlt, Ihre SQL 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 strikten Modus arbeiten, wenn Sie neue Datenbanken verwenden

Wenn Sie SQL 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.

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

Im kompatiblen Modus arbeiten, 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, damit mit Ihren definierten Connectors weiterhin Daten zur Tabelle hinzugefügt werden können.

Nächste Schritte