head	1.6;
access;
symbols
	REL8_2_17:1.5
	REL8_2_16:1.5
	REL8_2_15:1.5
	REL8_2_14:1.5
	REL8_2_13:1.5
	REL8_2_12:1.5
	REL8_2_11:1.5
	REL8_2_10:1.5
	REL8_2_9:1.5
	REL8_2_8:1.5
	REL8_2_7:1.5
	REL8_2_6:1.5
	REL8_3_BETA2:1.5
	REL8_3_BETA1:1.5
	REL8_2_5:1.5
	REL8_2_4:1.5
	REL8_2_3:1.5
	REL8_2_2:1.5
	REL8_2_1:1.5
	REL8_2_STABLE:1.5.0.2
	REL8_2_0:1.5
	REL8_2_RC1:1.5
	REL8_2_BETA3:1.5
	REL8_2_BETA2:1.5
	REL8_2_BETA1:1.5;
locks; strict;
comment	@# @;


1.6
date	2007.11.10.23.30.45;	author momjian;	state dead;
branches;
next	1.5;

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

1.4
date	2006.05.04.20.39.34;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2006.04.26.22.46.09;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	2006.04.26.22.41.18;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2006.02.12.03.55.53;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.6
log
@Move most /contrib README files into SGML.  Some still need conversion
or will never be converted.
@
text
@Pg_freespacemap - Real time queries on the free space map (FSM).
---------------

  This module consists of two C functions: 'pg_freespacemap_relations()' and
  'pg_freespacemap_pages()' that return a set of records, plus two views 
  'pg_freespacemap_relations' and 'pg_freespacemap_pages' for more
  user-friendly access to the functions.

  The module provides the ability to examine the contents of the free space
  map, without having to restart or rebuild the server with additional
  debugging code.

  By default public access is REVOKED from the functions and views, just in 
  case there are security issues present in the code.


Installation
------------

  Build and install the main Postgresql source, then this contrib module:

  $ cd contrib/pg_freespacemap
  $ gmake
  $ gmake install


  To register the functions and views:

  $ psql -d <database> -f pg_freespacemap.sql


Notes
-----

  The definitions for the columns exposed in the views are:

   pg_freespacemap_relations

       Column       |  references          | Description
  ------------------+----------------------+----------------------------------
   reltablespace    | pg_tablespace.oid    | Tablespace oid of the relation.
   reldatabase      | pg_database.oid      | Database oid of the relation.
   relfilenode      | pg_class.relfilenode | Relfilenode of the relation.
   avgrequest       |                      | Moving average of free space 
                    |                      | requests (NULL for indexes)
   interestingpages |                      | Count of pages last reported as
                    |                      | containing useful free space.
   storedpages      |                      | Count of pages actually stored
                    |                      | in free space map.
   nextpage         |                      | Page index (from 0) to start next 
                    |                      | search at.


   pg_freespacemap_pages

       Column     |  references          | Description
  ----------------+----------------------+------------------------------------
   reltablespace  | pg_tablespace.oid    | Tablespace oid of the relation.
   reldatabase    | pg_database.oid      | Database oid of the relation.
   relfilenode    | pg_class.relfilenode | Relfilenode of the relation.
   relblocknumber |                      | Page number in the relation.
   bytes          |                      | Free bytes in the page, or NULL
                  |                      | for an index page (see below).


  For pg_freespacemap_relations, there is one row for each relation in the free
  space map.  storedpages is the number of pages actually stored in the map,
  while interestingpages is the number of pages the last VACUUM thought had
  useful amounts of free space.

  If storedpages is consistently less than interestingpages then it'd be a
  good idea to increase max_fsm_pages.  Also, if the number of rows in
  pg_freespacemap_relations is close to max_fsm_relations, then you should
  consider increasing max_fsm_relations.

  For pg_freespacemap_pages, there is one row for each page in the free space 
  map.  The number of rows for a relation will match the storedpages column
  in pg_freespacemap_relations.

  For indexes, what is tracked is entirely-unused pages, rather than free
  space within pages.  Therefore, the average request size and free bytes
  within a page are not meaningful, and are shown as NULL.

  Because the map is shared by all the databases, it will include relations
  not belonging to the current database.

  When either of the views are accessed, internal free space map locks are
  taken, and a copy of the map data is made for them to display. 
  This ensures that the views produce a consistent set of results, while not 
  blocking normal activity longer than necessary.  Nonetheless there 
  could be some impact on database performance if they are read often.


Sample output - pg_freespacemap_relations
-------------

