add table docs

diff --git a/docs/Cookbook b/docs/Cookbook
index f2ab01219ffd8a7bc2c6d53e26a2d3b7bb63090a..6ed51643fbf01b896cf2d57935a0a0d3f052c4c7 100644 (file)
--- a/docs/Cookbook
+++ b/docs/Cookbook
@@ -28,3 +28,11 @@ use a different target service name:
 use a different source service name:
 
        copyrows -s <sourceservicename>
+
+drop a single table from an ongoing migration:
+
+       delete from migration.posting where table_name = ?
+
+set up a single table to be migrated:
+
+       select migration.setup_table('schema.table'::regclass);

diff --git a/docs/Overview b/docs/Overview
index 980c7fefa0c298ca35bd9713cbde466469c201ff..f1676c7d5b9517ee3274b8a1a7030dd78f6b4b90 100644 (file)
--- a/docs/Overview
+++ b/docs/Overview
@@ -1,11 +1,28 @@
 Overview of Setup
 -----------------
 
-unpack the tarball
-if needed, create the target database and load the schema
-setup source and target services
-run 'setup source' and 'setup target'
-run copyrows, probably from cron, it will limit itself
-
-when the migration.queue table on the source is empty, the migration is
-done.
+* unpack the tarball
+* if needed, create the target database and load the schema
+* setup source and target services
+* run 'setup source' and 'setup target'
+* run copyrows, probably from cron, it will limit itself
+
+when the migration.queue table on the source is empty, the migration is done.
+
+Control Tables
+--------------
+
+The system is controlled through two tables on the source database, both in the
+migration schema.
+
+The first table, 'posting', has information about each table to be migrated,
+including what queries to use and whether or not to use copy or insert for the
+initial migration.  If a table is not here, the system won't copy the rows from
+that table.  Consequently, you can remove a table from the migration by
+deleting the corresponding row from this table.
+
+The second table, 'queue', has information about the rows that need to be
+migrated.  It is initially populated by setup_table(), which inserts a row into
+posting and further rows into the queue table.  Triggers on the tables then
+will put rows into the queue table which track inserts, updates, and deletes on
+the tables to be migrated.