Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
En esta página, se describe cómo administrar los cambios de esquema de la base de datos de Spanner con Liquibase para bases de datos de dialecto de GoogleSQL y bases de datos de dialecto de PostgreSQL.
Liquibase es una biblioteca de código abierto independiente de la base de datos para hacer un seguimiento, administrar y aplicar cambios en el esquema de la base de datos. Admite SQL y formatos declarativos, como XML, YAML y JSON.
Liquibase puede orientarse a bases de datos de Spanner. Admite todas las funciones de Spanner, con algunas limitaciones.
Para ver las limitaciones generales, consulta Limitaciones.
Para ver información adicional sobre las bases de datos de dialecto de PostgreSQL, como los requisitos de Liquibase, los tipos de cambios admitidos y las limitaciones, consulta
PGAdapter y Liquibase.
Instala Liquibase
Para usar Liquibase con bases de datos de dialecto de GoogleSQL, debes instalar la
extensión de Liquibase de Spanner. En el caso de las bases de datos con dialecto de PostgreSQL, Liquibase puede usar su compatibilidad integrada con PostgreSQL junto con PGAdapter.
GoogleSQL
Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase, y tomar un instantánea de tu base de datos. En el archivo de configuración liquibase.properties, configura la
propiedad url de la siguiente manera.
Navega a la página de lanzamientos de la extensión de Liquibase de Spanner en GitHub y selecciona la versión más reciente.
Selecciona y descarga el archivo JAR con el nombre liquibase-spanner-x.y.z-all.jar, donde x.y.z representa el número de versión de la extensión. Por ejemplo, liquibase-spanner-4.17.0-all.jar
Coloca el archivo JAR descargado en el directorio lib de Liquibase. El archivo JAR incluye la extensión, el SDK de Spanner y el controlador de JDBC de Spanner.
PostgreSQL
Asegúrate de que PGAdapter se inicie y se ejecute en la máquina
en la que instalas Liquibase. Para obtener más información, consulta Cómo iniciar PGAdapter.
Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase, y tomar una instantánea de tu base de datos.
En el archivo de configuración liquibase.properties, establece la propiedad url de la siguiente manera:
Tu archivo de configuración liquibase.properties solo puede contener esta
propiedad. Las demás propiedades son opcionales.
La cadena url debe incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque Spanner no admite transacciones DDL, lo que garantiza que las transacciones DDL se conviertan en lotes DDL. Para obtener más información, consulta Opciones de DDL para PGAdapter.
Revisa las muestras de Liquibase
GoogleSQL
El archivo de registro de cambios de muestra changelog.yaml incluido con la extensión de Liquibase de GoogleSQL demuestra muchas de las funciones de Liquibase y cómo usarlas con Spanner.
PostgreSQL
El archivo de registro de cambios de muestra dbchangelog.xml disponible en el repositorio de GitHub de PGAdapter y Liquibase demuestra muchas de las funciones de Liquibase y cómo usarlas con Spanner.
Guía de inicio rápido de Liquibase
En esta guía de inicio rápido, se muestra cómo usar Liquibase para agregar una tabla Singers a una
base de datos.
Antes de comenzar
Asegúrate de haber completado los pasos anteriores para instalar
Liquibase.
Crea una instancia de Spanner.
Crea una base de datos con el dialecto de GoogleSQL o con el dialecto de PostgreSQL.
Solo para bases de datos de dialecto PostgreSQL, asegúrate de que PGAdapter se inicie y ejecute en la misma máquina que tu instalación de Liquibase. Para obtener más información, consulta Cómo iniciar PGAdapter.
Solo para bases de datos con dialecto de PostgreSQL, usa la secuencia de comandos create_database_change_log.sql para crear las tablas de metadatos databasechangeloglock y databasechangelog. Debes crear estas tablas para anular las que Liquibase crea automáticamente en tu base de datos. Esto se hace para garantizar que se usen los tipos de datos correctos de PostgreSQL para Spanner en estas tablas.
Puedes ejecutar la secuencia de comandos con el siguiente comando:
Ejecuta el siguiente comando gcloud para otorgar a la extensión de Liquibase de Spanner el uso temporal de tus credenciales de usuario de Spanner para el acceso a la API:
Este YAML define una tabla llamada Singers con una clave primaria SingerId y una columna llamada Name para almacenar el nombre del cantante.
Para las bases de datos de dialecto de PostgreSQL, te recomendamos que uses todo en minúsculas para los nombres de las tablas y columnas. Para obtener más información, consulta Distinción entre mayúsculas y minúsculas de PostgreSQL.
Ten en cuenta que el conjunto de cambios createTable debe incluir una restricción de clave primaria, y el nombre de la restricción de clave primaria debe ser pk_table_name.
Guarda los cambios como changelog.yaml.
Ejecuta Liquibase
Ejecuta el siguiente comando para aplicar el conjunto de cambios en changelog.yaml:
liquibase --changeLogFile changelog.yaml update
Liquibase usa la URL que definiste en el archivo liquibase.properties. Para anular el valor del archivo, agrega el siguiente argumento al comando anterior:
--url URL
Verifica tus cambios
Las actualizaciones del paso anterior provocaron que se agregara la tabla Singer a tu base de datos. Además, se agregaron las tablas DATABASECHANGELOG y DATABASECHANGELOGLOCK (base de datos de dialecto GoogleSQL) o se actualizaron (base de datos de dialecto PostgreSQL).
Puedes verificar la existencia de estas tablas a través de la Google Cloud consola
o gcloud CLI. Por ejemplo, ejecutar la consulta de SQL SELECT * FROM
INFORMATION_SCHEMA.TABLES muestra una lista de todas las tablas de tu base de datos.
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 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)."]]
