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

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.
Navegue até a página de versões da extensão Liquibase do Spanner no GitHub e selecione a versão mais recente.
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.
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

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

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

Para mais documentação, acesse o repositório do GitHub Extensão do Spanner Liquibase.
Para saber mais sobre o Liquibase, consulte Primeiros passos com o Liquibase.