regression=# \d pg_freespacemap_relations
View "public.pg_freespacemap_relations"
    Column        |  Type   | Modifiers
------------------+---------+-----------
 reltablespace    | oid     |
 reldatabase      | oid     |
 relfilenode      | oid     |
 avgrequest       | integer |
 interestingpages | integer |
 storedpages      | integer |
 nextpage         | integer |
View definition:
 SELECT p.reltablespace, p.reldatabase, p.relfilenode, p.avgrequest, p.interestingpages, p.storedpages, p.nextpage
   FROM pg_freespacemap_relations() p(reltablespace oid, reldatabase oid, relfilenode oid, avgrequest integer, interestingpages integer, storedpages integer, nextpage integer);

regression=# SELECT c.relname, r.avgrequest, r.interestingpages, r.storedpages
             FROM pg_freespacemap_relations r INNER JOIN pg_class c
             ON c.relfilenode = r.relfilenode INNER JOIN pg_database d
             ON r.reldatabase = d.oid AND (d.datname = current_database()) 
             ORDER BY r.storedpages DESC LIMIT 10;
             relname             | avgrequest | interestingpages | storedpages
---------------------------------+------------+------------------+-------------
 onek                            |        256 |              109 |         109
 pg_attribute                    |        167 |               93 |          93
 pg_class                        |        191 |               49 |          49
 pg_attribute_relid_attnam_index |            |               48 |          48
 onek2                           |        256 |               37 |          37
 pg_depend                       |         95 |               26 |          26
 pg_type                         |        199 |               16 |          16
 pg_rewrite                      |       1011 |               13 |          13
 pg_class_relname_nsp_index      |            |               10 |          10
 pg_proc                         |        302 |                8 |           8
(10 rows)


Sample output - pg_freespacemap_pages
-------------

regression=# \d pg_freespacemap_pages
 View "public.pg_freespacemap_pages"
     Column     |  Type   | Modifiers 
----------------+---------+-----------
 reltablespace  | oid     | 
 reldatabase    | oid     | 
 relfilenode    | oid     | 
 relblocknumber | bigint  | 
 bytes          | integer | 
View definition:
 SELECT p.reltablespace, p.reldatabase, p.relfilenode, p.relblocknumber, p.bytes
   FROM pg_freespacemap_pages() p(reltablespace oid, reldatabase oid, relfilenode oid, relblocknumber bigint, bytes integer);

regression=# SELECT c.relname, p.relblocknumber, p.bytes
             FROM pg_freespacemap_pages p INNER JOIN pg_class c
             ON c.relfilenode = p.relfilenode INNER JOIN pg_database d
             ON (p.reldatabase = d.oid AND d.datname = current_database()) 
             ORDER BY c.relname LIMIT 10;
   relname    | relblocknumber | bytes 
--------------+----------------+-------
 a_star       |              0 |  8040
 abstime_tbl  |              0 |  7908
 aggtest      |              0 |  8008
 altinhoid    |              0 |  8128
 altstartwith |              0 |  8128
 arrtest      |              0 |  7172
 b_star       |              0 |  7976
 box_tbl      |              0 |  7912
 bt_f8_heap   |             54 |  7728
 bt_i4_heap   |             49 |  8008
(10 rows)



Author
------

  * Mark Kirkwood <markir@@paradise.net.nz>

@


1.5
log
@Fix free space map to correctly track the total amount of FSM space needed
even when a single relation requires more than max_fsm_pages pages.  Also,
make VACUUM emit a warning in this case, since it likely means that VACUUM
FULL or other drastic corrective measure is needed.  Per reports from Jeff
Frost and others of unexpected changes in the claimed max_fsm_pages need.
@
text
@@


1.4
log
@Code review for contrib/pg_freespacemap.  Add a storedpages column to
pg_freespacemap_relations --- while one could theoretically get that
number by counting rows in pg_freespacemap_pages, it's surely the hard
way to do it.  Avoid expensive and inconvenient conversion to and from
text format.  Minor code and docs cleanup.
@
text
@d39 13
a51 13
       Column     |  references          | Description
  ----------------+----------------------+------------------------------------
   reltablespace  | pg_tablespace.oid    | Tablespace oid of the relation.
   reldatabase    | pg_database.oid      | Database oid of the relation.
   relfilenode    | pg_class.relfilenode | Relfilenode of the relation.
   avgrequest     |                      | Moving average of free space 
                  |                      | requests (NULL for indexes)
   lastpagecount  |                      | Count of pages last reported as
                  |                      | containing useful free space.
   storedpages    |                      | Count of pages actually stored
                  |                      | in free space map.
   nextpage       |                      | Page index (from 0) to start next 
                  |                      | search at.
