Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Auf dieser Seite wird beschrieben, wie Sie Änderungen am Spanner-Datenbankschema mit Liquibase für Datenbanken mit Google SQL- und PostgreSQL-Dialekt verwalten.
Liquibase ist eine Open-Source-Datenbank-unabhängige Bibliothek zum Nachverfolgen, Verwalten und Anwenden von Datenbankschemaänderungen. Es unterstützt sowohl SQL als auch deklarative Formate wie XML, YAML und JSON.
Liquibase kann auf Spanner-Datenbanken ausgerichtet werden. Es unterstützt alle Spanner-Funktionen, mit einigen Einschränkungen.
Allgemeine Einschränkungen finden Sie unter Einschränkungen.
Weitere Informationen zu Datenbanken mit PostgreSQL-Dialekt, z. B. Liquibase-Anforderungen, unterstützte Änderungstypen und Einschränkungen, finden Sie unter
PGAdapter und Liquibase.
Liquibase installieren
Wenn Sie Liquibase mit Datenbanken im GoogleSQL-Dialekt 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
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 so fest:
Rufen Sie auf GitHub die Releaseseite für die Liquibase-Erweiterung für Spanner auf und wählen Sie neuesten Release aus.
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.
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.
PostgreSQL
PGAdapter muss auf dem Computer gestartet und ausgeführt werden, auf dem Sie Liquibase installieren. Weitere Informationen finden Sie unter PGAdapter starten.
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 unten beschrieben fest.
Die Konfigurationsdatei liquibase.properties darf nur dieses Attribut enthalten. Andere Properties sind optional.
Der url-String muss options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction enthalten, da Spanner keine DDL-Transaktionen unterstützt. So werden DDL-Transaktionen in DDL-Batches umgewandelt. Weitere Informationen finden Sie unter DDL-Optionen für PGAdapter.
Liquibase-Beispiele ansehen
GoogleSQL
Die Beispieldatei für das Änderungsprotokoll changelog.yaml, die in der Liquibase-Erweiterung für GoogleSQL enthalten ist, zeigt viele Funktionen von Liquibase und deren Verwendung mit Spanner.
PostgreSQL
Die Beispieldatei für das Änderungsprotokoll dbchangelog.xml, die im GitHub-Repository von PGAdapter und Liquibase verfügbar ist, zeigt viele Funktionen von Liquibase und deren Verwendung mit Spanner.
Kurzanleitung zu Liquibase
In dieser Kurzanleitung erfahren Sie, wie Sie mit Liquibase einer Datenbank eine Singers-Tabelle hinzufügen.
Erstellen Sie eine Datenbank im GoogleSQL- oder PostgreSQL-Dialekt.
Nur für Datenbanken mit PostgreSQL-Dialekt: PGAdapter muss auf demselben Computer wie Ihre Liquibase-Installation gestartet und ausgeführt werden. Weitere Informationen finden Sie unter PGAdapter starten.
Verwenden Sie das Script create_database_change_log.sql nur für PostgreSQL-Datenbanken, um die Metadatentabellen databasechangeloglock und databasechangelog zu erstellen. Sie müssen diese Tabellen erstellen, um die Tabellen zu überschreiben, die Liquibase automatisch in Ihrer Datenbank erstellt. So wird sichergestellt, dass in diesen Tabellen die richtigen PostgreSQL-Datentypen für Spanner verwendet werden.
Sie können das Script mit dem folgenden Befehl ausführen:
Gewähren Sie der Spanner Liquibase-Erweiterung die vorübergehende 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
Geben Sie den folgenden YAML-Code in Ihren bevorzugten Editor ein.
In dieser YAML-Datei wird eine Tabelle namens Singers mit dem Primärschlüssel SingerId und der Spalte Name zum Speichern des Namens des Sängers definiert.
Der createTable-Änderungssatz muss eine Primärschlüsseleinschränkung enthalten und der Name der Primärschlüsseleinschränkung muss pk_table_name sein.
Speichern Sie die Änderungen als changelog.yaml.
Liquibase ausführen
Wenden Sie die Änderungsliste 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 der Tabelle Singer Ihrer Datenbank hinzugefügt. Außerdem wurden die Tabellen DATABASECHANGELOG und DATABASECHANGELOGLOCK hinzugefügt (Datenbank mit GoogleSQL-Dialekt) oder aktualisiert (Datenbank mit PostgreSQL-Dialekt).
Sie können die Existenz dieser Tabellen über die Google Cloud Console oder die gcloud-Befehlszeile 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.
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-09-05 (UTC)."],[],[],null,["# Integrate Spanner with Liquibase\n\nThis page describes how to manage Spanner database schema changes\nwith [Liquibase](https://www.liquibase.org/) for GoogleSQL-dialect databases and PostgreSQL-dialect databases.\n\nLiquibase is an open-source database-independent library for tracking, managing,\nand applying database schema changes. It supports SQL as well as declarative\nformats such as XML, YAML, and JSON.\n\nLiquibase can target Spanner databases. It supports all\nSpanner features, with some limitations.\n\n- To see general limitations, see [limitations](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/limitations.md).\n- To see additional information for PostgreSQL-dialect databases, such as Liquibase requirements, supported change types, and limitations, see [PGAdapter and Liquibase](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase).\n\nInstall Liquibase\n-----------------\n\nTo use Liquibase with GoogleSQL-dialect databases, you have to install the\nSpanner Liquibase extension. For PostgreSQL-dialect databases, Liquibase can use\nits built-in PostgreSQL support in conjunction with\n[PGAdapter](/spanner/docs/pgadapter). \n\n### GoogleSQL\n\n1. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart) to install and configure Liquibase, and to take a snapshot of your database. In the `liquibase.properties` configuration file, set the `url` property as follows.\n\n```\n jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE\n \n``` \n\n Your `liquibase.properties` configuration file can contain only this\n property. Other properties are optional.\n\n1. Navigate to the Spanner Liquibase Extension releases page\n on GitHub and select the [latest release](https://github.com/cloudspannerecosystem/liquibase-spanner/releases/latest).\n\n2. Select and download the JAR file with the name\n `liquibase-spanner-x.y.z-all.jar`, where x.y.z represents the extension\n version number. For example, `liquibase-spanner-4.17.0-all.jar`.\n\n3. Place the downloaded JAR file in the Liquibase lib directory. The JAR\n file includes the extension, the Spanner SDK, and the\n Spanner JDBC driver driver.\n\n### PostgreSQL\n\n1. Ensure that PGAdapter is started and running on the machine\n where you install Liquibase. For more information, see [Start\n PGAdapter](/spanner/docs/pgadapter-start).\n\n2. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart)\n to install and configure Liquibase, and to take a snapshot of your database.\n\nIn the `liquibase.properties` configuration file, set the `url` property as\nfollows. \n\n```\n jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction\n \n```\n\nYour `liquibase.properties` configuration file can contain only this\nproperty. Other properties are optional.\n\nThe `url` string must include\n`options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction`\nbecause Spanner doesn't support DDL transactions, and this\nensures that DDL transactions are converted to DDL batches. For more\ninformation, see [DDL Options for PGAdapter](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/docs/ddl.md).\n\nReview the Liquibase samples\n----------------------------\n\n### GoogleSQL\n\nThe sample change log file [changelog.yaml](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/example/changelog.yaml) included with\nthe GoogleSQL Liquibase extension demonstrates many of the\nfeatures of Liquibase and how to use them with Spanner.\n\n### PostgreSQL\n\nThe sample change log file `dbchangelog.xml` available in the\n[PGAdapter and Liquibase GitHub repository](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase)\ndemonstrates many of the features of Liquibase and how to use them with\nSpanner.\n\nLiquibase quickstart\n--------------------\n\nThis quickstart shows you how to use Liquibase to add a `Singers` table to a\ndatabase.\n\n### Before you begin\n\n- Make sure that you have completed the preceding steps to [install](#install-liq)\n Liquibase.\n\n- Create a Spanner instance.\n\n- Create a GoogleSQL-dialect database or PostgreSQL-dialect database.\n\n- For PostgreSQL-dialect databases only, ensure that PGAdapter is started and running\n on the same machine as your Liquibase installation. For more information, see\n [Start PGAdapter](/spanner/docs/pgadapter-start).\n\n- For PostgreSQL-dialect databases only, use the [create_database_change_log.sql](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase/create_database_change_log.sql)\n script to create the `databasechangeloglock` and `databasechangelog` metadata\n tables. You must create these tables to override the tables that Liquibase\n creates automatically in your database. This is to ensure that the correct\n PostgreSQL data types for Spanner are used in these\n tables.\n\n You can run the script with the following command: \n\n ```\n psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql\n ```\n- Give the Spanner Liquibase extension temporary use of your\n Spanner user credentials for API access by running the\n following `gcloud` command:\n\n ```\n gcloud auth application-default login\n ```\n\n### Create a changelog.yaml\n\n1. Enter the following YAML into your favorite editor.\n\n databaseChangeLog:\n - preConditions:\n onFail: HALT\n onError: HALT\n\n - changeSet:\n id: create-singers-table\n author: spanner-examples\n changes:\n - createTable:\n tableName: Singers\n columns:\n - column:\n name: SingerId\n type: BIGINT\n constraints:\n primaryKey: true\n primaryKeyName: pk_Singers\n - column:\n name: Name\n type: VARCHAR(255)\n\n This YAML defines a table called `Singers` with a primary key `SingerId` and a\n column called `Name` to store the singer's name.\n\n For PostgreSQL-dialect databases, we recommend using all lower case for table and column\n names. For more information, see\n [PostgreSQL case sensitivity](/spanner/docs/reference/postgresql/lexical#case-sensitivity).\n\n Note that the `createTable` change set must include a primary key constraint,\n and the name of the primary key constraint must be pk_\u003cvar translate=\"no\"\u003etable_name\u003c/var\u003e.\n2. Save your changes as `changelog.yaml`.\n\n### Run Liquibase\n\nApply the changeset in `changelog.yaml` by executing the following command: \n\n```\nliquibase --changeLogFile changelog.yaml update\n```\n\nLiquibase uses the URL that you defined in the `liquibase.properties` file. You\ncan override the value in the file by adding the following argument to the\npreceding command: \n\n```\n--url URL\n```\n\n### Verify your changes\n\nThe updates in the preceding step caused the `Singer` table to be added to your\ndatabase. Also, the `DATABASECHANGELOG` and `DATABASECHANGELOGLOCK` tables were\nadded (GoogleSQL-dialect database) or updated (PostgreSQL-dialect database).\n\nYou can verify the existence of these tables through the Google Cloud console\nor gcloud CLI. For example, running the SQL query `SELECT * FROM\nINFORMATION_SCHEMA.TABLES` returns a list of all tables in your database. \n\n```\ngcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \\\n --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'\n```\n\nYou can see a record of the changes that were applied by querying the contents\nof `DATABASECHANGELOG`.\n\nWhat's next\n-----------\n\n- For more documentation, visit the [Spanner Liquibase Extension](https://github.com/cloudspannerecosystem/liquibase-spanner)\n GitHub repository.\n\n- To learn more about Liquibase, see [Getting Started with Liquibase](https://www.liquibase.org/get-started)."]]
