Integra Spanner en Liquibase

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 orientar bases de datos de Spanner. Es compatible con todas las características de Spanner, con algunas limitaciones.

Para ver las limitaciones generales, consulta las limitaciones.
Para obtener 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 las 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 dialectos de PostgreSQL, Liquibase puede usar la compatibilidad integrada con PostgreSQL junto con PGAdapter.

GoogleSQL

Sigue las instrucciones de la documentación de Liquibase para instalar y configurar Liquibase y tomar una instantánea de la base de datos. En el archivo de configuración liquibase.properties, configura 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. Otras propiedades son opcionales.
Navega a la página de versiones 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, 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 Liquibase lib. El archivo JAR incluye la extensión, el SDK de Spanner y el controlador del controlador de JDBC de Spanner.

PostgreSQL

Asegúrate de que PGAdapter se inicie y se ejecute en la máquina en la que instalarás 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 la base de datos. En el archivo de configuración liquibase.properties, configura 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. Otras propiedades son opcionales.

La cadena url debe incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque Spanner no admite transacciones de DDL, y esto garantizará que las transacciones de DDL se conviertan automáticamente en lotes de 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 muestra changelog.yaml incluido con la extensión GoogleSQL Liquibase demuestra muchas de las funciones de Liquibase y cómo usarlas con Spanner.

PostgreSQL

En el archivo de registro de cambios de muestra dbchangelog.xml, disponible en el repositorio de PGAdapter y Liquibase en GitHub, se muestran 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 dialecto de GoogleSQL o una base de datos de dialecto de PostgreSQL.
Solo para bases de datos 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 Cómo iniciar PGAdapter.
Solo para las bases de datos con dialectos de PostgreSQL, crea las tablas de metadatos databasechangeloglock y databasechangelog mediante la secuencia de comandos create_database_change_log.sql. Debes crear estas tablas para anular las que Liquibase crea automáticamente en tu base de datos. Esto permite 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:
```
psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql
```
Ejecuta el siguiente comando gcloud para otorgarle a la extensión Liquibase de Spanner el uso temporal de tus propias credenciales de usuario de Spanner para el acceso a la API:
```
gcloud auth application-default login
```

Crea un 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)
```
En este YAML, se define una tabla llamada Singers con una clave primaria SingerId y una columna llamada Name para almacenar el nombre del cantante.

En el caso de las bases de datos con dialecto 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 de createTable debe incluir una restricción de clave primaria y el nombre de esta restricción debe ser pk_table_name.
Guarda los cambios como changelog.yaml.

Ejecuta Liquibase

Para aplicar el cambio en changelog.yaml, ejecuta el siguiente comando:

liquibase --changeLogFile changelog.yaml update

Liquibase usa la URL que definiste en el archivo liquibase.properties. Para anular el valor en el archivo, agrega el siguiente argumento al comando anterior:

--url URL

Verifica tus cambios

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

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

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

¿Qué sigue?

Para obtener más documentación, visita el repositorio de GitHub de la extensión Liquibase de Spanner.
Para obtener más información sobre Liquibase, consulte Cómo comenzar a utilizar Liquibase.