Integrar o Spanner ao Liquibase

Esta página descreve como gerenciar mudanças no esquema do banco de dados do Spanner com o Liquibase.

O Liquibase é uma biblioteca de banco de dados de código aberto independente para rastrear, gerenciar e aplicar alterações de esquema de banco de dados. Ele é compatível com SQL, além de formatos declarativos, como XML, YAML e JSON.

O Liquibase pode segmentar bancos de dados do Spanner. Ele oferece suporte a todos os recursos do Spanner, com algumas limitações.

  • Para ver as limitações gerais, consulte Limitações.
  • Para conferir mais informações sobre bancos de dados de dialeto PostgreSQL, como requisitos do Liquibase, tipos de mudança aceitos e limitações, consulte PGAdapter e Liquibase.

Instalar o Liquibase

Para usar o Liquibase com bancos de dados do dialeto GoogleSQL, é necessário instalar a extensão Spanner Liquibase. Para bancos de dados de dialeto PostgreSQL, o Liquibase pode usar o suporte integrado ao PostgreSQL em conjunto com o PGAdapter.

GoogleSQL

  1. Siga as instruções na documentação do Liquibase para instalar e configurar o Liquibase e fazer um snapshot do seu banco de dados. No arquivo de configuração liquibase.properties, defina a propriedade url da seguinte forma.

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

    O arquivo de configuração liquibase.properties só pode conter essa propriedade. Outras propriedades são opcionais.

  2. Navegue até a página de versões da extensão do Spanner Liquibase no GitHub e selecione a versão mais recente.

  3. Selecione e faça o download do arquivo JAR com o nome liquibase-spanner-x.y.z-all.jar, em que xyz representa o número da versão da extensão. Por exemplo, liquibase-spanner-4.17.0-all.jar.

  4. Coloque o arquivo JAR transferido por download no diretório Lilibbase lib. O arquivo JAR inclui a extensão, o SDK do Spanner e o driver JDBC do Spanner.

PostgreSQL

  1. Verifique se o PGAdapter foi iniciado e está em execução na máquina em que você vai instalar o Liquibase. Para mais informações, consulte Iniciar o PGAdapter.

  2. Siga as instruções na documentação do Liquibase para instalar e configurar o Liquibase e fazer um snapshot do seu banco de dados. No arquivo de configuração liquibase.properties, defina a propriedade url da seguinte forma.

    jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction

    O arquivo de configuração liquibase.properties só pode conter essa propriedade. Outras propriedades são opcionais.

    A string url precisa incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque o Spanner não oferece suporte a transações DDL. Isso garante que as transações DDL sejam convertidas automaticamente em lotes DDL. Para mais informações, consulte Opções de DDL para o PGAdapter.

Analisar os exemplos do Liquibase

GoogleSQL

O arquivo de registro de alterações de exemplo changelog.yaml incluído na extensão Liquibase do GoogleSQL demonstra muitos dos recursos do Liquibase e como usá-los com o Spanner.

PostgreSQL

O arquivo de registro de alterações de amostra dbchangelog.xml disponível no repositório do GitHub do PGAdapter e do Liquibase demonstra muitos dos recursos do Liquibase e como usá-los com o Spanner.

Guia de início rápido do Liquibase

Este guia de início rápido mostra como usar o Liquibase para adicionar uma tabela Singers a um banco de dados.

Antes de começar

  • Verifique se você concluiu as etapas anteriores para instalar o Liquibase.

  • Crie uma instância do Spanner.

  • Crie um banco de dados com dialeto GoogleSQL ou PostgreSQL.

  • Para bancos de dados de dialeto PostgreSQL, verifique se o PGAdapter foi iniciado e está sendo executado na mesma máquina que a instalação do Liquibase. Para mais informações, consulte Iniciar o PGAdapter.

  • Para bancos de dados de dialeto do PostgreSQL, crie as tabelas de metadados databasechangeloglock e databasechangelog usando o script create_database_change_log.sql. Você precisa criar essas tabelas para substituir as tabelas que o Liquibase cria automaticamente no seu banco de dados. Isso garante que os tipos de dados corretos do PostgreSQL para o Spanner sejam usados nessas tabelas.

    Você pode executar o script com o seguinte comando:

    psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql

  • Conceda à extensão do Spanner Liquibase o uso temporário das suas próprias credenciais de usuário do Spanner para acesso à API executando o seguinte comando gcloud:

    gcloud auth application-default login

Criar um changelog.yaml

  1. Insira o seguinte YAML no seu 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)

    Esse YAML define uma tabela chamada Singers com uma chave primária SingerId e uma coluna chamada Name para armazenar o nome do cantor.

    Para bancos de dados de dialeto PostgreSQL, recomendamos usar letras minúsculas para nomes de tabelas e colunas. Para mais informações, consulte Diferença entre maiúsculas e minúsculas no PostgreSQL.

    O conjunto de mudanças createTable precisa incluir uma restrição de chave primária, e o nome da restrição de chave primária precisa ser pk_table_name.

  2. Salve as alterações como changelog.yaml.

Executar o Liquibase

Aplique o conjunto de mudanças em changelog.yaml executando o seguinte comando:

liquibase --changeLogFile changelog.yaml update

O Liquibase usa o URL que você definiu no arquivo liquibase.properties. É possível substituir o valor no arquivo adicionando o seguinte argumento ao comando anterior:

--url URL

Verificar suas alterações

As atualizações na etapa anterior fizeram com que a tabela Singer fosse adicionada ao seu banco de dados. Além disso, as tabelas DATABASECHANGELOG e DATABASECHANGELOGLOCK foram adicionadas (banco de dados do dialeto GoogleSQL) ou atualizadas (banco de dados do dialeto PostgreSQL).

É possível verificar a existência dessas tabelas no console do Google Cloud ou na CLI gcloud. Por exemplo, executar a consulta SQL SELECT * FROM INFORMATION_SCHEMA.TABLES retorna uma lista de todas as tabelas no seu banco de dados.

gcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \
    --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'

É possível ver um registro das mudanças que foram aplicadas consultando o conteúdo de DATABASECHANGELOG.

A seguir