Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Questa pagina descrive come gestire le modifiche allo schema del database Spanner con Liquibase per i database con dialetto Google SQL e PostgreSQL.
Liquibase è una libreria open source indipendente dal database per monitorare, gestire e applicare le modifiche allo schema del database. Supporta SQL e formati dichiarativi come XML, YAML e JSON.
Liquibase può avere come target i database Spanner. Supporta tutte le funzionalità di Spanner, con alcune limitazioni.
Per conoscere le limitazioni generali, vedi limitazioni.
Per ulteriori informazioni sui database in dialetto PostgreSQL, ad esempio i requisiti di Liquibase, i tipi di modifiche supportati e le limitazioni, consulta
PGAdapter e Liquibase.
Installa Liquibase
Per utilizzare Liquibase con i database in dialetto Google SQL, devi installare l'estensione Liquibase di Spanner. Per i database in dialetto PostgreSQL, Liquibase può utilizzare il proprio supporto PostgreSQL integrato in combinazione con PGAdapter.
GoogleSQL
Segui le istruzioni riportate nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del database. Nel file di configurazione liquibase.properties, imposta la proprietà url come segue.
Vai alla pagina delle release dell'estensione Liquibase di Spanner su GitHub e seleziona l'ultima release.
Seleziona e scarica il file JAR con il nome
liquibase-spanner-x.y.z-all.jar, dove x.y.z rappresenta il numero di versione
dell'estensione. Ad esempio, liquibase-spanner-4.17.0-all.jar.
Inserisci il file JAR scaricato nella directory lib di Liquibase. Il file JAR include l'estensione, l'SDK Spanner e il driver JDBC Spanner.
PostgreSQL
Assicurati che PGAdapter sia avviato ed eseguito sulla macchina su cui installi Liquibase. Per ulteriori informazioni, consulta Avvia
PGAdapter.
Segui le istruzioni riportate nella documentazione di Liquibase per installare e configurare Liquibase e acquisire uno snapshot del database.
Nel file di configurazione liquibase.properties, imposta la proprietà url come segue.
Il file di configurazione liquibase.properties può contenere solo questa proprietà. Le altre proprietà sono facoltative.
La stringa url deve includere
options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
perché Spanner non supporta le transazioni DDL e questo
garantisce che le transazioni DDL vengano convertite in batch DDL. Per ulteriori informazioni, consulta Opzioni DDL per PGAdapter.
Esamina gli esempi di Liquibase
GoogleSQL
Il file di log delle modifiche di esempio changelog.yaml incluso con l'estensione Liquibase di GoogleSQL mostra molte delle funzionalità di Liquibase e come utilizzarle con Spanner.
PostgreSQL
Il file di log delle modifiche di esempio dbchangelog.xml disponibile nel
repository GitHub di PGAdapter e Liquibase
dimostra molte delle funzionalità di Liquibase e come utilizzarle con
Spanner.
Guida rapida di Liquibase
Questa guida rapida mostra come utilizzare Liquibase per aggiungere una tabella Singers a un database.
Prima di iniziare
Assicurati di aver completato i passaggi precedenti per installare
Liquibase.
Crea un'istanza di Spanner.
Crea un database con il dialetto Google SQL o PostgreSQL.
Solo per i database in dialetto PostgreSQL, assicurati che PGAdapter sia avviato e in esecuzione sulla stessa macchina dell'installazione di Liquibase. Per ulteriori informazioni, consulta
Avvia PGAdapter.
Solo per i database in dialetto PostgreSQL, utilizza lo script create_database_change_log.sql per creare le tabelle di metadati databasechangeloglock e databasechangelog. Devi creare queste tabelle per sostituire quelle create automaticamente da Liquibase nel tuo database. Questo serve ad assicurarti che in queste tabelle vengano utilizzati i tipi di dati PostgreSQL corretti per Spanner.
Questo file YAML definisce una tabella denominata Singers con una chiave primaria SingerId e una colonna denominata Name per memorizzare il nome del cantante.
Per i database in dialetto PostgreSQL, consigliamo di utilizzare solo lettere minuscole per i nomi di tabelle e colonne. Per ulteriori informazioni, consulta
Sensibilità alle maiuscole di PostgreSQL.
Tieni presente che il set di modifiche createTable deve includere una limitazione della chiave principale e il nome della limitazione della chiave principale deve essere pk_table_name.
Salva le modifiche come changelog.yaml.
Esegui Liquibase
Applica il set di modifiche in changelog.yaml eseguendo il seguente comando:
liquibase --changeLogFile changelog.yaml update
Liquibase utilizza l'URL definito nel file liquibase.properties. Puoi sovrascrivere il valore nel file aggiungendo il seguente argomento al comando precedente:
--url URL
Verifica le modifiche
Gli aggiornamenti nel passaggio precedente hanno causato l'aggiunta della tabella Singer al database. Inoltre, le tabelle DATABASECHANGELOG e DATABASECHANGELOGLOCK sono state aggiunte (database in dialetto GoogleSQL) o aggiornate (database in dialetto PostgreSQL).
Puoi verificare l'esistenza di queste tabelle tramite la Google Cloud console
o gcloud CLI. Ad esempio, l'esecuzione della query SQL SELECT * FROM
INFORMATION_SCHEMA.TABLES restituisce un elenco di tutte le tabelle del database.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 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)."]]
