Integre o Spanner com o Liquibase

Esta página descreve como gerir as alterações ao esquema da base de dados do Spanner com o Liquibase para bases de dados com dialeto GoogleSQL e bases de dados com dialeto PostgreSQL.

O Liquibase é uma biblioteca independente da base de dados de código aberto para acompanhar, gerir e aplicar alterações ao esquema da base de dados. Suporta SQL, bem como formatos declarativos, como XML, YAML e JSON.

O Liquibase pode segmentar bases de dados do Spanner. Suporta todas as funcionalidades do Spanner, com algumas limitações.

  • Para ver as limitações gerais, consulte as limitações.
  • Para ver informações adicionais sobre bases de dados com dialeto PostgreSQL, como requisitos do Liquibase, tipos de alterações suportados e limitações, consulte PGAdapter e Liquibase.

Instale o Liquibase

Para usar o Liquibase com bases de dados de dialeto GoogleSQL, tem de instalar a extensão do Liquibase para o Spanner. Para bases de dados com dialeto PostgreSQL, o Liquibase pode usar o suporte PostgreSQL incorporado em conjunto com o PGAdapter.

GoogleSQL

  1. Siga as instruções na documentação do Liquibase para instalar e configurar o Liquibase, e para tirar uma captura instantânea da sua base de dados.

  2. Navegue para a página de lançamentos da extensão Liquibase do Spanner no GitHub e selecione o lançamento mais recente.

  3. Selecione e transfira o ficheiro JAR com o nome liquibase-spanner-x.y.z-all.jar, em que x.y.z representa o número da versão da extensão. Por exemplo, liquibase-spanner-4.17.0-all.jar.

  4. Coloque o ficheiro JAR transferido no diretório lib do Liquibase. O ficheiro JAR inclui a extensão, o SDK do Spanner e o controlador JDBC do Spanner.

No ficheiro de configuração liquibase.properties, defina a propriedade url da seguinte forma.

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

O seu ficheiro de configuração liquibase.properties só pode conter esta propriedade. As outras propriedades são opcionais.

PostgreSQL

  1. Certifique-se de que o PGAdapter é iniciado e executado na máquina onde instala o Liquibase. Para mais informações, consulte o artigo Iniciar PGAdapter.

  2. Siga as instruções na documentação do Liquibase para instalar e configurar o Liquibase, e para tirar uma captura instantânea da sua base de dados.

No ficheiro 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 seu ficheiro de configuração liquibase.properties só pode conter esta propriedade. As outras propriedades são opcionais.

A string url tem de incluir options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction porque o Spanner não suporta transações DDL e isto garante que as transações DDL são convertidas em lotes DDL. Para mais informações, consulte Opções de DDL para o PGAdapter.

Reveja os exemplos do Liquibase

GoogleSQL

O ficheiro de registo de alterações de exemplo changelog.yaml incluído na extensão Liquibase do GoogleSQL demonstra muitas das funcionalidades do Liquibase e como as usar com o Spanner.

PostgreSQL

O ficheiro de registo de alterações de exemplo dbchangelog.xml disponível no repositório do GitHub do PGAdapter e do Liquibase demonstra muitas das funcionalidades do Liquibase e como as usar com o Spanner.

Início rápido do Liquibase

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

Antes de começar

  • Certifique-se de que concluiu os passos anteriores para instalar o Liquibase.

  • Crie uma instância do Spanner.

  • Crie uma base de dados com o dialeto GoogleSQL ou uma base de dados com o dialeto PostgreSQL.

  • Apenas para bases de dados com dialeto PostgreSQL, certifique-se de que o PGAdapter é iniciado e executado na mesma máquina que a instalação do Liquibase. Para mais informações, consulte o artigo Inicie o PGAdapter.

  • Apenas para bases de dados com dialeto PostgreSQL, use o script create_database_change_log.sql para criar as tabelas de metadados databasechangeloglock e databasechangelog. Tem de criar estas tabelas para substituir as tabelas que o Liquibase cria automaticamente na sua base de dados. Isto destina-se a garantir que os tipos de dados PostgreSQL corretos para o Spanner são usados nestas tabelas.

    Pode executar o script com o seguinte comando:

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

  • Conceda à extensão Liquibase do Spanner a utilização temporária das suas credenciais de utilizador do Spanner para acesso à API executando o seguinte comando gcloud:

    gcloud auth application-default login

Crie um ficheiro changelog.yaml

  1. Introduza 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)

    Este YAML define uma tabela denominada Singers com uma chave principal SingerId e uma coluna denominada Name para armazenar o nome do cantor.

    Para bases de dados com dialeto PostgreSQL, recomendamos que use apenas letras minúsculas para os nomes das tabelas e colunas. Para mais informações, consulte o artigo Diferenciação entre maiúsculas e minúsculas do PostgreSQL.

    Tenha em atenção que o conjunto de alterações createTable tem de incluir uma restrição de chave primária e o nome da restrição de chave primária tem de ser pk_table_name.

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

Execute 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 que definiu no ficheiro liquibase.properties. Pode substituir o valor no ficheiro adicionando o seguinte argumento ao comando anterior:

--url URL

Valide as alterações

As atualizações no passo anterior fizeram com que a tabela Singer fosse adicionada à sua base de dados. Além disso, as tabelas DATABASECHANGELOG e DATABASECHANGELOGLOCK foram adicionadas (base de dados de dialeto GoogleSQL) ou atualizadas (base de dados de dialeto PostgreSQL).

Pode verificar a existência destas tabelas através da Google Cloud consola ou da CLI gcloud. Por exemplo, a execução da consulta SQL SELECT * FROM INFORMATION_SCHEMA.TABLES devolve uma lista de todas as tabelas na sua base de dados.

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

Pode ver um registo das alterações que foram aplicadas consultando o conteúdo de DATABASECHANGELOG.

O que se segue?