Integrar Spanner con Liquibase

En esta página se describe cómo gestionar los cambios en el esquema de la base de datos de Spanner con Liquibase para bases de datos con dialecto GoogleSQL y PostgreSQL.

Liquibase es una biblioteca de código abierto independiente de la base de datos que se usa para monitorizar, gestionar y aplicar cambios en el esquema de la base de datos. Es compatible con SQL y con formatos declarativos como XML, YAML y JSON.

Liquibase puede usar como destino bases de datos de Spanner. Es compatible con todas las funciones de Spanner, aunque con algunas limitaciones.

  • Para ver las limitaciones generales, consulta Limitaciones.
  • Para ver información adicional sobre las bases de datos con dialecto PostgreSQL, como los requisitos de Liquibase, los tipos de cambios admitidos y las limitaciones, consulta PGAdapter y Liquibase.

Instalar Liquibase

Para usar Liquibase con bases de datos de dialecto GoogleSQL, debes instalar la extensión Spanner Liquibase. En el caso de las bases de datos con dialecto PostgreSQL, Liquibase puede usar su compatibilidad integrada con PostgreSQL junto con PGAdapter.

GoogleSQL

  1. Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase, así como para hacer una instantánea de tu base de datos.

  2. Ve a la página de versiones de la extensión Liquibase de Spanner en GitHub y selecciona la versión más reciente.

  3. 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.

  4. 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 JDBC de Spanner.

En el archivo de configuración liquibase.properties, define la propiedad url de la siguiente manera.

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

Tu archivo de configuración liquibase.properties solo puede contener esta propiedad. El resto de las propiedades son opcionales.

PostgreSQL

  1. Asegúrate de que PGAdapter se haya iniciado y se esté ejecutando en el equipo en el que instales Liquibase. Para obtener más información, consulta Iniciar PGAdapter.

  2. Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase, así como para hacer una instantánea de tu base de datos.

En el archivo de configuración liquibase.properties, define la propiedad url 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. El resto de las propiedades son opcionales.

La cadena url debe incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque Spanner no admite transacciones DDL y esto asegura que las transacciones DDL se conviertan en lotes DDL. Para obtener más información, consulta Opciones de DDL para PGAdapter.

Revisa los ejemplos de Liquibase

GoogleSQL

El archivo de registro de cambios de ejemplo changelog.yaml incluido con la extensión Liquibase de GoogleSQL muestra muchas de las funciones de Liquibase y cómo usarlas con Spanner.

PostgreSQL

El archivo de registro de cambios de ejemplo 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 añadir una tabla Singers a una base de datos.

Antes de empezar

  • Asegúrate de haber completado los pasos anteriores para instalar Liquibase.

  • Crea una instancia de Spanner.

  • Crea una base de datos con dialecto GoogleSQL o PostgreSQL.

  • En el caso de las bases de datos con dialecto PostgreSQL, asegúrate de que PGAdapter se haya iniciado y se esté ejecutando en el mismo equipo que tu instalación de Liquibase. Para obtener más información, consulta Iniciar PGAdapter.

  • En el caso de las bases de datos con dialecto 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. De esta forma, se asegura de 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

  • Para que la extensión Spanner Liquibase pueda usar temporalmente tus credenciales de usuario de Spanner para acceder a la API, ejecuta el siguiente comando gcloud:

    gcloud auth application-default login

Crea un archivo changelog.yaml.

  1. Introduce el siguiente archivo YAML en el editor que prefieras.

    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 archivo YAML define una tabla llamada Singers con una clave principal SingerId y una columna llamada Name para almacenar el nombre del cantante.

    En el caso de las bases de datos con dialecto PostgreSQL, te recomendamos que uses minúsculas en los nombres de las tablas y las columnas. Para obtener más información, consulta Distinción entre mayúsculas y minúsculas en PostgreSQL.

    Ten en cuenta que el createTable conjunto de cambios debe incluir una restricción de clave principal y que el nombre de la restricción de clave principal debe ser pk_table_name.

  2. Guarda los cambios como changelog.yaml.

Ejecutar Liquibase

Aplica el conjunto de cambios en changelog.yaml ejecutando el siguiente comando:

liquibase --changeLogFile changelog.yaml update

Liquibase usa la URL que has definido en el archivo liquibase.properties. Puedes anular el valor del archivo añadiendo el siguiente argumento al comando anterior:

--url URL

Verificar los cambios

Las actualizaciones del paso anterior han provocado que se añada la tabla Singer a tu base de datos. Además, se han añadido (base de datos con dialecto de GoogleSQL) o actualizado (base de datos con dialecto de PostgreSQL) las tablas DATABASECHANGELOG y DATABASECHANGELOGLOCK.

Puedes verificar la existencia de estas tablas a través de la Google Cloud consola o de la CLI de gcloud. Por ejemplo, al ejecutar la consulta SQL SELECT * FROM INFORMATION_SCHEMA.TABLES, se devuelve una lista de todas las tablas de 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 han aplicado, consulta el contenido de DATABASECHANGELOG.

Siguientes pasos