All Products
Search
Document Center

PolarDB:wal2json (decoding to JSON)

Last Updated:Jan 31, 2026

PolarDB for PostgreSQL menyediakan plugin wal2json yang menghasilkan file log logis dalam format JSON.

Keberlakuan

Versi mesin minor PolarDB for PostgreSQL yang didukung adalah sebagai berikut:

  • PostgreSQL 18 (versi mesin minor 2.0.18.1.1.0 atau lebih baru)

  • PostgreSQL 17 (versi mesin minor 2.0.17.7.5.0 atau lebih baru)

  • PostgreSQL 16 (versi mesin minor 2.0.16.6.2.0 atau lebih baru)

  • PostgreSQL 15 (versi mesin minor 2.0.15.12.4.0 atau lebih baru)

  • PostgreSQL 14 (versi mesin minor 2.0.14.5.1.0 atau lebih baru)

  • PostgreSQL 11 (versi mesin minor 2.0.11.9.29.0 atau lebih baru)

Catatan

Anda dapat melihat versi mesin minor di Konsol atau dengan menjalankan pernyataan SHOW polardb_version;. Jika versi Anda tidak didukung, Anda harus meningkatkan versi mesin minor.

Informasi Latar Belakang

wal2json adalah plugin logical decoding dengan fitur-fitur berikut:

  • Mendekode tupel yang dihasilkan oleh operasi INSERT dan UPDATE.

  • Dapat mengambil versi baris sebelumnya dari operasi UPDATE dan DELETE, berdasarkan identitas replika yang dikonfigurasi.

  • Dapat mengonsumsi perubahan baik melalui protokol streaming (logical replication slots) maupun API SQL khusus.

Plugin wal2json menghasilkan satu objek JSON untuk setiap transaksi. Objek JSON ini mencakup semua tupel lama dan baru. Anda dapat menggunakan opsi untuk menyertakan properti seperti timestamp transaksi, skema, tipe data, dan ID transaksi. Untuk informasi selengkapnya, lihat Retrieve JSON objects using SQL.

Catatan Penting

  • Karena PolarDB for PostgreSQL menggunakan REPLICA_IDENTITY_FULL, data baris lengkap dicatat untuk operasi update dan delete, bukan hanya data dari kolom yang berubah. Untuk mencatat hanya data dari kolom yang berubah, nonaktifkan parameter polar_create_table_with_full_replica_identity. Parameter ini tidak dapat diubah melalui console. Contact us untuk bantuan.

  • Plugin wal2json memerlukan logical decoding. Untuk mengaktifkan fitur ini, atur parameter wal_level ke logical.

    Catatan

    Anda dapat mengatur parameter `wal_level` di console. Untuk informasi selengkapnya, lihat Set cluster parameters. Perubahan ini memerlukan restart kluster. Rencanakan workload Anda sesuai.

Ambil Objek JSON Menggunakan SQL

