Justin Clift <jc at telstra.net> writes:
> This is the first go at documenting how Slony stores stuff
> internally in each table, the purpose of each table, and so on.

I have taken the liberty of putting this into a set of COMMENT ON
TABLE [foo] IS '' statements, in slony1_base.sql.

I won't commit it without there being some noises concurring with the
idea.

I would commend taking the very same approach with functions, in
slony1_funcs.sql.

We can then run an instance of it, and use Rod Taylor's tool to grab a
nice HTML and/or DocBook document that comprehensively grabs
documentation out of the database.

Index: doc/howto/slonik_commands.html
===================================================================
Index: src/backend/slony1_base.sql
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/src/backend/slony1_base.sql,v
retrieving revision 1.13
diff -c -u -r1.13 slony1_base.sql
--- src/backend/slony1_base.sql	19 May 2004 19:38:28 -0000	1.13
+++ src/backend/slony1_base.sql	29 Jul 2004 15:12:39 -0000
@@ -26,7 +26,7 @@
 	CONSTRAINT "sl_node-pkey"
 		PRIMARY KEY (no_id)
 );
-
+comment on table @NAMESPACE at .sl_node is 'Holds the list of nodes associated with this namespace.  no_id is the unique ID number for the node; no_comment is a human-oriented description of the node';
 
 -- ----------------------------------------------------------------------
 -- TABLE sl_set
@@ -43,6 +43,13 @@
 		FOREIGN KEY (set_origin)
 		REFERENCES @NAMESPACE at .sl_node (no_id)
 );
+comment on table @NAMESPACE at .sl_set is 'Holds definitions of replication sets.  
+
+set_id is a unique ID number for the set.
+set_origin is the ID number of the source node for the replication set.
+set_locked indicates whether or not the set is locked.
+set_comment is a human-oriented description of the set.
+';
 
 
 -- ----------------------------------------------------------------------
@@ -66,6 +73,7 @@
 		FOREIGN KEY (ssy_origin)
 		REFERENCES @NAMESPACE at .sl_node (no_id)
 );
+comment on table @NAMESPACE at .sl_setsync is 'Not documented yet';
 
 
 -- ----------------------------------------------------------------------
@@ -85,6 +93,12 @@
 		FOREIGN KEY (tab_set)
 		REFERENCES @NAMESPACE at .sl_set (set_id)
 );
+comment on table @NAMESPACE at .sl_table is 'Holds information about the tables being replicated.
+
+tab_id - unique key for Slony-I to use to identify the table
+tab_reloid - the OID of the table in pg_catalog.pg_class.oid
+tab_idxname - the name of the primary index of the table
+tab_comment - Human-oriented description of the table';
 
 
 -- ----------------------------------------------------------------------
@@ -101,6 +115,7 @@
 		REFERENCES @NAMESPACE at .sl_table (tab_id)
 		ON DELETE CASCADE
 );
+comment on table @NAMESPACE at .sl_trigger is 'Indicates the name of a trigger [for what purpose?]';
 
 
 -- ----------------------------------------------------------------------
@@ -118,6 +133,11 @@
 		FOREIGN KEY (seq_set)
 		REFERENCES @NAMESPACE at .sl_set (set_id)
 );
+comment on table @NAMESPACE at .sl_sequence is 'Similar to sl_table, each entry identifies a sequence being replicated.
+seq_id is an internally-used ID for Slony-I to use in its sequencing of updates
+seq_reloid is the OID of the sequence object
+seq_set indicates which replication set the object is in
+seq_comment is a human-oriented comment';
 
 
 -- ----------------------------------------------------------------------
@@ -138,6 +158,13 @@
 		FOREIGN KEY (pa_client)
 		REFERENCES @NAMESPACE at .sl_node (no_id)
 );
+comment on table @NAMESPACE at .sl_path is 'Holds connection information for the paths between nodes, and the synchronisation delay
+
+pa_server - The Node ID # (from sl_node.no_id) of the data source
+pa_client - The Node ID # (from sl_node.no_id) of the data target
+pa_conninfo - The PostgreSQL connection string used to connect to the source node.
+pa_connretry - The synchronisation delay, in seconds
+';
 
 
 -- ----------------------------------------------------------------------
