From: Nathan Wagner <nw@hydaspes.if.org>
Date: Thu, 18 Nov 2021 20:15:22 +0000 (-0600)
Subject: add table docs
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b86bddc5601cc20f37aa6a9be751a93b020efd1a;p=pgm

add table docs
---

diff --git a/docs/Cookbook b/docs/Cookbook
index f2ab012..6ed5164 100644
--- 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 980c7fe..f1676c7 100644
--- 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.