Hologres：REBUILD (Beta)

Format perintah

ASYNC REBUILD TABLE [ IF EXISTS ] <table_name>
    [ WITH ( <rebuild_parameter> [= <value>] [, ... ] )]  
    <action> [, ... ];
    
WHERE action IS ONE OF:
    ADD [ COLUMN ] <column_name> <data_type> [ column_constraint [ ... ] ]
    ALTER [ COLUMN ] <column_name> [ SET DATA ] TYPE <data_type> [ USING <expression> ]
    ALTER [ COLUMN ] <column_name> SET DEFAULT <expression>
    ALTER [ COLUMN ] <column_name> DROP DEFAULT
    ALTER [ COLUMN ] <column_name> { SET | DROP } NOT NULL
    ALTER PRIMARY KEY (<column_name> [, ...])
    TO [LOGICAL] PARTITION [BY LIST(<column_name> [, <column_name>])]
    SET ( <parameter> [= <value>] [, ... ] )

WHERE rebuild_parameter IS ONE OF:
    keep_source
    binlog_mode
    rebuild_guc_<guc_name> = '<guc_value>'

Parameter

Jalankan REBUILD pada tabel tanpa binary logging

-- Buat tabel dan impor data.
CREATE TABLE rebuild_test (
    a TEXT,
    b TEXT,
    ds TEXT
);

INSERT INTO rebuild_test VALUES ('1', '1', '2025-04-01'), ('2', '2', '2025-04-02'), ('3', '3', '2025-04-03');

-- Tambahkan kolom NOT NULL dan tetapkan nilai default.
ASYNC REBUILD TABLE rebuild_test ADD COLUMN c text NOT NULL DEFAULT 'a';

-- Ubah primary key menjadi kolom a.
ASYNC REBUILD TABLE rebuild_test ALTER PRIMARY KEY (a);

-- Gunakan sumber daya Serverless untuk menjalankan task Rebuild. 
-- Tetapkan distribution_key dan clustering_key untuk tabel, serta ubah orientasi menjadi penyimpanan hibrida baris-kolom.
ASYNC REBUILD TABLE rebuild_test 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    distribution_key = 'a',
    clustering_key = 'a',
    orientation = 'row,column'
);

-- Konversi tabel standar menjadi tabel partisi logis. 
-- Tetapkan kunci partisi ke ds dan tambahkan kendala NOT NULL ke kolom ds.
ASYNC REBUILD TABLE rebuild_test 
    ALTER COLUMN ds SET NOT NULL,
    TO LOGICAL PARTITION BY LIST(ds);

Jalankan REBUILD pada tabel dengan binary logging

Perintah REBUILD tidak menyimpan data binary logging (Binlog) historis. Oleh karena itu, Anda tidak dapat menjalankan REBUILD pada tabel yang telah mengaktifkan binary logging secara default. Untuk melakukan operasi ini, Anda harus mengonfigurasi parameter binlog_mode dalam task REBUILD dan mengikuti langkah-langkah berikut. Proses ini memastikan bahwa client downstream telah mengonsumsi semua data Binlog historis sebelum tabel direbuild.

1. Jalankan REBUILD.

   ASYNC REBUILD TABLE rebuild_test 
   WITH (
     binlog_mode
   )
   <your_action>;

2. Untuk task REBUILD yang mencakup parameter binlog_mode, task tersebut secara otomatis berhenti setelah langkah set_readonly selesai. Anda dapat memeriksa progres dengan menjalankan perintah SQL berikut. Pada titik ini, sistem telah menetapkan tabel menjadi read-only. Anda tidak dapat menulis data ke tabel tersebut, dan tidak ada data Binlog baru yang dihasilkan.

   postgres=# SELECT step, status, progress FROM hologres.rebuild_progress('<query_id>');
                step              | status | progress 
   -------------------------------+--------+----------
    prepare                       | done   | 1/1
    create_tmp_table              | done   | 1/1
    get_src_table_snapshot        | done   | 1/1
    insert                        | done   | 1/1
    set_readonly                  | done   | 1/1
    check_snapshot                |        | 0/1
    re-insert                     |        | -
    check_additional_child_table  |        | -
    create_additional_child_table |        | -
    insert_additional_child_table |        | -
    swap                          |        | 0/1
   (11 rows)

3. Tunggu hingga client downstream selesai mengonsumsi data Binlog yang ada. Kemudian, jalankan secara manual perintah SQL berikut untuk melanjutkan task REBUILD. Selama proses ini, tabel sumber tetap dalam mode read-only, dan tidak ada data Binlog baru yang dihasilkan.

   RESUME '<query_id>';

   Setelah task REBUILD berhasil diselesaikan, binary logging secara otomatis diaktifkan untuk tabel baru. Anda kemudian dapat merestart task konsumsi Binlog downstream. Konsumsi Binlog tabel baru harus dimulai dari lsn = 0.

Periksa status task REBUILD

Task REBUILD dijalankan secara asinkron. Saat Anda mengirimkan task, sistem mengembalikan status sukses untuk pengiriman dan query_id. Anda harus memeriksa status sub-task asinkron di tabel sistem hologres.rebuild_progress. Operasi REBUILD hanya dianggap selesai setelah semua sub-task berhasil. Anda dapat menggunakan perintah berikut untuk memeriksa status:

SELECT * FROM hologres.rebuild_progress('<rebuild_query_id>');

Kolom tabel sistem dan deskripsinya adalah sebagai berikut:

Berikut adalah hasil sampel:

Hentikan dan mulai ulang tugas REBUILD

• Jeda task REBUILD asinkron.

  SUSPEND '<query_id>';

• Lanjutkan tugas asinkron yang dijeda dengan menggunakan perintah CANCEL.

  RESUME '<query_id>';

Tangani pengecualian tugas REBUILD

Jika task REBUILD terganggu oleh error atau dijeda secara manual dengan perintah SUSPEND, Anda dapat menggunakan perintah RESUME untuk melanjutkan task tersebut. Atau, Anda dapat mengikuti langkah-langkah berikut untuk mengakhiri task dan memulihkan tabel sumber.

• Gunakan perintah berikut untuk membersihkan tabel sementara yang dibuat selama proses REBUILD.

  CALL hg_clean_rebuild_tmp_tables('<query_id>');

• Jika task terganggu setelah tabel sumber ditetapkan menjadi read-only, gunakan perintah berikut untuk mengembalikan operasi tulis ke tabel tersebut.

  ALTER TABLE <table_name> SET (readonly = false);