Spanner in Liquibase einbinden

Auf dieser Seite wird beschrieben, wie Sie Änderungen am Spanner-Datenbankschema mit Liquibase für Datenbanken mit GoogleSQL-Dialekt und Datenbanken mit PostgreSQL-Dialekt verwalten.

Liquibase ist eine Open-Source-Bibliothek, die unabhängig von der Datenbank ist und mit der sich Änderungen am Datenbankschema verfolgen, verwalten und anwenden lassen. Es unterstützt SQL sowie deklarative Formate wie XML, YAML und JSON.

Liquibase kann auf Spanner-Datenbanken ausgerichtet werden. Sie unterstützt alle Spanner-Funktionen, mit einigen Einschränkungen.

  • Allgemeine Einschränkungen finden Sie hier.
  • Weitere Informationen zu Datenbanken mit PostgreSQL-Dialekt, z. B. zu Liquibase-Anforderungen, unterstützten Änderungstypen und Einschränkungen, finden Sie unter PGAdapter und Liquibase.

Liquibase installieren

Wenn Sie Liquibase mit GoogleSQL-Dialektdatenbanken verwenden möchten, müssen Sie die Spanner-Liquibase-Erweiterung installieren. Für Datenbanken mit PostgreSQL-Dialekt kann Liquibase die integrierte PostgreSQL-Unterstützung in Verbindung mit PGAdapter verwenden.

GoogleSQL

  1. Folgen Sie der Anleitung in der Liquibase-Dokumentation, um Liquibase zu installieren und zu konfigurieren und einen Snapshot Ihrer Datenbank zu erstellen.

  2. Rufen Sie auf GitHub die Releaseseite für die Spanner Liquibase-Erweiterung auf und wählen Sie den neuesten Release aus.

  3. Wählen Sie die JAR-Datei mit dem Namen liquibase-spanner-x.y.z-all.jar aus und laden Sie sie herunter. Dabei steht x.y.z für die Versionsnummer der Erweiterung. Beispiel: liquibase-spanner-4.17.0-all.jar.

  4. Platzieren Sie die heruntergeladene JAR-Datei im lib-Verzeichnis von Liquibase. Die JAR-Datei enthält die Erweiterung, das Spanner SDK und den Spanner JDBC-Treiber.

Legen Sie in der Konfigurationsdatei liquibase.properties das Attribut url wie folgt fest.

 jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE

Ihre Konfigurationsdatei liquibase.properties darf nur dieses Attribut enthalten. Andere Properties sind optional.

PostgreSQL

  1. Prüfen Sie, ob PGAdapter auf dem Computer, auf dem Sie Liquibase installieren, gestartet wurde und ausgeführt wird. Weitere Informationen finden Sie unter PGAdapter starten.

  2. Folgen Sie der Anleitung in der Liquibase-Dokumentation, um Liquibase zu installieren und zu konfigurieren und einen Snapshot Ihrer Datenbank zu erstellen.

Legen Sie in der Konfigurationsdatei liquibase.properties das Attribut url wie folgt fest.

  jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction

Ihre Konfigurationsdatei liquibase.properties darf nur dieses Attribut enthalten. Andere Properties sind optional.

Der String url muss options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction enthalten, da Spanner keine DDL-Transaktionen unterstützt. Dadurch wird sichergestellt, dass DDL-Transaktionen in DDL-Batches konvertiert werden. Weitere Informationen finden Sie unter DDL-Optionen für PGAdapter.

Liquibase-Beispiele ansehen

GoogleSQL

Die Beispiel-Changelog-Datei changelog.yaml, die in der GoogleSQL-Liquibase-Erweiterung enthalten ist, zeigt viele Funktionen von Liquibase und deren Verwendung mit Spanner.

PostgreSQL

Die Beispiel-Changelog-Datei dbchangelog.xml, die im GitHub-Repository für PGAdapter und Liquibase verfügbar ist, zeigt viele Funktionen von Liquibase und deren Verwendung mit Spanner.

Liquibase-Kurzanleitung

In dieser Kurzanleitung erfahren Sie, wie Sie mit Liquibase einer Datenbank die Tabelle Singers hinzufügen.

