Merge branch 'master' into logical. Also testgres.pubsub was added to…

… the Sphinx templates and module header was added as well.
postgrespro · funbringer · Jun 1, 2018 · Mar 16, 2018 · Mar 16, 2018 · Mar 16, 2018
commit f652bf40850d5aa20a8c9f207a41fec8a570d639
diff --git a/docs/source/testgres.rst b/docs/source/testgres.rst
@@ -59,4 +59,19 @@ testgres.node
    .. automethod:: __init__
 
 .. autoclass:: testgres.node.ProcessProxy
-   :members:
+   :members:
+
+testgres.pubsub
+---------------
+
+.. automodule:: testgres.pubsub
+
+.. autoclass:: testgres.node.Publication
+   :members:
+
+   .. automethod:: __init__
+
+.. autoclass:: testgres.node.Subscription
+   :members:
+
+   .. automethod:: __init__
diff --git a/testgres/api.py b/testgres/api.py
@@ -28,7 +28,7 @@
 ...             replica.catchup()  # wait until changes are visible
 ...             print(replica.execute('postgres', 'select count(*) from test'))
 PostgresNode(name='...', port=..., base_dir='...')
-[(3,)]
+[(3L,)]
 """
 from .node import PostgresNode
 

diff --git a/testgres/node.py b/testgres/node.py
@@ -300,12 +300,11 @@ def _create_recovery_conf(self, username, slot=None):
         master = self.master
         assert master is not None
 
-        # yapf: disable
         conninfo = {
             "application_name": self.name,
             "port": master.port,
             "user": username
-        }
+        }  # yapf: disable
 
         # host is tricky
         try:
@@ -318,7 +317,7 @@ def _create_recovery_conf(self, username, slot=None):
         line = (
             "primary_conninfo='{}'\n"
             "standby_mode=on\n"
-        ).format(options_string(**conninfo))
+        ).format(options_string(**conninfo))  # yapf: disable
 
         if slot:
             # Connect to master for some additional actions

diff --git a/testgres/pubsub.py b/testgres/pubsub.py
@@ -1,4 +1,46 @@
 # coding: utf-8
+"""
+Unlike physical replication the logical replication allows users replicate only
+specified databases and tables. It uses publish-subscribe model with possibly
+multiple publishers and multiple subscribers. When initializing publisher's
+node ``allow_logical=True`` should be passed to the :meth:`.PostgresNode.init()`
+method to enable PostgreSQL to write extra information to the WAL needed by
+logical replication.
+
+To replicate table ``X`` from node A to node B the same table structure should
+be defined on the subscriber's node as logical replication don't replicate DDL.
+After that :meth:`~.PostgresNode.publish()` and :meth:`~.PostgresNode.subscribe()`
+methods may be used to setup replication. Example:
+
+>>> from .api import get_new_node
+>>> with get_new_node() as nodeA, get_new_node() as nodeB:
+...     nodeA.init(allow_logical=True).start()
+...     nodeB.init().start()
+...
+...     # create same table both on publisher and subscriber
+...     create_table = 'create table test (a int, b int)'
+...     nodeA.safe_psql(create_table)
+...     nodeB.safe_psql(create_table)
+...
+...     # create publication
+...     pub = nodeA.publish('mypub')
+...     # create subscription
+...     sub = nodeB.subscribe(pub, 'mysub')
+...
+...     # insert some data to the publisher's node
+...     nodeA.execute('insert into test values (1, 1), (2, 2)')
+...
+...     # wait until changes apply on subscriber and check them
+...     sub.catchup()
+...
+...     # read the data from subscriber's node
+...     nodeB.execute('select * from test')
+PostgresNode(name='...', port=..., base_dir='...')
+PostgresNode(name='...', port=..., base_dir='...')
+''
+''
+[(1, 1), (2, 2)]
+"""
 
 from six import raise_from
 
@@ -10,7 +52,8 @@
 class Publication(object):
     def __init__(self, name, node, tables=None, dbname=None, username=None):
         """
-        Constructor
+        Constructor. Use :meth:`.PostgresNode.publish()` instead of direct
+        constructing publication objects.
 
         Args:
             name: publication name
@@ -40,10 +83,11 @@ def drop(self, dbname=None, username=None):
 
     def add_tables(self, tables, dbname=None, username=None):
         """
-        Add tables
+        Add tables to the publication. Cannot be used if publication was
+        created with empty tables list.
 
         Args:
-            tables: a list of tables to add to the publication
+            tables: a list of tables to be added to the publication
         """
         if not tables:
             raise ValueError("Tables list is empty")
@@ -64,15 +108,17 @@ def __init__(self,
                  username=None,
                  **kwargs):
         """
-        Constructor
+        Constructor. Use :meth:`.PostgresNode.subscribe()` instead of direct
+        constructing subscription objects.
 
         Args:
             name: subscription name
             node: subscriber's node
-            publication: Publication object we are subscribing to
+            publication: :class:`.Publication` object we are subscribing to
+                (see :meth:`.PostgresNode.publish()`)
             dbname: database name used to connect and perform subscription
             username: username used to connect to the database
-            **kwargs: subscription parameters (see CREATE SUBSCRIPTION
+            **kwargs: subscription parameters (see ``CREATE SUBSCRIPTION``
                 in PostgreSQL documentation for more information)
         """
         self.name = name