head	1.12;
access;
symbols
	REL7_4_29:1.6
	REL8_0_25:1.6
	REL8_1_21:1.6
	REL8_2_17:1.9
	REL7_4_28:1.6
	REL8_0_24:1.6
	REL8_1_20:1.6
	REL8_2_16:1.9
	REL7_4_27:1.6
	REL8_0_23:1.6
	REL8_1_19:1.6
	REL8_2_15:1.9
	REL7_4_26:1.6
	REL8_0_22:1.6
	REL8_1_18:1.6
	REL8_2_14:1.9
	REL7_4_25:1.6
	REL8_0_21:1.6
	REL8_1_17:1.6
	REL8_2_13:1.9
	REL7_4_24:1.6
	REL8_0_20:1.6
	REL8_1_16:1.6
	REL8_2_12:1.9
	REL7_4_23:1.6
	REL8_0_19:1.6
	REL8_1_15:1.6
	REL8_2_11:1.9
	REL7_4_22:1.6
	REL8_0_18:1.6
	REL8_1_14:1.6
	REL8_2_10:1.9
	REL7_4_21:1.6
	REL8_0_17:1.6
	REL8_1_13:1.6
	REL8_2_9:1.9
	REL7_4_20:1.6
	REL8_0_16:1.6
	REL8_1_12:1.6
	REL8_2_8:1.9
	REL8_2_7:1.9
	REL7_3_21:1.5
	REL7_4_19:1.6
	REL8_0_15:1.6
	REL8_1_11:1.6
	REL8_2_6:1.9
	REL8_3_BETA2:1.11
	REL8_3_BETA1:1.11
	REL7_3_20:1.5
	REL7_4_18:1.6
	REL8_0_14:1.6
	REL8_1_10:1.6
	REL8_2_5:1.9
	REL7_3_19:1.5
	REL7_4_17:1.6
	REL8_0_13:1.6
	REL8_1_9:1.6
	REL8_2_4:1.9
	REL8_0_12:1.6
	REL8_1_8:1.6
	REL8_2_3:1.9
	REL7_3_18:1.5
	REL7_4_16:1.6
	REL8_0_11:1.6
	REL8_1_7:1.6
	REL8_2_2:1.9
	REL8_0_10:1.6
	REL8_1_6:1.6
	REL8_2_1:1.9
	REL7_4_15:1.6
	REL7_3_17:1.5
	REL8_2_STABLE:1.9.0.2
	REL8_2_0:1.9
	REL8_2_RC1:1.9
	REL8_2_BETA3:1.9
	REL8_2_BETA2:1.9
	REL8_1_5:1.6
	REL8_0_9:1.6
	REL7_4_14:1.6
	REL7_3_16:1.5
	REL8_2_BETA1:1.9
	REL7_3_15:1.5
	REL7_4_13:1.6
	REL8_0_8:1.6
	REL8_1_4:1.6
	REL7_3_14:1.5
	REL7_4_12:1.6
	REL8_0_7:1.6
	REL8_1_3:1.6
	REL7_3_13:1.5
	REL7_4_11:1.6
	REL8_0_6:1.6
	REL8_1_2:1.6
	REL7_3_12:1.5
	REL7_4_10:1.6
	REL8_0_5:1.6
	REL8_1_1:1.6
	REL8_1_STABLE:1.6.0.10
	REL8_1_0:1.6
	REL8_1_0RC1:1.6
	REL8_1_0BETA4:1.6
	REL8_1_0BETA3:1.6
	REL7_3_11:1.5
	REL7_4_9:1.6
	REL8_0_4:1.6
	REL8_1_0BETA2:1.6
	REL8_1_0BETA1:1.6
	REL7_2_8:1.2
	REL7_3_10:1.5
	REL7_4_8:1.6
	REL8_0_3:1.6
	REL8_0_2:1.6
	REL7_2_7:1.2
	REL7_3_9:1.5
	REL7_4_7:1.6
	REL8_0_1:1.6
	REL8_0_STABLE:1.6.0.8
	REL8_0_0:1.6.0.6
	REL8_0_0RC5:1.6
	REL8_0_0RC4:1.6
	REL8_0_0RC3:1.6
	REL8_0_0RC2:1.6
	REL8_0_0RC1:1.6
	REL8_0_0BETA5:1.6
	REL8_0_0BETA4:1.6
	REL7_4_6:1.6
	REL7_3_8:1.5
	REL7_2_6:1.2
	REL8_0_0BETA3:1.6
	REL8_0_0BETA2:1.6
	REL7_2_5:1.2
	REL7_4_5:1.6
	REL7_3_7:1.5
	REL7_4_4:1.6
	REL8_0_0BETA1:1.6
	REL7_4_3:1.6
	REL7_4_2:1.6
	REL7_3_6:1.5
	REL7_4_1:1.6
	REL7_3_5:1.5
	REL7_4:1.6
	REL7_4_RC2:1.6
	REL7_4_STABLE:1.6.0.4
	REL7_4_RC1:1.6
	REL7_4_BETA5:1.6
	REL7_4_BETA4:1.6
	REL7_4_BETA3:1.6
	REL7_4_BETA2:1.6
	WIN32_DEV:1.6.0.2
	REL7_4_BETA1:1.6
	REL7_3_4:1.5
	REL7_3_2:1.5
	REL7_2_4:1.2
	REL7_3_STABLE:1.5.0.2
	REL7_2_3:1.2
	REL7_2_STABLE:1.2.0.2
	REL7_2:1.2
	REL7_2_RC2:1.2
	REL7_2_RC1:1.2
	REL7_2_BETA5:1.2
	REL7_2_BETA4:1.1
	REL7_2_BETA3:1.1
	REL7_2_BETA2:1.1
	REL7_2_BETA1:1.1;
