2010-09-20 22:08:53 +02:00
|
|
|
<!-- doc/src/sgml/pgfreespacemap.sgml -->
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2011-05-08 04:29:20 +02:00
|
|
|
<sect1 id="pgfreespacemap" xreflabel="pg_freespacemap">
|
2007-12-02 23:33:20 +01:00
|
|
|
<title>pg_freespacemap</title>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<indexterm zone="pgfreespacemap">
|
2007-12-02 23:33:20 +01:00
|
|
|
<primary>pg_freespacemap</primary>
|
2007-11-11 00:30:46 +01:00
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
The <filename>pg_freespacemap</filename> module provides a means for examining the
|
2022-03-09 02:43:25 +01:00
|
|
|
<link linkend="storage-fsm">free space map</link> (<acronym>FSM</acronym>).
|
|
|
|
It provides a function called <function>pg_freespace</function>, or two
|
|
|
|
overloaded functions, to be precise. The functions show the value recorded in
|
|
|
|
the free space map for a given page, or for all pages in the relation.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2022-03-28 21:10:04 +02:00
|
|
|
By default use is restricted to superusers and roles with privileges of the
|
2017-03-30 20:18:53 +02:00
|
|
|
<literal>pg_stat_scan_tables</literal> role. Access may be granted to others
|
|
|
|
using <command>GRANT</command>.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<sect2>
|
2008-09-30 12:52:14 +02:00
|
|
|
<title>Functions</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
2008-10-02 12:26:51 +02:00
|
|
|
<function>pg_freespace(rel regclass IN, blkno bigint IN) returns int2</function>
|
2014-05-07 03:28:58 +02:00
|
|
|
<indexterm>
|
|
|
|
<primary>pg_freespace</primary>
|
|
|
|
</indexterm>
|
2008-09-30 12:52:14 +02:00
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Returns the amount of free space on the page of the relation, specified
|
2022-03-09 02:43:25 +01:00
|
|
|
by <literal>blkno</literal>, according to the <acronym>FSM</acronym>.
|
2008-09-30 12:52:14 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
2008-10-02 14:20:50 +02:00
|
|
|
<function>pg_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2)</function>
|
2008-09-30 12:52:14 +02:00
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-04-24 01:21:44 +02:00
|
|
|
Displays the amount of free space on each page of the relation,
|
2022-03-09 02:43:25 +01:00
|
|
|
according to the <acronym>FSM</acronym>. A set of
|
|
|
|
<literal>(blkno bigint, avail int2)</literal>
|
2008-09-30 12:52:14 +02:00
|
|
|
tuples is returned, one tuple for each page in the relation.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2008-09-30 12:52:14 +02:00
|
|
|
The values stored in the free space map are not exact. They're rounded
|
2017-10-09 03:44:17 +02:00
|
|
|
to precision of 1/256th of <symbol>BLCKSZ</symbol> (32 bytes with default <symbol>BLCKSZ</symbol>), and
|
2008-09-30 12:52:14 +02:00
|
|
|
they're not kept fully up-to-date as tuples are inserted and updated.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
|
|
|
For indexes, what is tracked is entirely-unused pages, rather than free
|
2008-09-30 12:52:14 +02:00
|
|
|
space within pages. Therefore, the values are not meaningful, just
|
|
|
|
whether a page is full or empty.
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Sample Output</title>
|
2007-11-11 00:30:46 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2008-09-30 12:52:14 +02:00
|
|
|
postgres=# SELECT * FROM pg_freespace('foo');
|
|
|
|
blkno | avail
|
|
|
|
-------+-------
|
|
|
|
0 | 0
|
|
|
|
1 | 0
|
|
|
|
2 | 0
|
|
|
|
3 | 32
|
|
|
|
4 | 704
|
|
|
|
5 | 704
|
|
|
|
6 | 704
|
|
|
|
7 | 1216
|
|
|
|
8 | 704
|
|
|
|
9 | 704
|
|
|
|
10 | 704
|
|
|
|
11 | 704
|
|
|
|
12 | 704
|
|
|
|
13 | 704
|
|
|
|
14 | 704
|
|
|
|
15 | 704
|
|
|
|
16 | 704
|
|
|
|
17 | 704
|
|
|
|
18 | 704
|
|
|
|
19 | 3648
|
|
|
|
(20 rows)
|
|
|
|
|
|
|
|
postgres=# SELECT * FROM pg_freespace('foo', 7);
|
|
|
|
pg_freespace
|
|
|
|
--------------
|
|
|
|
1216
|
|
|
|
(1 row)
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2>
|
|
|
|
<title>Author</title>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
<para>
|
2008-09-30 12:52:14 +02:00
|
|
|
Original version by Mark Kirkwood <email>markir@paradise.net.nz</email>.
|
2022-03-09 02:43:25 +01:00
|
|
|
Rewritten in version 8.4 to suit new <acronym>FSM</acronym> implementation
|
|
|
|
by Heikki Linnakangas <email>heikki@enterprisedb.com</email>
|
2007-11-11 00:30:46 +01:00
|
|
|
</para>
|
|
|
|
</sect2>
|
2007-12-10 06:32:51 +01:00
|
|
|
|
2007-11-11 00:30:46 +01:00
|
|
|
</sect1>
|