Thu Aug 5 19:10:53 PDT 2004
- Previous message: [Slony1-commit] By wieck: Agrument list mismatch in first appearence of setSessionRole()
- Next message: [Slony1-commit] By cbbrowne: Added crossreference to schemadoc.html
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Log Message:
-----------
Finished up having a comprehensive set of comments on all Slony functions,
alongside the autodoc-generated documentation.
Modified Files:
--------------
slony1-engine/doc/howto:
schemadoc.html (r1.3 -> r1.4)
slony1-engine/src/backend:
slony1_funcs.sql (r1.19 -> r1.20)
-------------- next part --------------
Index: schemadoc.html
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/doc/howto/schemadoc.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -Ldoc/howto/schemadoc.html -Ldoc/howto/schemadoc.html -u -w -r1.3 -r1.4
--- doc/howto/schemadoc.html
+++ doc/howto/schemadoc.html
@@ -111,7 +111,7 @@
<body>
<!-- Primary Index -->
- <p><br><br>Dumped on 2004-08-04</p>
+ <p><br><br>Dumped on 2004-08-05</p>
<h1><a name="index">Index of database - schemadoc</a></h1>
<ul>
@@ -2459,7 +2459,14 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>alterTableForReplication(tab_id)
+Sets up a table for replication.
+On the origin, this involves adding the "logTrigger()" trigger to the
+table.
+
+On a subscriber node, this involves disabling triggers and rules, and
+adding in the trigger that denies write access to replicated tables.</p>
<pre>
declare
p_tab_id alias for $1;
@@ -2480,8 +2487,8 @@
v_no_id := schemadoc.getLocalNodeId('_schemadoc');
-- ----
- -- Get the sl_table row and the current tables origin. Check
- -- that the table currently is NOT in altered state.
+ -- Get the sl_table row and the current origin of the table.
+ -- Verify that the table currently is NOT in altered state.
-- ----
select T.tab_reloid, T.tab_set, T.tab_idxname, T.tab_altered,
S.set_origin, PGX.indexrelid,
@@ -2591,7 +2598,14 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>alterTableRestore (tab_id)
+
+Restores table tab_id from being replicated.
+
+On the origin, this simply involves dropping the "logtrigger" trigger.
+On subscriber nodes, this involves dropping the "denyaccess" trigger,
+and restoring user triggers and rules.</p>
<pre>
declare
p_tab_id alias for $1;
@@ -2701,7 +2715,10 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
-
+ <p>cleaning old data out of sl_confirm, sl_event. Removes all but the
+last sl_confirm row per (origin,receiver), and then removes all events
+that are confirmed by all nodes in the whole cluster up to the last
+SYNC. </p>
<pre>
declare
v_max_row record;
@@ -2869,7 +2886,12 @@
</h2>
<h3>Returns: text</h3>
<h3>Language: PLPGSQL</h3>
+ <p>determineAttKindSerial (tab_fqname)
+A table was that was specified without a primary key is added to the
+replication. Assume that tableAddKey() was called before and finish
+the creation of the serial column. The return an attkind according to
+that.</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -2941,7 +2963,11 @@
</h2>
<h3>Returns: text</h3>
<h3>Language: PLPGSQL</h3>
+ <p>determineAttKindUnique (tab_fqname, indexname)
+Given a tablename, return the Slony-I specific attkind (used for the
+log trigger) of the table. Use the specified unique index or the
+primary key (if indexname is NULL).</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -3031,7 +3057,9 @@
</h2>
<h3>Returns: name</h3>
<h3>Language: PLPGSQL</h3>
+ <p>determineIdxnameSerial (tab_fqname)
+Given a tablename, construct the index name of the serial column.</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -3065,7 +3093,11 @@
</h2>
<h3>Returns: name</h3>
<h3>Language: PLPGSQL</h3>
+ <p>FUNCTION determineIdxnameUnique (tab_fqname, indexname)
+Given a tablename, tab_fqname, check that the unique index, indexname,
+exists or return the primary key index name for the table. If there
+is no unique index, it raises an exception.</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -3706,7 +3738,11 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>enableSubscription (sub_set, sub_provider, sub_receiver)
+Indicates that sub_receiver intends subscribing to set sub_set from
+sub_provider. Work is all done by the internal function
+enableSubscription_int (sub_set, sub_provider, sub_receiver).</p>
<pre>
declare
p_sub_set alias for $1;
@@ -3724,7 +3760,14 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>enableSubscription_int (sub_set, sub_provider, sub_receiver)
+
+Internal function to enable subscription of node sub_receiver to set
+sub_set via node sub_provider.
+slon does most of the work; all we need do here is to remember that it
+happened. The function updates sl_subscribe, indicating that the
+subscription has become active.</p>
<pre>
declare
p_sub_set alias for $1;
@@ -4129,7 +4172,11 @@
</h2>
<h3>Returns: bigint</h3>
<h3>Language: PLPGSQL</h3>
+ <p>forwardConfirm (p_con_origin, p_con_received, p_con_seqno, p_con_timestamp)
+Confirms (recorded in sl_confirm) that items from p_con_origin up to
+p_con_seqno have been received by node p_con_received as of
+p_con_timestamp, and raises an event to forward this confirmation.</p>
<pre>
declare
p_con_origin alias for $1;
@@ -5425,7 +5472,10 @@
</h2>
<h3>Returns: bigint</h3>
<h3>Language: PLPGSQL</h3>
+ <p>subscribeSet (sub_set, sub_provider, sub_receiver, sub_forward)
+Makes sure that the receiver is not the provider, then stores the
+subscription, and publishes the SUBSCRIBE_SET event to other nodes.</p>
<pre>
declare
p_sub_set alias for $1;
@@ -5485,7 +5535,10 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>subscribeSet_int (sub_set, sub_provider, sub_receiver, sub_forward)
+Internal actions for subscribing receiver sub_receiver to subscription
+set sub_set.</p>
<pre>
declare
p_sub_set alias for $1;
@@ -5573,7 +5626,9 @@
</h2>
<h3>Returns: text</h3>
<h3>Language: PLPGSQL</h3>
-
+ <p>tableAddKey (tab_fqname) - if the table has not got a column of the
+form _Slony-I_<clustername>_rowID, then add it as a bigint, defaulted
+to nextval() for a sequence created for the cluster.</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -5646,7 +5701,10 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>tableDropKey (tab_id)
+If the specified table has a column "_Slony-I_<clustername>_rowID",
+then drop it.</p>
<pre>
declare
p_tab_id alias for $1;
@@ -5697,7 +5755,10 @@
</h2>
<h3>Returns: boolean</h3>
<h3>Language: PLPGSQL</h3>
+ <p>tableHasSerialKey (tab_fqname)
+Checks if a table has our special serial key column that is used if
+the table has no natural unique constraint.</p>
<pre>
declare
p_tab_fqname alias for $1;
@@ -5820,7 +5881,14 @@
</h2>
<h3>Returns: bigint</h3>
<h3>Language: PLPGSQL</h3>
+ <p>unsubscribeSet (sub_set, sub_receiver)
+Unsubscribe node sub_receiver from subscription set sub_set. This is
+invoked on the receiver node. It verifies that this does not break
+any chains (e.g. - where sub_receiver is a provider for another node),
+then restores tables, drops Slony-specific keys, drops table entries
+for the set, drops the subscription, and generates an UNSUBSCRIBE_SET
+node to publish that the node is being dropped.</p>
<pre>
declare
p_sub_set alias for $1;
@@ -5897,7 +5965,11 @@
</h2>
<h3>Returns: integer</h3>
<h3>Language: PLPGSQL</h3>
+ <p>unsubscribeSet_int (sub_set, sub_receiver)
+All the REAL work of removing the subscriber is done before the event
+is generated, so this function just has to drop the references to the
+subscription in sl_subscribe.</p>
<pre>
declare
p_sub_set alias for $1;
Index: slony1_funcs.sql
===================================================================
RCS file: /usr/local/cvsroot/slony1/slony1-engine/src/backend/slony1_funcs.sql,v
retrieving revision 1.19
retrieving revision 1.20
diff -Lsrc/backend/slony1_funcs.sql -Lsrc/backend/slony1_funcs.sql -u -w -r1.19 -r1.20
--- src/backend/slony1_funcs.sql
+++ src/backend/slony1_funcs.sql
@@ -2749,8 +2749,8 @@
v_no_id := @NAMESPACE at .getLocalNodeId(''_ at CLUSTERNAME@'');
-- ----
- -- Get the sl_table row and the current tables origin. Check
- -- that the table currently is NOT in altered state.
+ -- Get the sl_table row and the current origin of the table.
+ -- Verify that the table currently is NOT in altered state.
-- ----
select T.tab_reloid, T.tab_set, T.tab_idxname, T.tab_altered,
S.set_origin, PGX.indexrelid,
@@ -2853,7 +2853,15 @@
return p_tab_id;
end;
' language plpgsql;
+comment on function @NAMESPACE at .alterTableForReplication(int4) is
+'alterTableForReplication(tab_id)
+
+Sets up a table for replication.
+On the origin, this involves adding the "logTrigger()" trigger to the
+table.
+On a subscriber node, this involves disabling triggers and rules, and
+adding in the trigger that denies write access to replicated tables.';
-- ----------------------------------------------------------------------
-- FUNCTION alterTableRestore (tab_id)
@@ -2962,7 +2970,15 @@
return p_tab_id;
end;
' language plpgsql;
+comment on function @NAMESPACE at .alterTableRestore (int4) is
+'alterTableRestore (tab_id)
+
+Restores table tab_id from being replicated.
+On the origin, this simply involves dropping the "logtrigger" trigger.
+
+On subscriber nodes, this involves dropping the "denyaccess" trigger,
+and restoring user triggers and rules.';
-- ----------------------------------------------------------------------
-- FUNCTION subscribeSet (sub_set, sub_provider, sub_receiver, sub_forward)
@@ -3021,7 +3037,11 @@
case p_sub_forward when true then ''t'' else ''f'' end);
end;
' language plpgsql;
+comment on function @NAMESPACE at .subscribeSet (int4, int4, int4, bool) is
+'subscribeSet (sub_set, sub_provider, sub_receiver, sub_forward)
+Makes sure that the receiver is not the provider, then stores the
+subscription, and publishes the SUBSCRIBE_SET event to other nodes.';
-- ----------------------------------------------------------------------
-- FUNCTION subscribeSet_int (sub_set, sub_provider, sub_receiver, sub_forward)
@@ -3109,6 +3129,11 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .subscribeSet_int (int4, int4, int4, bool) is
+'subscribeSet_int (sub_set, sub_provider, sub_receiver, sub_forward)
+
+Internal actions for subscribing receiver sub_receiver to subscription
+set sub_set.';
-- ----------------------------------------------------------------------
-- FUNCTION unsubscribeSet (sub_set, sub_receiver)
@@ -3184,7 +3209,15 @@
p_sub_set, p_sub_receiver);
end;
' language plpgsql;
+comment on function @NAMESPACE at .unsubscribeSet (int4, int4) is
+'unsubscribeSet (sub_set, sub_receiver)
+Unsubscribe node sub_receiver from subscription set sub_set. This is
+invoked on the receiver node. It verifies that this does not break
+any chains (e.g. - where sub_receiver is a provider for another node),
+then restores tables, drops Slony-specific keys, drops table entries
+for the set, drops the subscription, and generates an UNSUBSCRIBE_SET
+node to publish that the node is being dropped.';
-- ----------------------------------------------------------------------
-- FUNCTION unsubscribeSet_int (sub_set, sub_receiver)
@@ -3212,7 +3245,12 @@
return p_sub_set;
end;
' language plpgsql;
+comment on function @NAMESPACE at .unsubscribeSet_int (int4, int4) is
+'unsubscribeSet_int (sub_set, sub_receiver)
+All the REAL work of removing the subscriber is done before the event
+is generated, so this function just has to drop the references to the
+subscription in sl_subscribe.';
-- ----------------------------------------------------------------------
-- FUNCTION enableSubscription (sub_set, sub_provider, sub_receiver)
@@ -3230,6 +3268,12 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .enableSubscription (int4, int4, int4) is
+'enableSubscription (sub_set, sub_provider, sub_receiver)
+
+Indicates that sub_receiver intends subscribing to set sub_set from
+sub_provider. Work is all done by the internal function
+enableSubscription_int (sub_set, sub_provider, sub_receiver).';
-- ----------------------------------------------------------------------
-- FUNCTION enableSubscription_int (sub_set, sub_provider, sub_receiver)
@@ -3270,9 +3314,18 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .enableSubscription_int (int4, int4, int4) is
+'enableSubscription_int (sub_set, sub_provider, sub_receiver)
+
+Internal function to enable subscription of node sub_receiver to set
+sub_set via node sub_provider.
+
+slon does most of the work; all we need do here is to remember that it
+happened. The function updates sl_subscribe, indicating that the
+subscription has become active.';
-- ----------------------------------------------------------------------
--- FUNCTION forwardConfirm ()
+-- FUNCTION forwardConfirm (p_con_origin, p_con_received, p_con_seqno, p_con_timestamp)
--
-- ----------------------------------------------------------------------
create or replace function @NAMESPACE at .forwardConfirm (int4, int4, int8, timestamp)
@@ -3301,7 +3354,12 @@
return v_max_seqno;
end;
' language plpgsql;
+comment on function @NAMESPACE at .forwardConfirm (int4, int4, int8, timestamp) is
+'forwardConfirm (p_con_origin, p_con_received, p_con_seqno, p_con_timestamp)
+Confirms (recorded in sl_confirm) that items from p_con_origin up to
+p_con_seqno have been received by node p_con_received as of
+p_con_timestamp, and raises an event to forward this confirmation.';
-- ----------------------------------------------------------------------
-- FUNCTION cleanupEvent ()
@@ -3351,7 +3409,11 @@
return 0;
end;
' language plpgsql;
-
+comment on function @NAMESPACE at .cleanupEvent () is
+'cleaning old data out of sl_confirm, sl_event. Removes all but the
+last sl_confirm row per (origin,receiver), and then removes all events
+that are confirmed by all nodes in the whole cluster up to the last
+SYNC. ';
-- ----------------------------------------------------------------------
-- FUNCTION tableAddKey (tab_fqname)
@@ -3427,13 +3489,17 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .tableAddKey(text) is
+
+'tableAddKey (tab_fqname) - if the table has not got a column of the
+form _Slony-I_<clustername>_rowID, then add it as a bigint, defaulted
+to nextval() for a sequence created for the cluster.';
-- ----------------------------------------------------------------------
-- FUNCTION tableDropKey (tab_id)
--
--- If the specified table does not have a column
--- "_Slony-I_<clustername>_rowID", then add it as a bigint
--- with default nextval('"_<clustername>".sl_rowid_seq').
+-- If the specified table has a column
+-- "_Slony-I_<clustername>_rowID", then drop it.
-- ----------------------------------------------------------------------
create or replace function @NAMESPACE at .tableDropKey(int4) returns int4
as '
@@ -3480,6 +3546,11 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .tableDropKey(int4) is
+'tableDropKey (tab_id)
+
+If the specified table has a column "_Slony-I_<clustername>_rowID",
+then drop it.';
-- ----------------------------------------------------------------------
-- FUNCTION determineIdxnameUnique (tab_fqname, indexname)
@@ -3540,6 +3611,12 @@
return v_idxrow.relname;
end;
' language plpgsql called on null input;
+comment on function @NAMESPACE at .determineIdxnameUnique(text, name) is
+'FUNCTION determineIdxnameUnique (tab_fqname, indexname)
+
+Given a tablename, tab_fqname, check that the unique index, indexname,
+exists or return the primary key index name for the table. If there
+is no unique index, it raises an exception.';
-- ----------------------------------------------------------------------
@@ -3574,7 +3651,10 @@
return v_row.relname || ''__Slony-I_ at CLUSTERNAME@_rowID_key'';
end;
' language plpgsql called on null input;
+comment on function @NAMESPACE at .determineIdxnameSerial(text) is
+'determineIdxnameSerial (tab_fqname)
+Given a tablename, construct the index name of the serial column.';
-- ----------------------------------------------------------------------
-- FUNCTION determineAttKindUnique (tab_fqname, indexname)
@@ -3667,6 +3747,12 @@
end;
' language plpgsql called on null input;
+comment on function @NAMESPACE at .determineAttkindUnique(text, name) is
+'determineAttKindUnique (tab_fqname, indexname)
+
+Given a tablename, return the Slony-I specific attkind (used for the
+log trigger) of the table. Use the specified unique index or the
+primary key (if indexname is NULL).';
-- ----------------------------------------------------------------------
-- FUNCTION determineAttKindSerial (tab_fqname)
@@ -3743,6 +3829,13 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .determineAttkindSerial(text) is
+'determineAttKindSerial (tab_fqname)
+
+A table was that was specified without a primary key is added to the
+replication. Assume that tableAddKey() was called before and finish
+the creation of the serial column. The return an attkind according to
+that.';
-- ----------------------------------------------------------------------
-- FUNCTION tableHasSerialKey (tab_fqname)
@@ -3771,4 +3864,9 @@
end;
' language plpgsql;
+comment on function @NAMESPACE at .tableHasSerialKey(text) is
+'tableHasSerialKey (tab_fqname)
+
+Checks if a table has our special serial key column that is used if
+the table has no natural unique constraint.';
- Previous message: [Slony1-commit] By wieck: Agrument list mismatch in first appearence of setSessionRole()
- Next message: [Slony1-commit] By cbbrowne: Added crossreference to schemadoc.html
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
More information about the Slony1-commit mailing list