Hologres：訂閱Hologres Binlog

在Hologres中訂閱Hologres Binlog需要注意如下事項：

• 僅Hologres V0.9及以上版本支援訂閱Hologres Binlog，如果您的執行個體是V0.9以下版本，請您加入線上支援DingTalk群，詳情請參見如何擷取更多的線上支援？。

• Hologres V0.9以及V0.10版本，已存在的表無法修改表屬性開啟Binlog，需重建立表。從V1.1版本開始，可以按需開啟Binlog。

• Hologres V1.3.14和V1.1.82之前的版本僅支援Superuser消費Binlog，如果使用其他低許可權帳號消費Binlog會出現沒有許可權的報錯：permission denied for table hg_replication_slot_properties。從Hologres V1.3.14和V1.1.82版本開始，若使用Flink消費Binlog，僅需帳號具備查詢表的許可權即可。對於使用JDBC消費Hologres Binlog需要帳號在Replication Role中。

• Hologres支援單表層級的Binlog功能，支援行存表和列存表。當前訂閱Hologres Binlog支援的情況如下表。

  Flink分類	Hologres行存表Binlog	Hologres列存表Binlog	Hologres行列共存表Binlog（從Hologres V1.1版本開始支援）
  Realtime ComputeBlink	支援	支援	支援
  全託管Flink	支援	支援	支援
  開源Flink	不支援	不支援	不支援
  JDBC	Hologres V1.1版本開始支援	Hologres V1.1版本開始支援	Hologres V1.1版本開始支援

• Blink消費Hologres Binlog暫不支援Hologres的TIMESTAMP類型，在Hologres建表時，請使用TIMESTAMPTZ類型。同時也不支援SMALLINT等特殊類型。

• 不支援消費分區表父表的Binlog，請使用分區子表或者普通表（非分區表）。Hologres從 V1.3.24版本開始，支援按需修改分區子表的Binlog TTL，若是沒有顯式指定分區子表的Binlog TTL，則與父表的Binlog TTL保持一致。同時需要注意Binlog TTL不是精準的時間，系統不會強保證Binlog到期後立馬刪除Binlog，將會在到期後的某個時間刪除。

• 對於更新頻繁的情境，理論上列存表開啟Binlog的開銷要大於行存表的開銷，所以建議使用行存表開啟Binlog。

• 僅Hologres內部表支援開啟Binlog，外部表格不支援開啟Binlog。

Binlog記錄由Binlog系統欄位和使用者Table欄位組成，具體欄位定義如下表。

Hologres中，Binlog功能預設關閉，您可以通過設定表屬性binlog.level和binlog.ttl開啟該功能。如下樣本開啟Binlog，更多關於建立表的參數說明，請參見CREATE TABLE。

• V2.1版本起支援的文法：

  binlog.level和binlog.ttl表屬性名稱更新為binlog_level和binlog_ttl。

  CREATE TABLE test_message_src (
      id int PRIMARY KEY,
      title text NOT NULL,
      body text
  )
  WITH (
      orientation = 'row',
      clustering_key = 'id',
      binlog_level = 'replica',
      binlog_ttl = '86400' -- Binlog的TTL，單位為秒
  );

• 所有版本支援的文法：

  begin;
  create table test_message_src(
    id int primary key, 
    title text not null, 
    body text);
  call set_table_property('test_message_src', 'orientation', 'row');--建立行存表test_message_src
  call set_table_property('test_message_src', 'clustering_key', 'id');--在id列建立聚簇索引
  call set_table_property('test_message_src', 'binlog.level', 'replica');--設定表屬性開啟Binlog功能
  call set_table_property('test_message_src', 'binlog.ttl', '86400');--binlog.ttl，Binlog的TTL，單位為秒
  commit;

參數說明如下。

從Hologres V1.1版本開始，可以根據業務需要選擇開啟/關閉Binlog能力，同時支援配置TTL滿足不同業務情境對Binlog保留時間的訴求，已有表無需重建立表就能開啟Binlog，操作方便快捷。

Hologres表的Binlog資料採用強Schema格式。要查詢特定表的Binlog，可通過將Binlog內建額外欄位與表原有欄位進行組合來實現。此外，Hologres還提供了一些函數，以便查詢最新或最早的Binlog，或者通過已知的LSN和TIMESTAMP來查詢相應的Binlog資訊。

通過內建特殊欄位直接查詢Binlog

使用Binlog內建額外欄位與表原有欄位組合的方式查詢Binlog，樣本如下。

SELECT hg_binlog_lsn,hg_binlog_event_type,hg_binlog_timestamp_us,* FROM test_message_src;

查詢結果樣本如下。

查詢表指定Shard上最早或最新的Binlog

使用hg_get_binlog_cursor函數的方式查詢Binlog，文法如下。

-- OLDEST，此shard上最早的Binlog
SELECT * FROM hg_get_binlog_cursor('<table_name>','OLDEST',<shard_id>);

-- LATEST，此shard上最新的Binlog
SELECT * FROM hg_get_binlog_cursor('<table_name>','LATEST',<shard_id>);

樣本如下。

SELECT * FROM hg_get_binlog_cursor('test_message_src','OLDEST',0);

查詢結果樣本如下。

通過Binlog LSN查詢相應Binlog的時間戳記

使用hg_get_binlog_cursor_by_lsn函數查詢相應Binlog的時間戳記，可返回大於等於所查詢LSN（記錄序號）的第一條Binlog的資訊，如果當前LSN不存在，返回結果中的hg_binlog_timestamp_us欄位是目前時間。文法如下。

SELECT * FROM hg_get_binlog_cursor_by_lsn('<table_name>',<lsn>,<shard_id>);--LSN值（bigint類型）

樣本如下。

SELECT * FROM hg_get_binlog_cursor_by_lsn('test_message_src',152,0);

查詢結果樣本如下。

通過Binlog TIMESTAMP查詢相應Binlog的LSN

使用hg_get_binlog_cursor_by_timestamp函數查詢相應Binlog的LSN，可返回大於等於所查詢時間的第一條Binlog的資訊，如果已經是最新的，返回結果中的hg_binlog_timestamp_us欄位是目前時間，hg_binlog_lsn欄位是下一條資料插入時將會分配的LSN。文法如下。

SELECT * FROM hg_get_binlog_cursor_by_timestamp('<table_name>',<timestamp>,<shard_id>);

樣本如下。

SELECT *,to_timestamp(hg_binlog_timestamp_us/1000000.0) FROM hg_get_binlog_cursor_by_timestamp('test_message_src','2024-05-20 19:34:53.791+08',0);

查詢結果樣本如下。

當前支援通過Flink、Blink以及JDBC（包括Holo Client）消費Hologres Binlog，詳情請參見文檔：

• Flink和Blink即時消費Binlog，請參見Flink/Blink即時消費Hologres Binlog。

• 有關JDBC如何即時消費Binlog，請參見通過JDBC消費Hologres Binlog。

您可以使用如下SQL查看哪些表開啟了Binlog。

SELECT
    *
FROM
    hologres.hg_table_properties
WHERE
    property_key = 'binlog.level'
    AND property_value = 'replica';

返回結果樣本如下。