Hologres:Subscribe to Hologres binlogs

Observe as seguintes limitações ao assinar binlogs do Hologres:

• Somente o Hologres V0.9 ou superior suporta assinatura de binlog. Caso sua instância esteja em uma versão anterior, participe do grupo de suporte online no DingTalk. Para mais detalhes, consulte Como obter mais suporte online?.

• Nas versões V0.9 e V0.10 do Hologres, não é possível ativar binlogs para tabelas existentes alterando suas propriedades; recrie a tabela. A partir da V1.1, ative binlogs sob demanda.

• Antes das versões V1.3.14 e V1.1.82 do Hologres, apenas um Superuser podia consumir o binlog. O uso de uma conta com menos privilégios resultava no erro permission denied for table hg_replication_slot_properties. A partir das versões V1.3.14 e V1.1.82, a conta precisa apenas da permissão SELECT na tabela para consumir o binlog com o Flink. Para consumir o binlog via JDBC, a conta deve pertencer à Replication Role.

• O Hologres suporta binlogs no nível de tabela tanto para tabelas orientadas a linhas quanto para tabelas orientadas a colunas. A tabela a seguir lista os métodos de consumo suportados.

  Categoria do Flink	Tabela orientada a linhas	Tabela orientada a colunas	Tabela híbrida linha-coluna (Suportado a partir da V1.1)
  Blink	Suportado	Suportado	Suportado
  Realtime Compute for Apache Flink	Suportado	Suportado	Suportado
  Apache Flink	Não suportado	Não suportado	Não suportado
  JDBC	Suportado na V1.1 e posteriores	Suportado na V1.1 e posteriores	Suportado na V1.1 e posteriores

• O Blink não suporta o tipo de dado TIMESTAMP ao consumir binlogs do Hologres. Utilize o tipo TIMESTAMPTZ ao criar tabelas no Hologres. Outros tipos especiais, como SMALLINT, também não são suportados.

• Não é possível consumir binlogs da tabela pai de uma tabela particionada. Utilize uma tabela filha ou uma tabela regular (não particionada). A partir do Hologres V1.3.24, modifique o TTL do binlog de uma tabela filha sob demanda. Se nenhum TTL de binlog for especificado explicitamente para a tabela filha, ela herdará o TTL da tabela pai. Note que o TTL do binlog não é um temporizador preciso; o sistema não garante a exclusão imediata do binlog após a expiração e realiza a limpeza em algum momento posterior.

• Para cargas de trabalho com muitas escritas, ativar binlogs em uma tabela orientada a colunas gera, teoricamente, mais sobrecarga do que em uma tabela orientada a linhas. Portanto, prefira tabelas orientadas a linhas ao ativar binlogs. Se a tabela também for utilizada para consultas OLAP, opte pelo formato de armazenamento híbrido linha-coluna. Para mais informações, consulte Formatos de armazenamento de tabela.

• Apenas tabelas internas do Hologres suportam binlogs. Tabelas externas não possuem esse suporte.

Um registro de binlog contém campos de sistema e colunas da tabela do usuário. A tabela a seguir descreve esses campos.

Por padrão, o recurso de binlog vem desativado no Hologres. Para ativá-lo, defina as propriedades de tabela binlog.level e binlog.ttl. Os exemplos a seguir demonstram como ativar binlogs. Para mais informações sobre os parâmetros de criação de tabela, consulte CREATE TABLE.

• Sintaxe para V2.1 e posteriores:

  Os nomes das propriedades de tabela binlog.level e binlog.ttl foram atualizados para binlog_level e 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' -- The TTL of the binlog, in seconds.
  );

• Sintaxe suportada em todas as versões:

  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');--Create a row-oriented table named test_message_src.
  call set_table_property('test_message_src', 'clustering_key', 'id');--Create a clustered index on the id column.
  call set_table_property('test_message_src', 'binlog.level', 'replica');--Set a table property to enable the binlog feature.
  call set_table_property('test_message_src', 'binlog.ttl', '86400');--The TTL of the binlog, in seconds.
  commit;

A tabela a seguir descreve os parâmetros.

A partir do Hologres V1.1, é possível ativar ou desativar binlogs e configurar o TTL para atender a diferentes requisitos de retenção. Ative binlogs em tabelas existentes sem a necessidade de recriá-las.

Os dados de binlog do Hologres são fortemente tipados. Para consultar os binlogs de uma tabela específica, combine os campos de sistema internos do binlog com as colunas originais da tabela. O Hologres também fornece funções para consultar o binlog mais antigo ou o mais recente, ou ainda buscar informações do binlog por meio de um LSN ou timestamp conhecido.

