wal2json
Логическая репликация в формате json.
Для реализации возможности логической репликации в формате JSON в состав продукта дополнительно включен плагин вывода для логического декодирования
wal2json.Параметры плагина, задаваемые при подключении к слоту репликации:
include-xids- добавитьxidк каждому набору изменений. Значение по умолчанию -false;use-xid32- использовать 32-битныйxidв наборе изменений. Значение по умолчанию -false;include-timestamp- добавить временную метку (timestamp) к каждому набору изменений. Значение по умолчанию -false;include-schemas- добавить схему (schema) к каждому изменению. Значение по умолчанию -true;include-types- добавить тип к каждому изменению. Значение по умолчанию -true;include-typmod- добавить модификатор к типам, у которых он есть (например,varchar(20)вместоvarchar). Значение по умолчанию -true;include-type-oids- добавитьoidsтипа. Значение по умолчанию -false;include-domain-data-type- заменить доменное имя базовым типом данных. Значение по умолчанию -false;include-column-positions- добавить позицию столбца (pg_attribute.attnum). Значение по умолчанию -false;include-origin- добавить источник фрагмента данных. Значение по умолчанию -false;include-not-null- добавить ненулевую информацию в качествеcolumnoptionals. Значение по умолчанию -false;include-default- добавить выражение (expression) по умолчанию. Значение по умолчанию -false;include-pk- добавить информацию о primarykeyв видеpk. Имя столбца и тип данных включены. Значение по умолчанию -false;numeric-data-types-as-string- использовать строку для числовых типов данных. Спецификация JSON не распознаетInfinityиNaNкак допустимые числовые значения. Для чисел двойной точности могут возникнуть потенциальные проблемы совместимости. Значение по умолчанию -false;pretty-print- добавить пробелы и отступы в структуры JSON. Значение по умолчанию -false;write-in-chunks- запись после каждого изменения вместо каждого набора изменений. Используется только тогда, когдаformat-versionв значении1. Значение по умолчанию -false;include-lsn- добавитьnextlsnк каждому набору изменений (changeset). Значение по умолчанию -false;include-transaction- выдает записи, обозначающие начало и конец каждой транзакции. Значение по умолчанию -true;filter-origins- исключить изменения из указанных источников. Значение по умолчанию пустое, что означает, что источник не будет отфильтрован. Набор значений, разделенных запятой;filter-tables- исключить строки (rows) из указанных таблиц. Значение по умолчанию пустое, что означает, что ни одна таблица не будет отфильтрована. Набор значений, разделенных запятой. Таблицы должны соответствовать требованиям схемы. Имя вида*.fooозначает таблицуfooво всех схемах, а имя видаbar.*означает все таблицы в схеме bar. Специальные символы (пробел, одинарная кавычка, запятая, точка, звездочка) должны быть экранированы обратной косой чертой. Схема и таблица чувствительны к регистру;add-tables: включить только строки (rows) из указанных таблиц. По умолчанию используются все таблицы из всех схем. В нем действуют те же правила, что и вfilter-tables;filter-msg-prefixes- исключить сообщения, если префикс есть в списке. Значение по умолчанию пустое, что означает, что ни одно сообщение не будет отфильтровано. Задается в виде набора значений, разделенных запятой;add-msg-prefixes- включить только сообщения, если префикс есть в списке. По умолчанию используются все префиксы. Задается в виде набора значений, разделенных запятой. Значениеfilter-msg-prefixesприменяется перед этим параметром;format-version- определяет, какой формат вывода использовать. Значение по умолчанию равно1;actions- определяет, какие операции будут отправляться. По умолчанию используются все действия (INSERT,UPDATE,DELETEиTRUNCATE). Однако, если используетсяformat-version 1,TRUNCATEне будет включен (для поддержания обратной совместимости).
Плагин имеет доступ к кортежам, созданным с помощью
INSERT и UPDATE. Для настройки доступа к UPDATE/DELETE старых версий строк (row) при создании/изменении таблицы задается свойство REPLICA IDENTITY. Изменения могут быть применены с помощью протокола потока изменений (слоты логической репликации) или с помощью специального SQL API.Поддерживается два формата вывода:
- объект JSON для каждой транзакции: все новые/старые кортежи доступны в объекте JSON. Есть опции для включения таких свойств, как временная метка транзакции, соответствие схеме, типы данных и идентификаторы транзакций;
- объект JSON для каждого кортежа: для начала и окончания транзакции объект JSON необязателен; дополнительно представлен набор опций для включения отдельных свойств объектов.
Ниже приведен пример JSON-схемы, генерируемой для операции вставки:
{ "kind": "insert", "schema": "public", "table": "test_table", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [1, "A first record in a table"] }
Для использования плагина требуется уровень
WAL >= logical, для этого необходимо задать значение параметра wal_level = 'logical'. После смены значения этого параметра требуется перезапустить сервер Pangolin.Для создания слота логической репликации с использованием
wal2json необходимо вызвать функцию pg_create_logical_replication_slot:postgres$ psql -p 6544 \ -c "select pg_create_logical_replication_slot('test_slot1', 'wal2json')"
Для подключения к созданному слоту в отдельном терминале вызывается
pg_recvlogical:pg_recvlogical -d postgres --slot test_slot --start -o pretty-print=1 -o add-msg-prefixes=wal2json -f -
В соответствующем терминале будет отображаться мониторинг содержимого слота в формате JSON.
Ниже приведен пример создания тестовых таблиц и их заполнения данными:
CREATE table test01 (num INTEGER PRIMARY KEY, txt TEXT); CREATE table test02 (num INTEGER, txt TEXT); INSERT INTO test01 VALUES(1, 'A first record in a table'); INSERT INTO test01 VALUES(2, 'A second record in a table'),(3, 'Third row'); INSERT INTO test02 SELECT * FROM test01;
Пример вывода результата в терминале мониторинга:
**CREATE TABLE { "change": [ ] } **CREATE TABLE { "change": [ ] } **INSERT 0 1 { "change": [ { "kind": "insert", "schema": "public", "table": "test01", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [1, "A first record in a table"] } ] } **INSERT 0 2 { "change": [ { "kind": "insert", "schema": "public", "table": "test01", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [2, "A second record in a table"] } ,{ "kind": "insert", "schema": "public", "table": "test01", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [3, "Third row"] } ] } **INSERT 0 3 { "change": [ { "kind": "insert", "schema": "public", "table": "test02", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [1, "A first record in a table"] } ,{ "kind": "insert", "schema": "public", "table": "test02", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [2, "A second record in a table"] } ,{ "kind": "insert", "schema": "public", "table": "test02", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [3, "Third row"] } ] }
Содержимое тестовой таблицы test02:
num | txt ----+---------------------------- 1 | A first record in a table 2 | A second record in a table 3 | Third row (3 rows)
В примере далее произведено удаление данных из двух таблиц:
DELETE FROM test01 WHERE num=3; DELETE FROM test02 WHERE num=3;
Удаление строк таблицы
test01 выполнено. Для таблицы test02 было получено предупреждение (WARNING), так как логическая репликация операции невозможна из-за отсутствия ключа.Пример вывода
wal2json:**DELETE 1 { "change": [ { "kind": "delete", "schema": "public", "table": "test01", "oldkeys": { "keynames": ["num"], "keytypes": ["integer"], "keyvalues": [3] } } ] } **DELETE 1 WARNING: table "test02" without primary key or replica identity is nothing { "change": [ ] }
Аналогичным образом далее рассмотрен сценарий модификации строк в двух таблицах:
UPDATE test01 SET txt='modified' WHERE num=2; UPDATE test02 SET txt='modified' WHERE num=2;
Обновление строк таблицы
test01 выполнено. Для таблицы test02 указан WARNING, так как логическая репликация операции невозможна из-за отсутствия ключа.Получен следующий вывод:
**UPDATE 1 { "change": [ { "kind": "update", "schema": "public", "table": "test01", "columnnames": ["num", "txt"], "columntypes": ["integer", "text"], "columnvalues": [2, "modified"], "oldkeys": { "keynames": ["num"], "keytypes": ["integer"], "keyvalues": [2] } } ] } **UPDATE 1 WARNING: table "test02" without primary key or replica identity is nothing { "change": [ ] }
Дополнительную информацию по поставляемому модулю wal2json можно получить по ссылке.