Integrar o Spanner ao Liquibase

Nesta página, descrevemos como gerenciar mudanças no esquema do banco de dados do Spanner com o Liquibase para bancos de dados do dialeto GoogleSQL e do dialeto PostgreSQL.

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 conferir as limitações gerais, consulte esta página.
• Para mais informações sobre bancos de dados com dialeto PostgreSQL, como requisitos do Liquibase, tipos de mudanças aceitos e limitações, consulte PGAdapter e Liquibase.

Instalar o Liquibase

Para usar o Liquibase com bancos de dados do dialeto GoogleSQL, instale a extensão do Spanner Liquibase. Para bancos de dados do dialeto PostgreSQL, o Liquibase pode usar o suporte integrado do PostgreSQL em conjunto com o PGAdapter.

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

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

Analise os exemplos do Liquibase

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

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

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

• Somente para bancos de dados com dialeto PostgreSQL, use o script create_database_change_log.sql para criar as tabelas de metadados databasechangeloglock e databasechangelog. Você precisa criar essas tabelas para substituir as que o Liquibase cria automaticamente no seu banco de dados. Isso garante que os tipos de dados corretos do PostgreSQL para 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 credenciais de usuário do Spanner para acesso à API executando o comando gcloud a seguir:

  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 com 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 dela precisa ser pk_table_name.

2. Salve as mudanças 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 definido no arquivo liquibase.properties. Você pode 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 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

• Para mais documentação, acesse o repositório do GitHub Spanner Liquibase Extension.

• Para saber mais sobre o Liquibase, consulte Primeiros passos com o Liquibase.