Integrar o Spanner ao Liquibase

Nesta página, descrevemos como gerenciar alterações de esquema de 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 é compatível com todos os recursos do Spanner, com algumas limitações.

  • Para ver as limitações gerais, consulte as limitações.
  • Para mais informações sobre bancos de dados do dialeto PostgreSQL, como requisitos do Liquibase, tipos de alterações compatíveis e limitações, consulte PGAdapter e Liquibase.

Instalar o Liquibase

Para usar o Liquibase com bancos de dados do dialeto GoogleSQL, você precisa instalar a extensão Liquibase do Spanner. Para bancos de dados do dialeto PostgreSQL, o Liquibase pode usar o suporte integrado ao PostgreSQL em conjunto com o PGAdapter (em inglês).

GoogleSQL

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

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

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

  2. Navegue até a página de versões da extensão Liquibase do Spanner 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 está iniciado e em execução na máquina em que você instalará o Liquibase. Para mais informações, consulte Iniciar PGAdapter.

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

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

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

    A string url precisa incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque o Spanner não é compatível com transações DDL, e isso garante que as transações DDL sejam convertidas automaticamente em lotes DDL. Para mais informações, consulte Opções de DDL para PGAdapter.

Analisar as amostras do Liquibase

GoogleSQL

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

PostgreSQL

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

Guia de início rápido do Liquibase

Neste guia de início rápido, mostramos 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.

  • Criar uma instância do Spanner.

  • Criar um banco de dados do dialeto GoogleSQL ou do PostgreSQL.

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

  • Apenas para bancos de dados do dialeto PostgreSQL, crie as tabelas de metadados databasechangeloglock e databasechangelog usando o script create_database_change_log.sql. Crie 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.

    É possível executar o script com o seguinte comando:

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

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

    gcloud auth application-default login

Crie um arquivo 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 do dialeto PostgreSQL, recomendamos usar todas as letras minúsculas para nomes de tabelas e colunas. Para mais informações, consulte Detecção de maiúsculas e minúsculas do PostgreSQL.

    Observe que 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 modificar 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 GoogleSQL-dialect) ou atualizadas (banco de dados PostgreSQL-dialect).

É possível verificar a existência dessas tabelas por meio do console do Google Cloud ou da 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