d68 2
a69 2
  while lastpagecount is the number of pages VACUUM last tried to store
  (ie, the number that VACUUM thought had useful amounts of free space).
d71 2
a72 2
  If storedpages is consistently less than lastpagecount then it'd be a good
  idea to increase max_fsm_pages.  Also, if the number of rows in
d99 9
a107 9
    Column     |  Type   | Modifiers
---------------+---------+-----------
 reltablespace | oid     |
 reldatabase   | oid     |
 relfilenode   | oid     |
 avgrequest    | integer |
 lastpagecount | integer |
 storedpages   | integer |
 nextpage      | integer |
d109 2
a110 2
 SELECT p.reltablespace, p.reldatabase, p.relfilenode, p.avgrequest, p.lastpagecount, p.storedpages, p.nextpage
   FROM pg_freespacemap_relations() p(reltablespace oid, reldatabase oid, relfilenode oid, avgrequest integer, lastpagecount integer, storedpages integer, nextpage integer);
d112 1
a112 1
regression=# SELECT c.relname, r.avgrequest, r.lastpagecount, r.storedpages
d117 12
a128 12
             relname             | avgrequest | lastpagecount | storedpages
---------------------------------+------------+---------------+-------------
 onek                            |        256 |           109 |         109
 pg_attribute                    |        167 |            93 |          93
 pg_class                        |        191 |            49 |          49
 pg_attribute_relid_attnam_index |            |            48 |          48
 onek2                           |        256 |            37 |          37
 pg_depend                       |         95 |            26 |          26
 pg_type                         |        199 |            16 |          16
 pg_rewrite                      |       1011 |            13 |          13
 pg_class_relname_nsp_index      |            |            10 |          10
 pg_proc                         |        302 |             8 |           8
@


1.3
log
@Split out pg_freespace views to one for relations and another for pages,
pg_freespacemap_relations and pg_freespacemap_pages.

Mark Kirkwood
@
text
@d42 2
a43 2
   reldatabase    | pg_database.oid      | Database for the relation.
   relfilenode    | pg_class.relfilenode | Refilenode of the relation.
d45 6
a50 4
                  |                      | requests.
   lastpagecount  |                      | Count of pages examined for useful
                  |                      | free space.
   nextpage       |                      | page index (from 0) to start next 
d59 3
a61 3
   reldatabase    | pg_database.oid      | Database for the relation.
   relfilenode    | pg_class.relfilenode | Refilenode of the relation.
   relblocknumber |                      | Page offset in the relation.
d67 8
a74 1
  space map.
d77 2
a78 1
  map.
d80 3
a82 2
  Because the map is shared by all the databases, there are relations and pages
  from relations not belonging to the current database.
d84 2
a85 2
  The view 'freespacemap_pages'  can contain pages for btree indexes if they 
  were emptied by a vacuum process. The bytes field is set to NULL in this case.
d99 1
a99 1
    Column     |  Type   | Modifiers 
d101 7
a107 6
 reltablespace | oid     | 
 reldatabase   | oid     | 
 relfilenode   | oid     | 
 avgrequest    | bigint  | 
 lastpagecount | integer | 
 nextpage      | integer | 
d109 2
a110 2
 SELECT p.reltablespace, p.reldatabase, p.relfilenode, p.avgrequest, p.lastpagecount, p.nextpage
   FROM pg_freespacemap_relations() p(reltablespace oid, reldatabase oid, relfilenode oid, avgrequest bigint, lastpagecount integer, nextpage integer);
d112 1
a112 1
regression=# SELECT c.relname, r.avgrequest, r.lastpagecount, r.nextpage
d116 13
a128 13
             ORDER BY c.relname LIMIT 10;
   relname    | avgrequest | lastpagecount | nextpage 
--------------+------------+---------------+----------
 a_star       |        250 |             1 |        0
 abstime_tbl  |        249 |             1 |        0
 aggtest      |        250 |             1 |        0
 altinhoid    |        250 |             1 |        0
 altstartwith |        250 |             1 |        0
 arrtest      |        254 |             1 |        0
 b_star       |        250 |             1 |        0
 box_tbl      |        250 |             1 |        0
 bt_f8_heap   |         92 |             1 |        0
 bt_i4_heap   |         94 |             1 |        0
a130 2
regression=# 

d135 1
a135 1
regression=# \d pg_freespacemap_pages;
a166 2
regression=# 

@


