Mengintegrasikan Spanner dengan Liquibase

Halaman ini menjelaskan cara mengelola perubahan skema database Spanner dengan Liquibase untuk database dialek GoogleSQL dan database dialek PostgreSQL.

Liquibase adalah library open source yang independen dari database untuk melacak, mengelola, dan menerapkan perubahan skema database. Alat ini mendukung SQL serta format deklaratif seperti XML, YAML, dan JSON.

Liquibase dapat menargetkan database Spanner. Layanan ini mendukung semua fitur Spanner, dengan beberapa batasan.

  • Untuk melihat batasan umum, lihat batasan.
  • Untuk melihat informasi tambahan untuk database dialek PostgreSQL, seperti persyaratan Liquibase, jenis perubahan yang didukung, dan batasan, lihat PGAdapter dan Liquibase.

Instal 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

  1. Ikuti petunjuk dalam dokumentasi Liquibase untuk menginstal dan mengonfigurasi Liquibase, serta mengambil snapshot database Anda.

  2. Buka halaman rilis Spanner Liquibase Extension di GitHub, lalu pilih rilis terbaru.

  3. 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.

  4. Tempatkan file JAR yang didownload di direktori lib Liquibase. File JAR mencakup ekstensi, Spanner SDK, dan driver JDBC Spanner.

Di file konfigurasi liquibase.properties, tetapkan properti url sebagai berikut.

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

File konfigurasi liquibase.properties Anda hanya dapat berisi properti ini. Properti lainnya bersifat opsional.

PostgreSQL

  1. Pastikan PGAdapter dimulai dan berjalan di komputer tempat Anda menginstal Liquibase. Untuk mengetahui informasi selengkapnya, lihat Mulai PGAdapter.

  2. Ikuti petunjuk dalam dokumentasi Liquibase untuk menginstal dan mengonfigurasi Liquibase, serta mengambil snapshot database Anda.

Di file konfigurasi liquibase.properties, tetapkan properti url sebagai berikut.

  jdbc:postgresql://localhost:5432/DATABASE_NAME?options=-c%20spanner.ddl_transaction_mode=AutocommitExplicitTransaction

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 mengetahui informasi selengkapnya, lihat Opsi DDL untuk PGAdapter.

Tinjau contoh Liquibase

GoogleSQL

File log perubahan contoh changelog.yaml yang disertakan dengan ekstensi GoogleSQL Liquibase menunjukkan banyak fitur Liquibase dan cara menggunakannya dengan Spanner.

PostgreSQL

File log perubahan contoh 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 mesin yang sama dengan penginstalan Liquibase Anda. Untuk mengetahui informasi selengkapnya, lihat Mulai 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:

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

  • Berikan penggunaan sementara kredensial pengguna Spanner Anda untuk akses API ke ekstensi Spanner Liquibase dengan menjalankan perintah gcloud berikut:

    gcloud auth application-default login

Buat changelog.yaml

  1. Masukkan YAML berikut ke editor favorit Anda.

    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)

    YAML ini menentukan tabel bernama Singers dengan kunci utama SingerId dan kolom bernama Name untuk menyimpan nama penyanyi.

    Untuk database dialek PostgreSQL, sebaiknya gunakan huruf kecil semua untuk nama tabel dan kolom. Untuk mengetahui informasi selengkapnya, lihat Sensitivitas huruf besar/kecil PostgreSQL.

    Perhatikan bahwa set perubahan createTable harus menyertakan batasan kunci primer, dan nama batasan kunci primer harus pk_table_name.

  2. Simpan perubahan Anda 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 konsol Google Cloud atau gcloud CLI. Misalnya, menjalankan kueri SQL SELECT * FROM INFORMATION_SCHEMA.TABLES akan menampilkan daftar semua tabel di database Anda.

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

Anda dapat melihat catatan perubahan yang diterapkan dengan membuat kueri konten DATABASECHANGELOG.

Langkah berikutnya