Anda tidak membuat plugin wal2json menggunakan CREATE EXTENSION. Sebagai gantinya, Anda dapat memuatnya melalui logical replication slot.

  1. Setelah membuat logical replication slot dengan plugin wal2json, jalankan perintah berikut untuk mengambil objek JSON dari WAL.

    -- Create tables with and without a primary key
    CREATE TABLE table2_with_pk (a SERIAL, b VARCHAR(30), c TIMESTAMP NOT NULL, PRIMARY KEY(a, c));
    CREATE TABLE table2_without_pk (a SERIAL, b NUMERIC(5,2), c TEXT);
    
    -- Create a logical replication slot of type wal2json
    SELECT 'init' FROM pg_create_logical_replication_slot('test_slot', 'wal2json');
    
    -- Commit the transaction to write to WAL
    BEGIN;
    INSERT INTO table2_with_pk (b, c) VALUES('Backup and Restore', now());
    INSERT INTO table2_with_pk (b, c) VALUES('Tuning', now());
    INSERT INTO table2_with_pk (b, c) VALUES('Replication', now());
    DELETE FROM table2_with_pk WHERE a < 3;
    
    INSERT INTO table2_without_pk (b, c) VALUES(2.34, 'Tapir');
    UPDATE table2_without_pk SET c = 'Anta' WHERE c = 'Tapir';
    COMMIT;
    
    -- Retrieve JSON objects from WAL
    SELECT data FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', '1');

    Output-nya adalah sebagai berikut:

    {
        "change": [
            {
                "kind": "insert",
                "schema": "public",
                "table": "table2_with_pk",
                "columnnames": ["a", "b", "c"],
                "columntypes": ["integer", "character varying(30)", "timestamp without time zone"],
                "columnvalues": [1, "Backup and Restore", "2018-03-27 12:05:29.914496"]
            }
            ,{
                "kind": "insert",
                "schema": "public",
                "table": "table2_with_pk",
                "columnnames": ["a", "b", "c"],
                "columntypes": ["integer", "character varying(30)", "timestamp without time zone"],
                "columnvalues": [2, "Tuning", "2018-03-27 12:05:29.914496"]
            }
            ,{
                "kind": "insert",
                "schema": "public",
                "table": "table2_with_pk",
                "columnnames": ["a", "b", "c"],
                "columntypes": ["integer", "character varying(30)", "timestamp without time zone"],
                "columnvalues": [3, "Replication", "2018-03-27 12:05:29.914496"]
            }
            ,{
                "kind": "delete",
                "schema": "public",
                "table": "table2_with_pk",
                "oldkeys": {
                    "keynames": ["a", "c"],
                    "keytypes": ["integer", "timestamp without time zone"],
                    "keyvalues": [1, "2018-03-27 12:05:29.914496"]
                }
            }
            ,{
                "kind": "delete",
                "schema": "public",
                "table": "table2_with_pk",
                "oldkeys": {
                    "keynames": ["a", "c"],
                    "keytypes": ["integer", "timestamp without time zone"],
                    "keyvalues": [2, "2018-03-27 12:05:29.914496"]
                }
            }
            ,{
                "kind": "insert",
                "schema": "public",
                "table": "table2_without_pk",
                "columnnames": ["a", "b", "c"],
                "columntypes": ["integer", "numeric(5,2)", "text"],
                "columnvalues": [1, 2.34, "Tapir"]
            }
        ]
    }
  2. Jalankan perintah berikut untuk menghapus slot replikasi test_slot. Perintah ini mengembalikan string 'stop'.

    SELECT 'stop' FROM pg_drop_replication_slot('test_slot');

Deskripsi Parameter

Tabel berikut menjelaskan parameter-parameter wal2json.

Parameter

Deskripsi

change

Entri WAL untuk setiap operasi DML, seperti INSERT, UPDATE, DELETE, atau TRUNCATE.

changeset

Kumpulan beberapa entri change.

include-xids

Mengontrol apakah akan menambahkan xid ke setiap changeset. Default: false.

  • true: Tambahkan xid ke setiap changeset.

  • false (default): Jangan tambahkan xid ke setiap changeset.

include-timestamp

Mengontrol apakah akan menambahkan timestamp ke setiap changeset. Default: false.

  • true: Tambahkan timestamp ke setiap changeset.

  • false (default): Jangan tambahkan timestamp ke setiap changeset.

include-schemas

Mengontrol apakah akan menambahkan nama skema ke setiap change. Default: true.

  • true (default): Tambahkan nama skema ke setiap change.

  • false: Jangan tambahkan nama skema ke setiap change.

include-types

Mengontrol apakah akan menambahkan tipe data ke setiap change. Default: true.

  • true (default): Tambahkan tipe data ke setiap change.

  • false: Jangan tambahkan tipe data ke setiap change.

include-typmod

Menambahkan pengubah ke tipe yang memilikinya (misalnya, varchar(20) alih-alih varchar). Default: true.

  • true (default): Tambahkan pengubah ke tipe yang memilikinya.

  • false: Jangan tambahkan pengubah ke tipe yang memilikinya.