locks; strict;
comment	@# @;


1.12
date	2007.11.10.23.30.46;	author momjian;	state dead;
branches;
next	1.11;

1.11
date	2007.05.17.21.43.19;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	2007.05.17.19.11.24;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	2006.09.02.17.05.29;	author momjian;	state Exp;
branches;
next	1.8;

1.8
date	2006.07.06.02.18.07;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	2006.02.27.16.09.49;	author petere;	state Exp;
branches;
next	1.6;

1.6
date	2003.06.12.08.02.53;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	2002.08.29.17.14.31;	author tgl;	state Exp;
branches;
next	1.4;

1.4
date	2002.08.23.08.19.49;	author ishii;	state Exp;
branches;
next	1.3;

1.3
date	2002.03.30.01.02.41;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2001.12.19.20.28.41;	author tgl;	state Exp;
branches;
next	1.1;

1.1
date	2001.10.01.01.52.38;	author ishii;	state Exp;
branches;
next	;


desc
@@


1.12
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@pgstattuple README			2002/08/29 Tatsuo Ishii

1. Functions supported:

    pgstattuple
    -----------
    pgstattuple() returns the relation length, percentage of the "dead"
    tuples of a relation 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 relation 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 %

    pg_relpages
    -----------
    pg_relpages() returns the number of pages in the relation.

    pgstatindex
    -----------
    pgstatindex() returns an array showing the information about an index:

        test=> \x
        Expanded display is on.
        test=> SELECT * FROM pgstatindex('pg_cast_oid_index');
        -[ RECORD 1 ]------+------
        version            | 2
        tree_level         | 0
        index_size         | 8192
        root_block_no      | 1
        internal_pages     | 0
        leaf_pages         | 1
        empty_pages        | 0
        deleted_pages      | 0
        avg_leaf_density   | 50.27
        leaf_fragmentation | 0


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 relation 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 relation name (optionally it may be qualified)
    or the OID of the relation.  Note that pgstattuple only returns
    one row.


4. Notes

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

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