@@ -157,6 +184,12 @@
 		FOREIGN KEY (li_provider, li_receiver)
 		REFERENCES @NAMESPACE at .sl_path (pa_server, pa_client)
 );
+comment on table @NAMESPACE at .sl_listen is 'Indicates how nodes listen to events from other nodes in the Slony-I network.
+
+li_origin		:	Integer.  The ID # (from sl_node.no_id) of the node this listener is operating on
+li_provider		:	Integer.  The ID # (from sl_node.no_id) of the source node for this listening event
+li_receiver		:	Integer.  The ID # (from sl_node.no_id) of the target node for this listening event
+';
 
 
 -- ----------------------------------------------------------------------
@@ -178,6 +211,7 @@
 		FOREIGN KEY (sub_set)
 		REFERENCES @NAMESPACE at .sl_set (set_id)
 );
+comment on table @NAMESPACE at .sl_subscribe is 'Not documented yet';
 
 
 -- ----------------------------------------------------------------------
@@ -203,6 +237,41 @@
 	CONSTRAINT "sl_event-pkey"
 		PRIMARY KEY (ev_origin, ev_seqno)
 );
+comment on table @NAMESPACE at .sl_event is 'Holds information about replication events.
+
+After a period of time, Slony removes old confirmed events from both this table and the sl_confirm table.
+
+ev_origin		:	Integer.  The ID # (from sl_node.no_id) of the source node for this event
+ev_seqno		:	Integer.  The ID # for the event
+ev_timestamp	:	Timestamp.  When this event record was created
+ev_minxid		:
+ev_maxxid		:
+ev_xip			:	String.
+ev_type			:	String.  The type of event this record is for.
+
+				SYNC				= Synchronise
+				STORE_NODE			=
+				ENABLE_NODE			=
+				DROP_NODE			=
+				STORE_PATH			=
+				DROP_PATH			=
+				STORE_LISTEN		=
+				DROP_LISTEN			=
+				STORE_SET			=
+				DROP_SET			=
+				MERGE_SET			=
+				SET_ADD_TABLE		=
+				SET_ADD_SEQUENCE	=
+				STORE_TRIGGER		=
+				DROP_TRIGGER		=
+				MOVE_SET			=
+				FAILOVER_SET		=
+				SUBSCRIBE_SET		=
+				ENABLE_SUBSCRIPTION	=
+				UNSUBSCRIBE_SET		=
+				DDL_SCRIPT			=
+				ADJUST_SEQ			=
+';
 
 
 -- ----------------------------------------------------------------------
@@ -214,12 +283,20 @@
 	con_seqno			int8,
 	con_timestamp		timestamp DEFAULT timeofday()::timestamp
 );
+comment on table @NAMESPACE at .sl_confirm is 'Holds confirmation of replication events.
+
+After a period of time, Slony removes old confirmed events from both this table and the sl_event table.
+
+con_origin		:	Integer.  The ID # (from sl_node.no_id) of the source node for this event  
+con_received	:	Integer.
+con_seqno		:	Integer.  The ID # for the event
+con_timestamp	:	Timestamp.  When this event was confirmed
+';
 create index sl_confirm_idx1 on @NAMESPACE at .sl_confirm
 	(con_origin, con_received, con_seqno);
 create index sl_confirm_idx2 on @NAMESPACE at .sl_confirm
 	(con_received, con_seqno);
 
-
 -- ----------------------------------------------------------------------
 -- TABLE sl_seqlog
 -- ----------------------------------------------------------------------
@@ -229,6 +306,7 @@
 	seql_ev_seqno		int8,
 	seql_last_value		int8
 );
+comment on table @NAMESPACE at .sl_seqlog is 'Not documented yet';
 create index sl_seqlog_idx on @NAMESPACE at .sl_seqlog
 	(seql_origin, seql_ev_seqno, seql_seqid);
 
@@ -283,6 +361,13 @@
 create index sl_log_1_idx1 on @NAMESPACE at .sl_log_1
 	(log_origin, log_xid @NAMESPACE at .xxid_ops, log_actionseq);
 
