Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
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.
GoogleSQL
Siga as instruções na documentação do Liquibase
para instalar e configurar o Liquibase e fazer um snapshot do seu banco de dados.
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 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.
No arquivo de configuração liquibase.properties, defina a propriedade url da seguinte maneira.
Seu arquivo de configuração liquibase.properties pode conter apenas essa propriedade. Outras propriedades são opcionais.
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 maneira.
Seu 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 elas sejam convertidas em lotes DDL. Para mais informações, consulte Opções de DDL para PGAdapter.
Analise os exemplos do Liquibase
GoogleSQL
O arquivo de registro de mudanças de exemplo 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ças de exemplo 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
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:
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:
O conjunto de mudanças createTable precisa incluir uma restrição de chave primária, e o nome dela precisa ser pk_table_name.
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.
[[["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-10 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)."]]