Hinweise

  • Achten Sie darauf, dass Sie die vorherigen Schritte zum Installieren von Liquibase ausgeführt haben.

  • Erstellen Sie eine Spanner-Instanz.

  • Erstellen Sie eine Datenbank mit GoogleSQL-Dialekt oder eine Datenbank mit PostgreSQL-Dialekt.

  • Achten Sie bei Datenbanken mit PostgreSQL-Dialekt darauf, dass PGAdapter auf demselben Computer wie Ihre Liquibase-Installation gestartet wird und ausgeführt wird. Weitere Informationen finden Sie unter PGAdapter starten.

  • Verwenden Sie für Datenbanken mit PostgreSQL-Dialekt das Skript create_database_change_log.sql, um die Metadatentabellen databasechangeloglock und databasechangelog zu erstellen. Sie müssen diese Tabellen erstellen, um die Tabellen zu überschreiben, die von Liquibase automatisch in Ihrer Datenbank erstellt werden. So wird sichergestellt, dass in diesen Tabellen die richtigen PostgreSQL-Datentypen für Spanner verwendet werden.

    Sie können das Skript mit dem folgenden Befehl ausführen:

    psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql

  • Gewähren Sie der Spanner Liquibase-Erweiterung vorübergehend die Verwendung Ihrer Spanner-Nutzeranmeldedaten für den API-Zugriff, indem Sie den folgenden gcloud-Befehl ausführen:

    gcloud auth application-default login

changelog.yaml erstellen

  1. Geben Sie das folgende YAML-Manifest in Ihren bevorzugten Editor ein.

    databaseChangeLog:
  - preConditions:
     onFail: HALT
     onError: HALT

  - changeSet:
     id: create-singers-table
     author: spanner-examples
     changes:
       - createTable:
          tableName: Singers
          columns:
            -  column:
                name:    SingerId
                type:    BIGINT
                constraints:
                  primaryKey: true
                  primaryKeyName: pk_Singers
            -  column:
                name:    Name
                type:    VARCHAR(255)

    In diesem YAML wird eine Tabelle mit dem Namen Singers mit dem Primärschlüssel SingerId und einer Spalte mit dem Namen Name zum Speichern des Namens des Sängers definiert.

    Für Datenbanken mit PostgreSQL-Dialekt empfehlen wir, für Tabellen- und Spaltennamen nur Kleinbuchstaben zu verwenden. Weitere Informationen finden Sie unter Berücksichtigung der Groß-/Kleinschreibung in PostgreSQL.

    Die createTable-Änderungsmenge muss eine Primärschlüsseleinschränkung enthalten und der Name der Primärschlüsseleinschränkung muss pk_table_name sein.

  2. Speichern Sie die Änderungen als changelog.yaml.

Liquibase ausführen

Wenden Sie die Änderungsgruppe in changelog.yaml mit dem folgenden Befehl an:

liquibase --changeLogFile changelog.yaml update

Liquibase verwendet die URL, die Sie in der Datei liquibase.properties definiert haben. Sie können den Wert in der Datei überschreiben, indem Sie dem vorherigen Befehl das folgende Argument hinzufügen:

--url URL

Änderungen prüfen

Durch die Aktualisierungen im vorherigen Schritt wurde die Tabelle Singer Ihrer Datenbank hinzugefügt. Außerdem wurden die Tabellen DATABASECHANGELOG und DATABASECHANGELOGLOCK hinzugefügt (GoogleSQL-Dialekt-Datenbank) oder aktualisiert (PostgreSQL-Dialekt-Datenbank).

Sie können das Vorhandensein dieser Tabellen über die Google Cloud Console oder die gcloud CLI prüfen. Wenn Sie beispielsweise die SQL-Abfrage SELECT * FROM INFORMATION_SCHEMA.TABLES ausführen, wird eine Liste aller Tabellen in Ihrer Datenbank zurückgegeben.

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

Sie können eine Liste der angewendeten Änderungen aufrufen, indem Sie den Inhalt von DATABASECHANGELOG abfragen.

Nächste Schritte