begriffs open source - pg_scribe/blob - wal2sql/README

   1 wal2sql, Output plugin for logical replication
   2 ==============================================
   3
   4 **Origin**: This project is a fork of decoder_raw from Michael Paquier's
   5 pg_plugins repository (https://github.com/michaelpq/pg_plugins/tree/main/decoder_raw).
   6
   7 **Author**: Original decoder_raw code by Michael Paquier
   8 **License**: PostgreSQL License (same as original)
   9
  10 **Purpose**: Extended version of decoder_raw with additional callbacks for:
  11 - `message_cb` - Handling DDL messages from pg_logical_emit_message()
  12 - `truncate_cb` - Handling TRUNCATE operations
  13
  14 This output plugin for logical replication generates raw SQL queries based
  15 on the logical changes it finds. Those queries can be consumed as they
  16 are by any remote source.
  17
  18 UPDATE and DELETE queries are generated for relations using a level of
  19 REPLICA IDENTITY sufficient to ensure that tuple selectivity is guaranteed:
  20 - FULL, all the old tuple values are decoded from WAL all the time so
  21 they are used for WHERE clause generation.
  22 - DEFAULT, when relation has an index usable for selectivity like a
  23 primary key.
  24 - USING INDEX, because the UNIQUE index on NOT NULL values ensures
  25 that tuples are uniquely identified.
  26 In those cases, for DEFAULT and USING INDEX, WHERE clause is generated
  27 with new tuple values if no columns mused by the selectivity index are
  28 updated as server does not need to provide old tuple values. If at least
  29 one column is updated, new tuple values are added, of course only on the
  30 columns managing tuple selectivity.
  31 Based on that, UPDATE and DELETE queries are not generated for the following
  32 cases of REPLICA IDENTITY:
  33 - NOTHING
  34 - DEFAULT without a selectivity index
  35
  36 INSERT queries are generated for all relations everytime using the new
  37 tuple values fetched from WAL.
  38
  39 Options
  40 -------
  41
  42 The following options can be used:
  43 - include_transaction, 'on' will print BEGIN and COMMIT messages, while
  44 'off' bypasses them and generates nothing.
  45 - output_format, 'textual' for textual format, or 'binary' for binary
  46 format. Default is 'textual'.
  47
  48 This worker is compatible with PostgreSQL 9.4 and newer versions.
  49
  50 TODO
  51 ----
  52
  53 - Implement options filtering INSERT generation depending on REPLICA
  54 IDENTITY level of relation involved.