5. History

    2007/05/17

	Moved page-level functions to contrib/pageinspect.

    2006/06/28

	Extended to work against indexes.
@


1.11
log
@Add CVS comment for recent commit:

        Moved page-level functions from pgstattuple to
contrib/pageinspect.
@
text
@@


1.10
log
@Add database page inspection /contrib module.

Simon and Heikki
@
text
@d98 1
a98 1
	Moved page-level functions to contrib/pageinspect
@


1.9
log
@Add functions to /contrib/pgstattuple that show index statistics and
index page contents.

Satoshi Nagayasu
@
text
@a58 47
    bt_metap
    --------
    bt_metap() returns information about the btree index metapage:

        test=> SELECT * FROM bt_metap('pg_cast_oid_index');
        -[ RECORD 1 ]-----
        magic     | 340322
        version   | 2
        root      | 1
        level     | 0
        fastroot  | 1
        fastlevel | 0

    bt_page_stats
    -------------
    bt_page_stats() shows information about single btree pages:

        test=> SELECT * FROM bt_page_stats('pg_cast_oid_index', 1);
        -[ RECORD 1 ]-+-----
        blkno         | 1
        type          | l
        live_items    | 256
        dead_items    | 0
        avg_item_size | 12
        page_size     | 8192
        free_size     | 4056
        btpo_prev     | 0
        btpo_next     | 0
        btpo          | 0
        btpo_flags    | 3

    bt_page_items
    -------------
    bt_page_items() returns information about specific items on btree pages:

        test=> SELECT * FROM bt_page_items('pg_cast_oid_index', 1);
         itemoffset |  ctid   | itemlen | nulls | vars |    data
        ------------+---------+---------+-------+------+-------------
                  1 | (0,1)   |      12 | f     | f    | 23 27 00 00
                  2 | (0,2)   |      12 | f     | f    | 24 27 00 00
                  3 | (0,3)   |      12 | f     | f    | 25 27 00 00
                  4 | (0,4)   |      12 | f     | f    | 26 27 00 00
                  5 | (0,5)   |      12 | f     | f    | 27 27 00 00
                  6 | (0,6)   |      12 | f     | f    | 28 27 00 00
                  7 | (0,7)   |      12 | f     | f    | 29 27 00 00
                  8 | (0,8)   |      12 | f     | f    | 2a 27 00 00

d96 4
@


1.8
log
@Add index information to /contrib/pgstattuple:

This is an extension of pgstattuple to query information from indexes.
It supports btree, hash and gist. Gin is not supported. It scans only
index pages and does not read corresponding heap tuples. Therefore,
'dead_tuple' means the number of tuples with LP_DELETE flag.

Also, I added an experimental feature for btree indexes. It checks
fragmentation factor of indexes. If an leaf has the right link on the
next adjacent page in the file, it is assumed to be continuous (not
fragmented). It will help us to decide when to REINDEX.

ITAGAKI Takahiro
@
text
@d3 102
a104 1
1. What is pgstattuple?
a105 29
   pgstattuple returns the relation length, percentage of the "dead"
   tuples of a relation 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 relation 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 %
d113 1
d116 2
a117 2
   pgstattuple may be called as a relation function and is
   defined as follows:
d119 1
a119 1
   CREATE OR REPLACE FUNCTION pgstattuple(text) RETURNS pgstattuple_type
d123 1
a123 1
   CREATE OR REPLACE FUNCTION pgstattuple(oid) RETURNS pgstattuple_type
d127 4
a130 3
   The argument is the relation name (optionally it may be qualified)
   or the OID of the relation.  Note that pgstattuple only returns
   one row.
d134 5
a138 2
   pgstattuple acquires only a read lock on the relation. So concurrent
   update may affect the result.
a139 2
   pgstattuple judges a tuple is "dead" if HeapTupleSatisfiesNow()
   returns false.
d143 1
a143 1
   2006/06/28
@


