Integra Spanner con Liquibase

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 con dialecto de GoogleSQL y bases de datos con 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 de esquema de la base de datos. Admite SQL, así como 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 con 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 con dialecto de GoogleSQL, debes instalar la extensión de Spanner Liquibase. Para las bases de datos con dialecto de 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, y para tomar una instantánea de tu base de datos.

  2. Navega a la página de versiones de la extensión de Spanner Liquibase 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, 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.

  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, establece 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. Las otras propiedades son opcionales.

PostgreSQL

  1. 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 Inicia PGAdapter.

  2. Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase, y para 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.

  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. Las otras propiedades son opcionales.

La cadena url debe incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque Spanner no admite transacciones DDL, y esto 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 GoogleSQL Liquibase 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 dialecto de GoogleSQL o una base de datos con dialecto de PostgreSQL.

  • Solo para bases de datos con dialecto de PostgreSQL, asegúrate de que PGAdapter se inicie y se ejecute en la misma máquina que tu instalación de Liquibase. Para obtener más información, consulta Inicia PGAdapter.

  • Solo para bases de datos con dialecto de PostgreSQL, usa la create_database_change_log.sql para crear las tablas de metadatos databasechangeloglock y databasechangelog. Debes crear estas tablas para anular las tablas que Liquibase crea automáticamente en tu base de datos. Esto es para 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

  • Para otorgar a la extensión de Spanner Liquibase el uso temporal de tus credenciales de usuario de Spanner para el acceso a la API, ejecuta el siguiente comando gcloud:

    gcloud auth application-default login

Crea un changelog.yaml

  1. 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 primaria SingerId y una columna llamada Name para almacenar el nombre del cantante.

    Para las bases de datos con dialecto de PostgreSQL, recomendamos usar todas las letras minúsculas para los nombres de tablas y columnas. Para obtener más información, consulta Sensibilidad a 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.

  2. 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 en el archivo agregando el siguiente argumento al comando anterior:

--url URL

Verifica tus cambios

Las actualizaciones del paso anterior hicieron que se agregara la tabla Singer a tu base de datos. Además, se agregaron las tablas DATABASECHANGELOG y DATABASECHANGELOGLOCK (base de datos con dialecto de GoogleSQL) o se actualizaron (base de datos con dialecto de PostgreSQL).

Puedes verificar la existencia de estas tablas a través de la Google Cloud consola o gcloud CLI. Por ejemplo, si ejecutas la consulta en SQL SELECT * FROM INFORMATION_SCHEMA.TABLES, se muestra 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'

Puedes ver un registro de los cambios que se aplicaron consultando el contenido de DATABASECHANGELOG.

¿Qué sigue?