Mengintegrasikan Spanner dengan Liquibase

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

Liquibase adalah library open source independen 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. Fitur 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.

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 untuk mengambil snapshot database Anda. Di file konfigurasi liquibase.properties, tetapkan properti url sebagai berikut.

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

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

  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 telah 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 untuk 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 boleh 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 ini akan memastikan bahwa transaksi DDL otomatis dikonversi 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 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.

  • Membuat 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 dilakukan 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

  • Beri ekstensi Spanner Liquibase penggunaan sementara kredensial pengguna Spanner Anda sendiri 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 mengetahui informasi selengkapnya, baca artikel Sensitivitas huruf PostgreSQL.

    Perhatikan bahwa kumpulan perubahan createTable harus menyertakan batasan kunci utama, dan nama batasan kunci utama harus pk_table_name.

  2. Simpan perubahan sebagai changelog.yaml.

Jalankan 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 telah ditambahkan (database dialek GoogleSQL) atau diperbarui (database dialek PostgreSQL).

Anda dapat memverifikasi keberadaan tabel ini melalui Google Cloud Console 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 data perubahan yang diterapkan dengan mengkueri konten DATABASECHANGELOG.

Langkah selanjutnya