En esta página, se describe cómo administrar los cambios del esquema de la base de datos de Spanner con Liquibase.
Liquibase es una biblioteca de código abierto independiente de la base de datos para realizar 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 las bases de datos de Spanner. Es compatible con todas las funciones de Spanner, con algunas limitaciones.
- Para conocer las limitaciones generales, consulta las 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 las bases de datos de dialectos de GoogleSQL, debes instalar la extensión de Spanner Liquibase. Para las bases de datos de dialecto de PostgreSQL, Liquibase puede usar su compatibilidad integrada con PostgreSQL junto con PGAdapter.
GoogleSQL
Sigue las instrucciones en 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
, configura la propiedadurl
de la siguiente manera.jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE
Tu archivo de configuración
liquibase.properties
solo puede contener esta propiedad. Otras propiedades son opcionales.Navega a la página de versiones de la extensión de Spanner Liquibase 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
, en el que 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 de lib de Liquibase. El archivo JAR incluye la extensión, el SDK de Spanner y el controlador del controlador JDBC de Spanner.
PostgreSQL
Asegúrate de que PGAdapter se haya iniciado y se esté ejecutando en la máquina en la que instalarás Liquibase. Para obtener más información, consulta Cómo iniciar PGAdapter.
Sigue las instrucciones en 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
, configura la propiedadurl
de la siguiente manera.jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
Tu archivo de configuración
liquibase.properties
solo puede contener esta propiedad. Otras propiedades son opcionales.La string
url
debe incluiroptions=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
porque Spanner no admite transacciones de DDL, lo que garantizará que las transacciones de DDL se conviertan de forma automática en lotes de 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 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 muestra 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.
Crear una instancia de Spanner
Crea una base de datos de dialectos de GoogleSQL o de PostgreSQL.
Solo para las bases de datos de dialectos de PostgreSQL, asegúrate de que PGAdapter se inicie y se ejecute en la misma máquina en que se instaló la instalación de Liquibase. Para obtener más información, consulta Cómo iniciar PGAdapter.
Solo para las bases de datos del dialecto de PostgreSQL, crea las tablas de metadatos
databasechangeloglock
ydatabasechangelog
con la secuencia de comandos create_database_change_log.sql. Debes crear estas tablas para anular las tablas que Liquibase crea automáticamente en tu base de datos. Esto permite garantizar que se usen los tipos de datos de PostgreSQL correctos para Spanner en estas tablas.Puedes ejecutar la secuencia de comandos con el siguiente comando:
psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
Ejecuta el siguiente comando
gcloud
para permitir que la extensión de Spanner Liquibase use de forma temporal tus propias credenciales de usuario de Spanner para el acceso a la API:gcloud auth application-default login
Crea un archivo changelog.yaml
Ingresa el siguiente YAML en tu editor favorito.
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)
Este YAML define una tabla llamada
Singers
con una clave primariaSingerId
y una columna llamadaName
para almacenar el nombre del cantante.En el caso de las bases de datos de dialectos de PostgreSQL, te recomendamos que uses minúsculas para los nombres de 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
Para aplicar el conjunto de cambios en changelog.yaml
, ejecuta el siguiente comando:
liquibase --changeLogFile changelog.yaml update
Liquibase usa la URL que definiste en el archivo liquibase.properties
. Puedes
anular el valor del archivo si agregas el siguiente argumento al
comando anterior:
--url URL
Verifica tus cambios
Las actualizaciones del paso anterior hicieron que la tabla Singer
se agregara a tu base de datos. Además, se agregaron las tablas DATABASECHANGELOG
y DATABASECHANGELOGLOCK
(base de datos del dialecto GoogleSQL) o se actualizaron (base de datos del dialecto de PostgreSQL).
Puedes verificar la existencia de estas tablas a través de la consola de Google Cloud
o gcloud CLI. Por ejemplo, ejecutar la consulta en SQL SELECT * FROM
INFORMATION_SCHEMA.TABLES
muestra una lista de todas las tablas en tu base de datos.
gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \ --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'
Para ver un registro de los cambios que se aplicaron, consulta el contenido de DATABASECHANGELOG
.
¿Qué sigue?
Para obtener más documentación, visita el repositorio de GitHub de la extensión de Spanner Liquibase.
Para obtener más información sobre Liquibase, consulta Cómo comenzar a usar Liquibase.