Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Halaman ini menjelaskan cara mengelola perubahan skema database Spanner
dengan Liquibase untuk database dialek GoogleSQL dan database dialek PostgreSQL.
Liquibase adalah library independen database open source untuk melacak, mengelola,
dan menerapkan perubahan skema database. Format ini mendukung SQL serta format
deklaratif seperti XML, YAML, dan JSON.
Liquibase dapat menargetkan database Spanner. API ini mendukung semua
fitur Spanner, dengan beberapa batasan.
Untuk melihat informasi tambahan tentang database dialek PostgreSQL, seperti persyaratan
Liquibase, jenis perubahan yang didukung, dan batasan, lihat
PGAdapter dan Liquibase.
Menginstal Liquibase
Untuk menggunakan Liquibase dengan database dialek GoogleSQL, Anda harus menginstal
ekstensi Spanner Liquibase. Untuk database dialek PostgreSQL, Liquibase dapat menggunakan
dukungan PostgreSQL bawaannya bersama dengan
PGAdapter.
GoogleSQL
Ikuti petunjuk dalam dokumentasi Liquibase untuk menginstal dan mengonfigurasi Liquibase, serta mengambil snapshot database Anda. Dalam file konfigurasi liquibase.properties, tetapkan properti url sebagai berikut.
Buka halaman rilis Ekstensi Liquibase Spanner di GitHub, lalu pilih rilis terbaru.
Pilih dan download file JAR dengan nama
liquibase-spanner-x.y.z-all.jar, dengan x.y.z mewakili nomor versi
ekstensi. Contoh, liquibase-spanner-4.17.0-all.jar.
Tempatkan file JAR yang didownload di direktori lib Liquibase. File JAR
menyertakan ekstensi, Spanner SDK, dan
driver driver JDBC Spanner.
PostgreSQL
Pastikan PGAdapter dimulai dan berjalan di komputer
tempat Anda menginstal Liquibase. Untuk mengetahui informasi selengkapnya, lihat Memulai
PGAdapter.
Ikuti petunjuk dalam dokumentasi Liquibase untuk menginstal dan mengonfigurasi Liquibase, serta mengambil snapshot database Anda.
Dalam file konfigurasi liquibase.properties, tetapkan properti url sebagai
berikut.
File konfigurasi liquibase.properties Anda hanya dapat berisi properti
ini. Properti lainnya bersifat opsional.
String url harus menyertakan
options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction
karena Spanner tidak mendukung transaksi DDL, dan hal ini
memastikan bahwa transaksi DDL dikonversi menjadi batch DDL. Untuk informasi
selengkapnya, lihat Opsi DDL untuk PGAdapter.
Meninjau contoh Liquibase
GoogleSQL
Contoh file log perubahan changelog.yaml yang disertakan dengan ekstensi GoogleSQL Liquibase menunjukkan banyak fitur Liquibase dan cara menggunakannya dengan Spanner.
PostgreSQL
Contoh file log perubahan dbchangelog.xml yang tersedia di
repositori GitHub PGAdapter dan Liquibase
menunjukkan banyak fitur Liquibase dan cara menggunakannya dengan
Spanner.
Panduan memulai Liquibase
Panduan memulai ini menunjukkan cara menggunakan Liquibase untuk menambahkan tabel Singers ke database.
Sebelum memulai
Pastikan Anda telah menyelesaikan langkah-langkah sebelumnya untuk menginstal
Liquibase.
Buat instance Spanner.
Buat database dialek GoogleSQL atau database dialek PostgreSQL.
Khusus untuk database dialek PostgreSQL, pastikan PGAdapter dimulai dan berjalan
di komputer yang sama dengan penginstalan Liquibase Anda. Untuk mengetahui informasi selengkapnya, lihat
Memulai PGAdapter.
Khusus untuk database dialek PostgreSQL, gunakan skrip create_database_change_log.sql
untuk membuat tabel metadata databasechangeloglock dan databasechangelog. Anda harus membuat tabel ini untuk mengganti tabel yang dibuat Liquibase secara otomatis di database Anda. Hal ini untuk memastikan bahwa jenis data PostgreSQL yang benar untuk Spanner digunakan dalam tabel ini.
Anda dapat menjalankan skrip dengan perintah berikut:
Berikan penggunaan sementara kredensial pengguna Spanner Anda kepada ekstensi Spanner Liquibase untuk akses API dengan menjalankan perintah gcloud berikut:
YAML ini menentukan tabel yang disebut Singers dengan kunci utama SingerId dan
kolom yang disebut Name untuk menyimpan nama penyanyi.
Untuk database dialek PostgreSQL, sebaiknya gunakan semua huruf kecil untuk nama tabel dan kolom. Untuk informasi selengkapnya, lihat
Kesadaran huruf besar/kecil PostgreSQL.
Perhatikan bahwa set perubahan createTable harus menyertakan batasan kunci utama,
dan nama batasan kunci utama harus pk_table_name.
Simpan perubahan sebagai changelog.yaml.
Menjalankan Liquibase
Terapkan changeset di changelog.yaml dengan menjalankan perintah berikut:
liquibase --changeLogFile changelog.yaml update
Liquibase menggunakan URL yang Anda tentukan dalam file liquibase.properties. Anda
dapat mengganti nilai dalam file dengan menambahkan argumen berikut ke
perintah sebelumnya:
--url URL
Memverifikasi perubahan Anda
Pembaruan pada langkah sebelumnya menyebabkan tabel Singer ditambahkan ke database Anda. Selain itu, tabel DATABASECHANGELOG dan DATABASECHANGELOGLOCK
ditambahkan (database dialek GoogleSQL) atau diperbarui (database dialek PostgreSQL).
Anda dapat memverifikasi keberadaan tabel ini melalui Google Cloud konsol
atau gcloud CLI. Misalnya, menjalankan kueri SQL SELECT * FROM
INFORMATION_SCHEMA.TABLES akan menampilkan daftar semua tabel dalam database Anda.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 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)."]]