1.2
log
@Adjust /contrib/pg_freespace to show index free space as NULL (FSM only
tracks index pages, not free space on pages):

1/ Index free bytes set to NULL
2/ Comment added to the README briefly mentioning the index business
3/ Columns reordered more logically
4/ 'Blockid' column removed
5/ Free bytes column renamed to just 'bytes' instead of 'blockfreebytes'

Mark Kirkwood
@
text
@d4 4
a7 2
  This module consists of a C function 'pg_freespacemap()' that returns 
  a set of records, and a view 'pg_freespacemap' to wrapper the function.
d13 2
a14 2
  By default public access is REVOKED from both of these, just in case there
  are security issues lurking.
d27 1
a27 1
  To register the functions:
d35 18
a52 1
  The definition of the columns exposed in the view is:
d59 2
a60 2
   relblocknumber |                      | Offset of the page in the relation.
   bytes          |                      | Free bytes in the block/page, or NULL
d64 5
a68 1
  There is one row for each page in the free space map.
d70 2
a71 2
  Because the map is shared by all the databases, there are pages from
  relations not belonging to the current database.
d73 2
a74 2
  The free space map can contain pages for btree indexes if they were emptied 
  by a vacuum process. The bytes field is set to NULL in this case.
d76 3
a78 3
  When the pg_freespacemap view is accessed, internal free space map locks are
  taken, and a copy of the map data is made for the view to display. 
  This ensures that the view produces a consistent set of results, while not 
d80 38
a117 1
  could be some impact on database performance if this view is read often.
d119 1
d121 2
a122 1
Sample output
d125 10
a134 10
  regression=# \d pg_freespacemap
     View "public.pg_freespacemap"
      Column     |  Type   | Modifiers 
 ----------------+---------+-----------
  reltablespace  | oid     | 
  reldatabase    | oid     | 
  relfilenode    | oid     | 
  relblocknumber | bigint  | 
  bytes          | integer | 
 View definition:
d136 20
a155 1
 FROM pg_freespacemap() p(reltablespace oid, reldatabase oid, relfilenode oid, relblocknumber bigint, bytes integer);
d157 1
a157 16
  regression=# SELECT c.relname, m.relblocknumber, m.bytes  
               FROM pg_freespacemap m INNER JOIN pg_class c 
               ON c.relfilenode = m.relfilenode LIMIT 10;
      relname             | relblocknumber |  bytes 
  ------------------------+----------------+--------
  sql_features            |              5 |   2696
  sql_implementation_info |              0 |   7104
  sql_languages           |              0 |   8016
  sql_packages            |              0 |   7376
  sql_sizing              |              0 |   6032
  pg_authid               |              0 |   7424
  pg_toast_2618           |             13 |   4588
  pg_toast_2618           |             12 |   1680
  pg_toast_2618           |             10 |   1436
  pg_toast_2618           |              7 |   1136
  (10 rows)
a158 1
  regression=# 
@


1.1
log
@Add contrib/pg_freespacemap to display free space map information.

Mark Kirkwood
@
text
@a36 2
   blockid        |                      | Id, 1.. max_fsm_pages
   relfilenode    | pg_class.relfilenode | Refilenode of the relation.
d39 1
d41 2
a42 1
   blockfreebytes |                      | Free bytes in the block/page.
d50 3
d64 1
a64 1
      View "public.pg_freespacemap"
d66 1
a66 3
  ---------------+---------+-----------
  blockid        | integer | 
  relfilenode    | oid     | 
d69 1
d71 1
a71 1
  blockfreebytes | integer | 
d73 2
a74 2
  SELECT p.blockid, p.relfilenode, p.reltablespace, p.reldatabase, p.relblocknumber, p.blockfreebytes
    FROM pg_freespacemap() p(blockid integer, relfilenode oid, reltablespace oid, reldatabase oid, relblocknumber bigint, blockfreebytes integer);
d76 1
a76 1
  regression=# SELECT c.relname, m.relblocknumber, m.blockfreebytes  
d79 12
a90 12
      relname             | relblocknumber | blockfreebytes 
  ------------------------+----------------+----------------
  sql_features            |              5 |           2696
  sql_implementation_info |              0 |           7104
  sql_languages           |              0 |           8016
  sql_packages            |              0 |           7376
  sql_sizing              |              0 |           6032
  pg_authid               |              0 |           7424
  pg_toast_2618           |             13 |           4588
  pg_toast_2618           |             12 |           1680
  pg_toast_2618           |             10 |           1436
  pg_toast_2618           |              7 |           1136
@

