pgstattuple README			2002/08/29 Tatsuo Ishii

1. What is pgstattuple?

   pgstattuple returns the table length, percentage of the "dead"
   tuples of a table and other info. This may help users to determine
   whether vacuum is necessary or not. Here is an example session:

test=# \x
Expanded display is on.
test=# select * from pgstattuple('pg_catalog.pg_proc');
-[ RECORD 1 ]------+-------
table_len          | 458752
tuple_count        | 1470
tuple_len          | 438896
tuple_percent      | 95.67
dead_tuple_count   | 11
dead_tuple_len     | 3157
dead_tuple_percent | 0.69
free_space         | 8932
free_percent       | 1.95


Here are explanations for each column:

table_len		-- physical table length in bytes
tuple_count		-- number of live tuples
tuple_len		-- total tuples length in bytes
tuple_percent		-- live tuples in %
dead_tuple_len		-- total dead tuples length in bytes
dead_tuple_percent	-- dead tuples in %
free_space		-- free space in bytes
free_percent		-- free space in %

2. Installing pgstattuple

    $ make
    $ make install
    $ psql -e -f /usr/local/pgsql/share/contrib/pgstattuple.sql test

3. Using pgstattuple

   pgstattuple may be called as a table function and is
   defined as follows:

   CREATE OR REPLACE FUNCTION pgstattuple(text) RETURNS pgstattuple_type
     AS 'MODULE_PATHNAME', 'pgstattuple'
     LANGUAGE 'c' STRICT;

   CREATE OR REPLACE FUNCTION pgstattuple(oid) RETURNS pgstattuple_type
     AS 'MODULE_PATHNAME', 'pgstattuplebyid'
     LANGUAGE 'c' STRICT;

   The argument is the table name (optionally it may be qualified)
   or the OID of the table.  Note that pgstattuple only returns
   one row.

4. Notes

   pgstattuple acquires only a read lock on the table. So concurrent
   update may affect the result.

   pgstattuple judges a tuple is "dead" if HeapTupleSatisfiesNow()
   returns false.