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 ser destinado a bancos de dados do Spanner. Ele oferece suporte a todos os recursos do Spanner, com algumas limitações.

  • Para conferir as limitações gerais, consulte as limitações.
  • Para saber mais sobre os bancos de dados de dialeto PostgreSQL, como os requisitos do Liquibase, tipos de alterações suportados 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 capturar 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é o liquibase do Spanner página de versões de extensão no GitHub e selecione 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. Verificar se o PGAdapter está iniciado e em execução na máquina em que você 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 dá suporte a transações DDL, e isso garante que As transações DDL são convertidas automaticamente em lotes DDL. Para mais informações, consulte Opções de DDL para o PGAdapter.

Analisar as amostras do Liquibase

GoogleSQL

O exemplo de arquivo de registro de alterações changelog.yaml incluído no A extensão GoogleSQL Liquibase 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 uma no seu banco de dados.

Antes de começar

  • Verifique se você concluiu as etapas anteriores de instalação. Liquibase.

  • Crie uma instância do Spanner.

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

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

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

    É possível 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 Sensibilidade de maiúsculas e minúsculas do 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 mudanças como changelog.yaml.

Executar o Liquibase

Aplique o conjunto de alterações 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 no 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 pelo console do Google Cloud ou CLI gcloud. Por exemplo, executar a consulta SQL SELECT * FROM INFORMATION_SCHEMA.TABLES retorna uma lista de todas as tabelas no 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