--
-- Transportable Optimizer Mode (TOM) for PostgreSQL
--
-- Development 	simon@2ndquadrant.com
-- Installation cbbrowne@acm.org
--

TOM is designed to allow you to take statistics from one database
server to another, fully emulating the environment for SQL planning.

Example use cases are
* 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]
	cd <postgresql-source-tree>
	tar cvf TOM.tar
	cd contrib/TOM
	make
	make install - copies .so file to $LIB directory

	No functions need to be created

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)

	pg_dump [-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

    Either set for all users via postgresql.conf

	   shared_preload_libraries = '$libdir/tom_hooks'

	or set for individual sessions using

	  LOAD '$libdir/tom_hooks';

11. EXPLAIN your queries


