Mengintegrasikan Spanner dengan Liquibase

Halaman ini menjelaskan cara mengelola perubahan skema database Spanner dengan Liquibase.

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 batasan umum, lihat 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

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

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

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

  2. Buka halaman rilis Ekstensi Liquibase Spanner 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 menyertakan ekstensi, Spanner SDK, dan driver driver JDBC Spanner.

PostgreSQL

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

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

    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 akan memastikan bahwa transaksi DDL dikonversi secara otomatis ke batch DDL. Untuk informasi selengkapnya, lihat Opsi DDL untuk PGAdapter.

Meninjau contoh Liquibase

GoogleSQL

Contoh file log perubahan changelog.yaml yang disertakan dengan ekstensi Liquibase GoogleSQL 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, buat tabel metadata databasechangeloglock dan databasechangelog menggunakan skrip create_database_change_log.sql. 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 sendiri kepada ekstensi Spanner Liquibase untuk akses API dengan menjalankan perintah gcloud berikut:

    gcloud auth application-default login

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

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