Consulta por campos internos

Utilize a instrução a seguir para consultar o binlog combinando os campos internos do binlog com os campos originais da tabela.

SELECT hg_binlog_lsn,hg_binlog_event_type,hg_binlog_timestamp_us,* FROM test_message_src;

O código a seguir apresenta um exemplo de resultado.

postgres=# select hg_binlog_lsn, hg_binlog_event_type, hg_binlog_timestamp_us, * from test_message_src ;
 hg_binlog_lsn | hg_binlog_event_type | hg_binlog_timestamp_us | id |  title  |       body
---------------+----------------------+------------------------+----+---------+-------------------
          1081 |                    5 |       1626856018921653 |  1 | title 1 | body 1
          1092 |                    3 |       1626856054284918 |  1 | title 1 | body 1
          1093 |                    7 |       1626856054284918 |  1 | title 1 | body after update
          1095 |                    2 |       1626856059747536 |  1 | title 1 | body after update
(4 rows)

Consulta do binlog mais antigo ou mais recente

Utilize a função hg_get_binlog_cursor para consultar o binlog mais antigo ou mais recente em um shard específico. O código a seguir apresenta a sintaxe.

-- OLDEST: Query the earliest binlog on this shard.
SELECT * FROM hg_get_binlog_cursor('<table_name>','OLDEST',<shard_id>);
-- LATEST: Query the latest binlog on this shard.
SELECT * FROM hg_get_binlog_cursor('<table_name>','LATEST',<shard_id>);

O código a seguir mostra um exemplo de uso.

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

O código a seguir apresenta um exemplo de resultado.

test=# select * from hg_get_binlog_cursor('test_message_src','OLDEST',0);
 hg_shard_id | hg_binlog_lsn | hg_binlog_timestamp_us
-------------+---------------+------------------------
           0 |           152 |       1716204893791755
(1 row)

Consulta de timestamp por LSN

Utilize a função hg_get_binlog_cursor_by_lsn para consultar o timestamp de um binlog. Essa função retorna informações sobre o primeiro registro de binlog cujo LSN seja maior ou igual ao LSN especificado. Se o LSN especificado não existir, o campo hg_binlog_timestamp_us no resultado retornará a hora atual. O código a seguir apresenta a sintaxe.

SELECT * FROM hg_get_binlog_cursor_by_lsn('<table_name>',<lsn>,<shard_id>);--The LSN value must be of the BIGINT type.

O código a seguir mostra um exemplo de uso.

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

O código a seguir apresenta um exemplo de resultado.

test=# select * from hg_get_binlog_cursor_by_lsn('test_message_src',152,0);
 hg_shard_id | hg_binlog_lsn | hg_binlog_timestamp_us
-------------+---------------+------------------------
           0 |           152 |      1716204893791755
(1 row)

Consulta de LSN por timestamp

Utilize a função hg_get_binlog_cursor_by_timestamp para consultar o LSN de um binlog. Essa função retorna informações sobre o primeiro registro de binlog com timestamp maior ou igual ao horário especificado. Se o horário especificado for posterior à entrada de binlog mais recente, o campo hg_binlog_timestamp_us no resultado retornará a hora atual, e o campo hg_binlog_lsn retornará o LSN que será atribuído à próxima linha inserida. O código a seguir apresenta a sintaxe.

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

O código a seguir mostra um exemplo de uso.

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);

O código a seguir apresenta um exemplo de resultado.

test=# 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);
 hg_shard_id | hg_binlog_lsn | hg_binlog_timestamp_us |          to_timestamp
-------------+---------------+------------------------+-------------------------------
           0 |           152 |    1716204893791755 | 2024-05-20 19:34:53.791755+08
(1 row)

Consuma binlogs do Hologres com Flink, Blink e JDBC (incluindo Holo Client). Para mais informações, consulte os tópicos a seguir:

• Para consumir binlogs em tempo real com Flink ou Blink, consulte Consumir binlogs do Hologres em tempo real usando Flink ou Blink.

• Para consumir binlogs com JDBC, consulte Consumir binlogs do Hologres usando JDBC.

Utilize a instrução SQL a seguir para verificar quais tabelas têm binlogs ativados.

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

Abaixo está um exemplo de resultado. A consulta retorna quatro colunas: table_namespace, table_name, property_key e property_value. Essas colunas fornecem informações sobre todas as tabelas que possuem binlogs ativados.

-- Enable at the session level.
SET hg_experimental_generate_binlog=off;