Thu Jul 29 15:52:39 PDT 2004
- Previous message: [Slony1-general] First go at documenting how Slony stores info
- Next message: [Slony1-general] First go at documenting how Slony stores info
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
I very much support the idea of commenting the functions.. On July 29, 2004 08:16 am, Christopher Browne wrote: > 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. -- Darcy Buskermolen Wavefire Technologies Corp. ph: 250.717.0200 fx: 250.763.1759 http://www.wavefire.com
- Previous message: [Slony1-general] First go at documenting how Slony stores info
- Next message: [Slony1-general] First go at documenting how Slony stores info
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Slony1-general mailing list