include-type-oids

Mengontrol apakah akan menambahkan OID tipe. Default: false.

  • true: Tambahkan OID tipe.

  • false (default): Jangan tambahkan OID tipe.

include-not-null

Mengontrol apakah akan menambahkan informasi not null sebagai columnoptionals. Default: false.

  • true: Tambahkan informasi not null sebagai columnoptionals.

  • false (default): Jangan tambahkan informasi not null sebagai columnoptionals.

pretty-print

Mengontrol apakah akan menambahkan spasi dan indentasi untuk memformat struktur JSON. Default: false.

  • true: Tambahkan spasi dan indentasi untuk memformat struktur JSON.

  • false (default): Jangan tambahkan spasi dan indentasi. Tidak ada pemformatan yang diterapkan.

write-in-chunks

Mengontrol apakah akan menulis setelah setiap change alih-alih setelah setiap changeset. Default: false.

  • true: Tulis setelah setiap change, bukan setelah setiap changeset.

  • false (default): Tulis setelah setiap changeset, bukan setelah setiap change.

include-lsn

Mengontrol apakah akan menambahkan nextlsn ke setiap changeset. Default: false.

  • true: Tambahkan nextlsn ke setiap changeset.

  • false (default): Jangan tambahkan nextlsn ke setiap changeset.

filter-tables

Mengecualikan tabel tertentu. Default: kosong (tidak ada tabel yang difilter).

Catatan
  • Pisahkan beberapa tabel dengan koma. Tentukan skema untuk setiap tabel.

  • *.foo cocok dengan tabel foo di semua skema. bar.* cocok dengan semua tabel di skema bar.

  • Escape karakter khusus (spasi, tanda kutip tunggal, koma, titik, tanda bintang) dengan backslash (\).

  • Nama skema dan tabel bersifat case-sensitive.

  • Tabel Foo bar di skema public dirujuk sebagai public.Foo\bar.

add-tables

Menentukan tabel yang akan didekode. Secara default, semua tabel di semua skema didekode. Penggunaannya sama seperti filter-tables.

filter-msg-prefixes

Mengecualikan baris dengan awalan tertentu. Biasanya digunakan dengan fungsi pg_logical_slot_peek_changes(). Default: kosong (tidak ada filter). Pisahkan beberapa awalan dengan koma.

add-msg-prefixes

Menyertakan baris dengan awalan tertentu. Biasanya digunakan dengan fungsi pg_logical_slot_peek_changes(). Default: semua awalan. Pisahkan beberapa awalan dengan koma. Gunakan filter-msg-prefixes sebelum parameter ini.

format-version

Menentukan versi format output. Default: 1.

  • 1: Gunakan format output versi 1.

  • 2: Gunakan format output versi 2.

actions

Menentukan operasi mana yang akan di-output. Default: all (INSERT, UPDATE, DELETE, dan TRUNCATE). Jika Anda menggunakan format-version 1, TRUNCATE tidak diaktifkan.

Contoh

Contoh berikut menunjukkan cara menggunakan parameter include-xids.

  1. Buat tabel dan logical replication slot, lalu masukkan satu baris.

    DROP TABLE IF EXISTS tbl;
    CREATE TABLE tbl (id int);
    SELECT 'init' FROM pg_create_logical_replication_slot('regression_slot', 'wal2json');
    INSERT INTO tbl VALUES (1);
  2. Berikan nama dan nilai parameter ke fungsi.

    SELECT    
    count(*) = 1,    
    count(distinct ((data::json)->'xid')::text) = 1
    FROM pg_logical_slot_get_changes(    
    'regression_slot', NULL, NULL,    
    'format-version', '1',    
    'include-xids', '1');

Prinsip Desain

Untuk informasi lebih lanjut dan prinsip desain, lihat dokumentasi resmi.