--
-- Transportable Optimizer Mode (TOM) for PostgreSQL
--
-- simon@2ndquadrant.com
--

TOM is designed to allow you to take statistics from one database
server to another, allowing you to recreate the same environment
under which SQL planning occurred.

You may wish to do this for the following reasons
* creating a development server
* providing details of a problem SQL statement to a remote analyst

Process is straightforward if you are using same schema and tablenames
on both database servers (recommended).

Actions on Source database:
===========================
[0. Install TOM, if not already installed]

1. VACUUM ANALYZE all required tables 

	VACUUM ANALYZE [tablename];

	This is just to make sure stats are up to date before we transport them.

2. Get stats data for TOM 

	psql -f get_data_for_tom.sql

	Produces 
		tom_pg_statistic.data 
		tom_pg_class.data

	This includes all stats for tables you have access to, so you may wish
	to edit this down if you have security concerns.

3. Get table metadata (and possibly data, or a sample of it)

	pgdump [-s] -t tablename > user_tables.sql

	If you include data as well, then it may be possible to run an
	EXPLAIN ANALYZE as well as an EXPLAIN. Of course, extracting a
	representative sample is difficult.

Between databases:
==================
4. Transport data to target system
e.g. RFC 1149, email etc

Actions on Target database:
===========================

5. Determine the name of the database and schema you intend to use for TOM

	TOMSCHEMA=tom
	TESTDB=testtomdb
	export TOMSCHEMA TESTDB

6. Create user tables (and load data full/sample as required)

	e.g.
	createdb ${TESTDB}
	psql -f user_tables.sql -d ${TESTDB}

7. Create TOM tables

	psql -c "create schema ${TOMSCHEMA};" -d ${TESTDB}
	psql -f create_tom_tables.sql --single-transaction -v TOM_SCHEMA='${TOMSCHEMA}' -d ${TESTDB}

8. Load TOM data into target database

	e.g.
	psql -f load_data_for_tom.sql --single-transaction  -v TOM_SCHEMA='${TOMSCHEMA}' -d ${TESTDB}

9. Create mapping between target catalog and source stats

	psql -f get_mapping_for_tom.sql -v TOM_SCHEMA=${TOMSCHEMA} -d ${TESTDB}

	We need to be able to match up objects between source and target. This
	script matches up objects that have matching schema and tablenames. If
	you have a different or more complex matching algorithm, run it now.

10. Setup TOM plugin 

	psql -c "LOAD '\$libdir/tom_hooks';" -d ${TESTDB}

11. EXPLAIN your queries


