Liquibase 요구사항, 지원되는 변경 유형, 제한사항 등 PostgreSQL 언어 데이터베이스에 관한 자세한 내용은 PGAdapter 및 Liquibase를 참조하세요.
Liquibase 설치
GoogleSQL 언어 데이터베이스에서 Liquibase를 사용하려면 Spanner Liquibase 확장 프로그램을 설치해야 합니다. PostgreSQL 언어 데이터베이스의 경우 Liquibase는 PGAdapter와 함께 기본 제공되는 PostgreSQL 지원을 사용할 수 있습니다.
GoogleSQL
Liquibase 문서의 안내에 따라 Liquibase를 설치 및 구성하고 데이터베이스의 스냅샷을 만듭니다. liquibase.properties 구성 파일에서 url 속성을 다음과 같이 설정합니다.
liquibase.properties 구성 파일에는 이 속성만 포함할 수 있습니다. 다른 속성은 선택사항입니다.
Spanner는 DDL 트랜잭션을 지원하지 않으므로 url 문자열에 options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction이 포함되어야 합니다. 이렇게 하면 DDL 트랜잭션이 DDL 배치로 변환됩니다. 자세한 내용은 PGAdapter의 DDL 옵션을 참조하세요.
Liquibase 샘플 검토
GoogleSQL
GoogleSQL Liquibase 확장 프로그램에 포함된 샘플 변경 로그 파일 changelog.yaml은 Liquibase의 많은 기능과 이를 Spanner와 함께 사용하는 방법을 보여줍니다.
GoogleSQL 언어 데이터베이스 또는 PostgreSQL 언어 데이터베이스를 만듭니다.
PostgreSQL 언어 데이터베이스에만 해당하는 경우 PGAdapter가 Liquibase 설치와 동일한 머신에서 시작되고 실행 중인지 확인합니다. 자세한 내용은 PGAdapter 시작을 참조하세요.
PostgreSQL 언어 데이터베이스의 경우에만 create_database_change_log.sql 스크립트를 사용하여 databasechangeloglock 및 databasechangelog 메타데이터 테이블을 만듭니다. Liquibase가 데이터베이스에 자동으로 만드는 테이블을 재정의하려면 이러한 테이블을 만들어야 합니다. 이러면 Spanner에 올바른 PostgreSQL 데이터 유형이 이러한 테이블에 사용되도록 보장합니다.
이 YAML은 기본 키 SingerId 및 Name이라는 열을 사용해서 가수 이름을 저장하기 위한 Singers라는 테이블을 정의합니다.
PostgreSQL 언어 데이터베이스의 경우 테이블 및 열 이름에 소문자를 모두 사용하는 것이 좋습니다. 자세한 내용은 PostgreSQL 대소문자 구분을 참조하세요.
createTable 변경 세트에는 기본 키 제약조건이 포함되어야 하며 기본 키 제약조건의 이름은 pk_table_name여야 합니다.
변경사항을 changelog.yaml로 저장합니다.
Liquibase 실행
다음 명령어를 실행하여 changelog.yaml의 변경사항 집합을 적용합니다.
liquibase --changeLogFile changelog.yaml update
Liquibase는 liquibase.properties 파일에 정의된 URL을 사용합니다. 이전 명령어에 다음 인수를 추가하여 파일의 값을 재정의할 수 있습니다.
--url URL
변경사항 확인
이전 단계의 업데이트로 인해 Singer 테이블이 데이터베이스에 추가되었습니다. 또한 DATABASECHANGELOG 및 DATABASECHANGELOGLOCK 테이블이 추가(GoogleSQL 언어 데이터베이스) 또는 업데이트(PostgreSQL 언어 데이터베이스)되었습니다.
Google Cloud 콘솔 또는 gcloud CLI를 통해 이러한 테이블이 있는지 확인할 수 있습니다. 예를 들어 SQL 쿼리 SELECT * FROM
INFORMATION_SCHEMA.TABLES를 실행하면 데이터베이스에 있는 모든 테이블 목록이 반환됩니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 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)."]]