1.7
log
@Clean up CREATE FUNCTION syntax usage in contrib and elsewhere, in
particular get rid of single quotes around language names and old WITH ()
construct.
@
text
@d5 2
a6 2
   pgstattuple returns the table length, percentage of the "dead"
   tuples of a table and other info. This may help users to determine
d26 1
a26 1
table_len		-- physical table length in bytes
d43 1
a43 1
   pgstattuple may be called as a table function and is
d54 2
a55 2
   The argument is the table name (optionally it may be qualified)
   or the OID of the table.  Note that pgstattuple only returns
d60 1
a60 1
   pgstattuple acquires only a read lock on the table. So concurrent
d65 6
@


1.6
log
@New patch with corrected README attached.

Also quickly added mention that it may be a qualified schema name.

Rod Taylor
@
text
@d48 1
a48 1
     LANGUAGE 'c' STRICT;
d52 1
a52 1
     LANGUAGE 'c' STRICT;
@


1.5
log
@Adjust nodeFunctionscan.c to reset transient memory context between calls
to the table function, thus preventing memory leakage accumulation across
calls.  This means that SRFs need to be careful to distinguish permanent
and local storage; adjust code and documentation accordingly.  Patch by
Joe Conway, very minor tweaks by Tom Lane.
@
text
@d11 1
a11 1
test=# select * from pgstattuple('pg_proc');
d48 1
a48 1
     LANGUAGE 'c' WITH (isstrict);
d50 6
a55 1
   The argument is the table name.  Note that pgstattuple only returns
@


1.4
log
@Adapt for SRF(Set Returning Function).
@
text
@d1 1
a1 1
pgstattuple README			2002/08/22 Tatsuo Ishii
d43 1
a43 1
   pgstattuple may be called as a SRF (set returning function) and is
d46 1
a46 1
   CREATE OR REPLACE FUNCTION pgstattuple(text) RETURNS SETOF pgstattuple_view
d50 2
a51 2
   The argument is the table name.  Note that pgstattuple never
   returns more than 1 tuple.
@


1.3
log
@Further cleanups for relations in schemas: teach nextval and other
sequence functions how to cope with qualified names.  Same code is
also used for int4notin, currtid_byrelname, pgstattuple.  Also,
move TOAST tables into special pg_toast namespace.
@
text
@d1 1
a1 1
pgstattuple README			2001/10/01 Tatsuo Ishii
d5 29
a33 20
   pgstattuple returns the percentage of the "dead" tuples of a
   table. This will help users to judge if vacuum is needed.

   In addition, pgstattuple prints more detailed information using
   NOTICE.

test=# select pgstattuple('tellers');
NOTICE:  physical length: 0.08MB live tuples: 20 (0.00MB, 1.17%) dead tuples: 320 (0.01MB, 18.75%) free/reusable space: 0.01MB (18.06%) overhead: 62.02%
 pgstattuple 
-------------
       18.75
(1 row)

   Above example shows tellers table includes 18.75% dead tuples.

   physical length	physical size of the table in MB
   live tuples		information on the live tuples
   dead tuples		information on the dead tuples
   free/reusable space	available space
   overhead		overhead space
d43 2
a44 1
   pgstattuple can be called as a function:
d46 3
a48 1
   pgstattuple(TEXT) RETURNS FLOAT8
d50 2
a51 2
   The argument is the table name.  pgstattuple returns the percentage
   of the "dead" tuples of a table.
@


1.2
log
@Fix pgstattuple to acquire a read lock on the target table.  This
prevents embarassments such as having the table dropped or truncated
partway through the scan.  Also, fix free space calculation to include
pages that currently contain no tuples.
@
text
@d36 1
a36 1
   pgstattuple(NAME) RETURNS FLOAT8
@


1.1
log
@Add pgstattuple
@
text
@d18 1
a18 1
   Above example shows tellers tables includes 18.75% dead tuples.
d43 1
a43 1
   pgstattuple does not lock the target table at all. So concurrent
@