+comment on table @NAMESPACE at .sl_log_1 is 'Stores each change to be propagated to subscriber nodes
+
+log_origin - origin node from which the change came
+log_xid - transaction ID on the origin node
+log_table_id - the table ID (from sl_table.tab_id) that this log entry is to affect
+log_cmdtype - replication action to take. U = Update, I = Insert, D = DELETE
+log_cmddata - the data needed to perform the log action';
 
 -- ----------------------------------------------------------------------
 -- TABLE sl_log_2
@@ -295,6 +380,13 @@
 	log_cmdtype			char,
 	log_cmddata			text
 );
+comment on table @NAMESPACE at .sl_log_2 is 'Stores each change to be propagated to subscriber nodes
+
+log_origin - origin node from which the change came
+log_xid - transaction ID on the origin node
+log_table_id - the table ID (from sl_table.tab_id) that this log entry is to affect
+log_cmdtype - replication action to take. U = Update, I = Insert, D = DELETE
+log_cmddata - the data needed to perform the log action';
 create index sl_log_2_idx1 on @NAMESPACE at .sl_log_2
 	(log_origin, log_xid @NAMESPACE at .xxid_ops, log_actionseq);
 
@@ -313,6 +405,7 @@
 create sequence @NAMESPACE at .sl_local_node_id
 	MINVALUE -1;
 SELECT setval('@NAMESPACE at .sl_local_node_id', -1);
+comment on sequence @NAMESPACE at .sl_local_node_id is 'The local node ID is initialized to -1, meaning that this node is not initialized yet.';
 
 
 -- ----------------------------------------------------------------------
@@ -321,7 +414,7 @@
 --	The sequence for numbering events originating from this node.
 -- ----------------------------------------------------------------------
 create sequence @NAMESPACE at .sl_event_seq;
-
+comment on sequence @NAMESPACE at .sl_event_seq is 'The sequence for numbering events originating from this node.';
 
 -- ----------------------------------------------------------------------
 -- SEQUENCE sl_action_seq
@@ -331,6 +424,8 @@
 --	statements.
 -- ----------------------------------------------------------------------
 create sequence @NAMESPACE at .sl_action_seq;
+comment on sequence @NAMESPACE at .sl_action_seq is 'The sequence to number statements in the transaction logs, so that the replication engines can figure out the "agreeable" order of statements.';
+
 
 
 -- ----------------------------------------------------------------------
@@ -342,6 +437,7 @@
 -- ----------------------------------------------------------------------
 create sequence @NAMESPACE at .sl_rowid_seq;
 grant select, update on @NAMESPACE at .sl_rowid_seq to public;
+comment on sequence @NAMESPACE at .sl_rowid_seq is 'Application tables that do not have a natural primary key must be modified and an int8 column added that serves as a rowid for us.  The values are assigned with a default from this sequence.';
 
 
 -- ----------------------------------------------------------------------
@@ -360,6 +456,17 @@
 create sequence @NAMESPACE at .sl_log_status
 	MINVALUE 0 MAXVALUE 3;
 SELECT setval('@NAMESPACE at .sl_log_status', 0);
+comment on sequence @NAMESPACE at .sl_log_status is '
+Bit 0x01 determines the currently active log table
+Bit 0x02 tells if the engine needs to read both logs
+after switching until the old log is clean and truncated.
+
+Possible values:
+	0		sl_log_1 active, sl_log_2 clean
+	1		sl_log_2 active, sl_log_1 clean
+	2		sl_log_1 active, sl_log_2 unknown - cleanup
+	3		sl_log_2 active, sl_log_1 unknown - cleanup
+';
 
 
 -- **********************************************************************
@@ -377,7 +484,8 @@
 create table @NAMESPACE at .sl_config_lock (
 	dummy				integer
 );
-
+comment on table @NAMESPACE at .sl_config_lock is 'This table exists solely to prevent overlapping execution of configuration change procedures and the resulting possible deadlocks.
+';
 
 -- ----------------------------------------------------------------------
 -- Last but not least grant USAGE to the replication schema objects.
-- 
(reverse (concatenate 'string "ofni.sailifa.ac" "@" "enworbbc"))
<http://dev6.int.libertyrms.com/>
Christopher Browne
(416) 673-4124 (land)