Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta página descreve como gerenciar mudanças no esquema do banco de dados do Spanner
com o Liquibase para bancos de dados com dialeto GoogleSQL e 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 oferece suporte a todos
os recursos do Spanner, com algumas limitações.
Para ver as limitações gerais, consulte Limitações.
Para ver mais informações sobre bancos de dados de dialeto PostgreSQL, como requisitos do Liquibase, tipos de mudança 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 Spanner Liquibase. Para bancos de dados de dialeto PostgreSQL, o Liquibase pode usar
o suporte integrado ao PostgreSQL em conjunto com o
PGAdapter.
GoogleSQL
Siga as instruções na documentação do Liquibase
para instalar e configurar o Liquibase e fazer um instantâneo do
banco de dados. No arquivo de configuração liquibase.properties, defina a
propriedade url da seguinte maneira.
Navegue até a página de versões da extensão do Spanner Liquibase
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 x.y.z 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 do driver JDBC do Spanner.
PostgreSQL
Verifique se o PGAdapter foi iniciado e está em execução na máquina
em que você instalou o Liquibase. Para mais informações, consulte Iniciar
o PGAdapter.
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.
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 é compatível com transações DDL. Isso
garante que as transações DDL sejam convertidas em lotes DDL. Para mais
informações, consulte Opções de DDL para o PGAdapter.
Analisar os exemplos do Liquibase
GoogleSQL
O arquivo de registro de alterações de amostra changelog.yaml incluído na extensão Liquibase do GoogleSQL demonstra muitos dos recursos do Liquibase e como usá-los com o Spanner.
PostgreSQL
O arquivo de registro de mudança 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 um
banco de dados.
Antes de começar
Verifique se você concluiu as etapas anteriores para instalar
o Liquibase.
Crie uma instância do Spanner.
Crie um banco de dados com dialeto do GoogleSQL ou do PostgreSQL.
Para bancos de dados de dialeto PostgreSQL, verifique se o PGAdapter foi iniciado e está sendo executado
na mesma máquina que a instalação do Liquibase. Para mais informações, consulte
Iniciar o PGAdapter.
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 o Spanner sejam usados nessas
tabelas.
Você pode executar o script com o seguinte comando:
Conceda à extensão do Spanner Liquibase o uso temporário das suas
credenciais de usuário do Spanner para acesso à API executando o
seguinte comando gcloud:
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
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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-05 UTC."],[],[],null,["# Integrate Spanner with Liquibase\n\nThis page describes how to manage Spanner database schema changes\nwith [Liquibase](https://www.liquibase.org/) for GoogleSQL-dialect databases and PostgreSQL-dialect databases.\n\nLiquibase is an open-source database-independent library for tracking, managing,\nand applying database schema changes. It supports SQL as well as declarative\nformats such as XML, YAML, and JSON.\n\nLiquibase can target Spanner databases. It supports all\nSpanner features, with some limitations.\n\n- To see general limitations, see [limitations](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/limitations.md).\n- To see additional information for PostgreSQL-dialect databases, such as Liquibase requirements, supported change types, and limitations, see [PGAdapter and Liquibase](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase).\n\nInstall Liquibase\n-----------------\n\nTo use Liquibase with GoogleSQL-dialect databases, you have to install the\nSpanner Liquibase extension. For PostgreSQL-dialect databases, Liquibase can use\nits built-in PostgreSQL support in conjunction with\n[PGAdapter](/spanner/docs/pgadapter). \n\n### GoogleSQL\n\n1. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart) to install and configure Liquibase, and to take a snapshot of your database. In the `liquibase.properties` configuration file, set the `url` property as follows.\n\n```\n jdbc:cloudspanner:/projects/PROJECT/instances/INSTANCE/databases/DATABASE\n \n``` \n\n Your `liquibase.properties` configuration file can contain only this\n property. Other properties are optional.\n\n1. Navigate to the Spanner Liquibase Extension releases page\n on GitHub and select the [latest release](https://github.com/cloudspannerecosystem/liquibase-spanner/releases/latest).\n\n2. Select and download the JAR file with the name\n `liquibase-spanner-x.y.z-all.jar`, where x.y.z represents the extension\n version number. For example, `liquibase-spanner-4.17.0-all.jar`.\n\n3. Place the downloaded JAR file in the Liquibase lib directory. The JAR\n file includes the extension, the Spanner SDK, and the\n Spanner JDBC driver driver.\n\n### PostgreSQL\n\n1. Ensure that PGAdapter is started and running on the machine\n where you install Liquibase. For more information, see [Start\n PGAdapter](/spanner/docs/pgadapter-start).\n\n2. Follow the instructions in the [Liquibase documentation](https://www.liquibase.org/get-started/quickstart)\n to install and configure Liquibase, and to take a snapshot of your database.\n\nIn the `liquibase.properties` configuration file, set the `url` property as\nfollows. \n\n```\n jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction\n \n```\n\nYour `liquibase.properties` configuration file can contain only this\nproperty. Other properties are optional.\n\nThe `url` string must include\n`options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction`\nbecause Spanner doesn't support DDL transactions, and this\nensures that DDL transactions are converted to DDL batches. For more\ninformation, see [DDL Options for PGAdapter](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/docs/ddl.md).\n\nReview the Liquibase samples\n----------------------------\n\n### GoogleSQL\n\nThe sample change log file [changelog.yaml](https://github.com/cloudspannerecosystem/liquibase-spanner/blob/master/example/changelog.yaml) included with\nthe GoogleSQL Liquibase extension demonstrates many of the\nfeatures of Liquibase and how to use them with Spanner.\n\n### PostgreSQL\n\nThe sample change log file `dbchangelog.xml` available in the\n[PGAdapter and Liquibase GitHub repository](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase)\ndemonstrates many of the features of Liquibase and how to use them with\nSpanner.\n\nLiquibase quickstart\n--------------------\n\nThis quickstart shows you how to use Liquibase to add a `Singers` table to a\ndatabase.\n\n### Before you begin\n\n- Make sure that you have completed the preceding steps to [install](#install-liq)\n Liquibase.\n\n- Create a Spanner instance.\n\n- Create a GoogleSQL-dialect database or PostgreSQL-dialect database.\n\n- For PostgreSQL-dialect databases only, ensure that PGAdapter is started and running\n on the same machine as your Liquibase installation. For more information, see\n [Start PGAdapter](/spanner/docs/pgadapter-start).\n\n- For PostgreSQL-dialect databases only, use the [create_database_change_log.sql](https://github.com/GoogleCloudPlatform/pgadapter/blob/-/samples/java/liquibase/create_database_change_log.sql)\n script to create the `databasechangeloglock` and `databasechangelog` metadata\n tables. You must create these tables to override the tables that Liquibase\n creates automatically in your database. This is to ensure that the correct\n PostgreSQL data types for Spanner are used in these\n tables.\n\n You can run the script with the following command: \n\n ```\n psql -h localhost -d DATABASE_NAME -f create_database_change_log.sql\n ```\n- Give the Spanner Liquibase extension temporary use of your\n Spanner user credentials for API access by running the\n following `gcloud` command:\n\n ```\n gcloud auth application-default login\n ```\n\n### Create a changelog.yaml\n\n1. Enter the following YAML into your favorite editor.\n\n databaseChangeLog:\n - preConditions:\n onFail: HALT\n onError: HALT\n\n - changeSet:\n id: create-singers-table\n author: spanner-examples\n changes:\n - createTable:\n tableName: Singers\n columns:\n - column:\n name: SingerId\n type: BIGINT\n constraints:\n primaryKey: true\n primaryKeyName: pk_Singers\n - column:\n name: Name\n type: VARCHAR(255)\n\n This YAML defines a table called `Singers` with a primary key `SingerId` and a\n column called `Name` to store the singer's name.\n\n For PostgreSQL-dialect databases, we recommend using all lower case for table and column\n names. For more information, see\n [PostgreSQL case sensitivity](/spanner/docs/reference/postgresql/lexical#case-sensitivity).\n\n Note that the `createTable` change set must include a primary key constraint,\n and the name of the primary key constraint must be pk_\u003cvar translate=\"no\"\u003etable_name\u003c/var\u003e.\n2. Save your changes as `changelog.yaml`.\n\n### Run Liquibase\n\nApply the changeset in `changelog.yaml` by executing the following command: \n\n```\nliquibase --changeLogFile changelog.yaml update\n```\n\nLiquibase uses the URL that you defined in the `liquibase.properties` file. You\ncan override the value in the file by adding the following argument to the\npreceding command: \n\n```\n--url URL\n```\n\n### Verify your changes\n\nThe updates in the preceding step caused the `Singer` table to be added to your\ndatabase. Also, the `DATABASECHANGELOG` and `DATABASECHANGELOGLOCK` tables were\nadded (GoogleSQL-dialect database) or updated (PostgreSQL-dialect database).\n\nYou can verify the existence of these tables through the Google Cloud console\nor gcloud CLI. For example, running the SQL query `SELECT * FROM\nINFORMATION_SCHEMA.TABLES` returns a list of all tables in your database. \n\n```\ngcloud spanner databases execute-sql DATABASE_NAME --instance=INSTANCE \\\n --sql='SELECT * FROM INFORMATION_SCHEMA.TABLES'\n```\n\nYou can see a record of the changes that were applied by querying the contents\nof `DATABASECHANGELOG`.\n\nWhat's next\n-----------\n\n- For more documentation, visit the [Spanner Liquibase Extension](https://github.com/cloudspannerecosystem/liquibase-spanner)\n GitHub repository.\n\n- To learn more about Liquibase, see [Getting Started with Liquibase](https://www.liquibase.org/get-started)."]]
