From c4c2a372968bdac6bb03a92d2b353f7b6b7b9caa Mon Sep 17 00:00:00 2001 From: "kuroda.hayato%40jp.fujitsu.com" Date: Wed, 18 May 2022 04:56:18 +0000 Subject: [PATCH 2/2] add doc --- doc/src/sgml/catalogs.sgml | 296 ++++++++++++++++++++++++++++++ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/func.sgml | 79 ++++++++ doc/src/sgml/lrg.sgml | 364 +++++++++++++++++++++++++++++++++++++ doc/src/sgml/postgres.sgml | 1 + 5 files changed, 741 insertions(+) create mode 100644 doc/src/sgml/lrg.sgml diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index a533a2153e..29abc04fab 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -200,6 +200,22 @@ metadata for large objects + + pg_lrg_info + logical replication group + + + + pg_lrg_nodes + logical replication group + + + + pg_lrg_pub + logical replication group + + + pg_namespace schemas @@ -4960,6 +4976,286 @@ SCRAM-SHA-256$<iteration count>:&l + + <structname>pg_lrg_info</structname> + + + pg_lrg_info + + + test + + + + <structname>pg_lrg_info</structname> Columns + + + + + Column Type + + + Description + + + + + + + + oid oid + + + Row identifier + + + + + + groupname name + + + Name of the group + + + + + + puballtables bool + + + The type of publication + + + + +
+ + + + <structname>pg_lrg_nodes</structname> + + + pg_lrg_nodes + + + test + + + + <structname>pg_lrg_nodes</structname> Columns + + + + + Column Type + + + Description + + + + + + + + oid oid + + + Row identifier + + + + + + nodeid name + + + Identifier of this node + + + + + + groupid oid + (references pg_lrg_info.oid) + + + attached group + + + + + + dbid oid + (references pg_database.oid) + + + database + + + + + + status int + + + status + + + + + + nodename name + + + Name of this node + + + + + + localconn name + + + connection string for this node + + + + + + upstreamconn name + + + connection string for upstream node + + + + + +
+ + + + <structname>pg_lrg_pub</structname> + + + pg_lrg_pub + + + test + + + + <structname>pg_lrg_pub</structname> Columns + + + + + Column Type + + + Description + + + + + + + + oid oid + + + Row identifier + + + + + + groupid oid + (references pg_lrg_info.oid) + + + attached group + + + + + + pubid oid + (references pg_publication.oid) + + + publication + + + + + + +
+ + + + + <structname>pg_lrg_sub</structname> + + + pg_lrg_sub + + + test + + + + <structname>pg_lrg_sub</structname> Columns + + + + + Column Type + + + Description + + + + + + + + oid oid + + + Row identifier + + + + + + groupid oid + (references pg_lrg_info.oid) + + + attached group + + + + + + subid oid + (references pg_subscription.oid) + + + subscription + + + + + + +
+ <structname>pg_namespace</structname> diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 40ef5f7ffc..8be17a652e 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -49,6 +49,7 @@ + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 85ecc639fd..85edb739f0 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -29233,6 +29233,85 @@ postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn); + + Logical Replication Group Management Functions + + + The functions shown + in are for + controlling and interacting with logical replication groups. + + + + LRG Management Functions + + + + + Function + + + Description + + + + + + + + + + + lrg_create ( group_name name, publication_type text, local_connstring text, node_name name) + + + + creates a group. + + + + + + + + lrg_node_attach ( group_name name, local_connstring text, upstream_connstring text, node_name name) + + + + attach to a group. + + + + + + + + lrg_node_detach ( group_name name, node_name name) + + + + detach from a group. This function must be executed from a member of the group. + + + + + + + + lrg_drop ( group_name name) + + + + Detach from a given group and remove it. This function must be executed from a member of the group. + + + + + +
+ + + Database Object Management Functions diff --git a/doc/src/sgml/lrg.sgml b/doc/src/sgml/lrg.sgml new file mode 100644 index 0000000000..f27c3def18 --- /dev/null +++ b/doc/src/sgml/lrg.sgml @@ -0,0 +1,364 @@ + + + Logical Replication Group (LRG) + + + logical replication group + + + + Logical Replication Group(LRG) provides an easy way for constructing + N-directional logical replicaiton systems. Advantages of LRG are + + + + + Allowing load balancing + + + + + Allowing rolling updates of nodes + + + + + Improving the availability of the system + + + + + Improving performance + + + + + + + + Concepts + + In this section terminology for LRG is defined. + + + Node Group + + Node group is a group that participant nodes have same tables and send/receive their data changes. + Note that each node in a group must be connected to all other nodes in that group. + LRG accomplishes such a group by creating publications and subscriptions on nodes. + + + + + Upstream node + + Upstream node is a node that belongs to a group, and it must be specified when a node attaches to the group. + It is not special and arbitrary participants can be used as that. + The attaching node will copy data from the upstream. + + + + + lrg launcher + + Lrg launcher is a background worker that is registered at postmaster startup. + This will be registered when max_logical_replication_workers is not equal to zero. + This process sometimes seeks pg_database, and it launches lrg worker associated with the database. + + + + + lrg worker + + Lrg worker is a background worker that is registered by the lrg launcher. + This process is associated with a specific database, and performs all operations related to the LRG feature. + If this database is not a member of any node groups, this process will exit immediately. + + + + + + + LRG SQL interface + + See for detailed documentation on + SQL-level APIs for interacting with logical replication group. + + + + + System Catalogs related to LRG + + Following catalogs are used for LRG. + + + + + pg_lrg_info, + + + + + pg_lrg_nodes, + + + + + pg_lrg_pub, + + + + + pg_lrg_sub + + + + + + + + + Restrictions + + LRG currently has the following restrictions or missing functionality. + + + + Each node can attach only one node set at a time. + + + + + All tables must be shard in the database. + + + + + LRG does not provide any mechanism for conflict handling (e.g. PK violations). + Avoiding conflicts is the user responsibility. + + + + + + + + Configuration + + LRG will create a publication and subscriptions on each node, + that number of subscribers is the number of participants minus one. Therefore LRG requires + several configuration options. + + + + + + wal_level must be logical. + + + + + max_replication_slots must be set to at least the number of participants. + + + + + max_wal_senders must be set to at least same as max_replication_slots. + + + + + max_logical_replication_workers must be larger than the number of participants. + + + + + max_worker_processes must be larger that max_logical_replication_workers. + + + + + + + Example + + The following example demonstrates constructing N-directional logical replication group. + Assuming that there are three nodes, called Node1, Node2, Node3, and they can connect each other. + In the example they are in the same machine. + + + + Create a group + + + At first, a node group must be created. Here it will be created on Node1. + + +postgres=# -- Create a node group 'testgroup', and attach to it as 'testnode1' +postgres=# SELECT lrg_create('testgroup', 'FOR ALL TABLES', 'port=5431 dbname=postgres', 'testnode1'); + lrg_create +------------ + +(1 row) + + + + Information of the group and nodes can check via system catalogs, + like pg_lrg_nodes. + + +postgres=# SELECT * FROM pg_lrg_info ; + oid | groupname | puballtables +-------+-----------+-------------- + 16384 | testgroup | t +(1 row) + +postgres=# SELECT * FROM pg_lrg_nodes; + oid | nodeid | groupid | dbid | status | nodename | localconn | upstreamconn +-------+----------------------+---------+------+--------+-----------+---------------------------+-------------- + 16385 | 70988980716274892555 | 16384 | 5 | 3 | testnode1 | port=5431 dbname=postgres | +(1 row) + + + + + + Attach to a group + + + Next Node2 can attach the created group testgroup. Note that the connection string for Node1 must be specified. + + + +postgres=# -- Attach to 'testgroup' as 'testnode2' +postgres=# SELECT lrg_node_attach('testgroup', 'port=5432 dbname=postgres', 'port=5431 dbname=postgres', 'testnode2'); + lrg_node_attach +----------------- + +(1 row) + + + + The status of all nodes can check via pg_lrg_nodes. Following tuples will be found on both nodes. + + + +postgres=# SELECT * FROM pg_lrg_info ; + oid | groupname | puballtables +-------+-----------+-------------- + 16384 | testgroup | t +(1 row) + +postgres=# SELECT * FROM pg_lrg_nodes; + oid | nodeid | groupid | dbid | status | nodename | localconn | upstreamconn +-------+----------------------+---------+------+--------+-----------+---------------------------+--------------------------- + 16385 | 70989229890284027935 | 16384 | 5 | 3 | testnode2 | port=5432 dbname=postgres | port=5431 dbname=postgres + 16386 | 70988980716274892555 | 16385 | 5 | 3 | testnode1 | port=5431 dbname=postgres | +(2 rows) + + + + Now Node1 and Node2 has same contents about LRG system catalogs, + so ether of them can be specified as an upstream node. + In below example Node2 is used as upstream for attaching a new node. + + + +postgres=# -- Attach to 'testgroup' as 'testode3', and data will be copied from Node2 +postgres=# SELECT lrg_node_attach('testgroup', 'port=5433 dbname=postgres', 'port=5432 dbname=postgres', 'testnode3'); + lrg_node_attach +----------------- + +(1 row) + + + + Finally pg_lrg_info and pg_lrg_nodes will be like: + + + +postgres=# SELECT * FROM pg_lrg_info ; + oid | groupname | puballtables +-------+-----------+-------------- + 16384 | testgroup | t +(1 row) + +postgres=# SELECT * FROM pg_lrg_nodes; + oid | nodeid | groupid | dbid | status | nodename | localconn | upstreamconn +-------+----------------------+---------+------+--------+-----------+---------------------------+--------------------------- + 16385 | 70989243367269230745 | 16384 | 5 | 3 | testnode3 | port=5433 dbname=postgres | port=5432 dbname=postgres + 16386 | 70989229890284027935 | 16385 | 5 | 3 | testnode2 | port=5432 dbname=postgres | port=5431 dbname=postgres + 16387 | 70988980716274892555 | 16385 | 5 | 3 | testnode1 | port=5431 dbname=postgres | +(3 rows) + + + + Now all nodes publish their changes, and they subscribe them. If a tuple inserted on Node1, + the data will be also found on Node2 and Node3. + + + + + + Detach from a group + + User can detach attached nodes at any time. n API for detaching lrg_node_detach is used for that. + This function must be called from a node that is a member of a group. + + + +postgres=# -- Detach Node3 from 'testgroup'. This can be done from the arbitrary member of the group +postgres=# select lrg_node_detach('testgroup', 'testnode3'); + lrg_node_detach +----------------- + +(1 row) + +postgres=# -- Also detach Node2 from 'testgroup'. This can be done from Node1 or Node2 +postgres=# select lrg_node_detach('testgroup', 'testnode2'); + lrg_node_detach +----------------- + +(1 row) + + + + The user-defined data will be not removed even if nodes are detached, but tuples in LRG related catalogs will be deleted. + + + +postgres=# -- On Node2, there are no tuples in pg_lrg_nodes +postgres=# select * from pg_lrg_nodes; + oid | nodeid | groupid | dbid | status | nodename | localconn | upstreamconn +-----+--------+---------+------+--------+----------+-----------+-------------- +(0 rows) + + + + + Drop a group + + For dropping a group, the API lrg_drop can be used. + The function must be callled from a node that is a member of a group, and + it will throw ERROR if there are other members in the group. + + + +postgres=# -- Drop 'testgroup.' Node1 will detach from it automatically. +postgres=# select lrg_drop('testgroup'); + lrg_drop +---------- + +(1 row) + +postgres=# -- There are no tuples in pg_lrg_info +postgres=# select * from pg_lrg_info; + oid | groupname | puballtables +-----+-----------+-------------- +(0 rows) + + + + + + \ No newline at end of file diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 0b60e46d69..bcea47fdc9 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -172,6 +172,7 @@ break is not needed in a wider output rendering. &logical-replication; &jit; ®ress; + &lrg; -- 2.27.0