<primary>unnest</primary>
<secondary>for tsvector</secondary>
</indexterm>
- <function>unnest</function> ( <type>tsvector</type>,
- <literal>OUT</literal> <replaceable>lexeme</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>positions</replaceable> <type>smallint[]</type>,
- <literal>OUT</literal> <replaceable>weights</replaceable> <type>text</type> )
+ <function>unnest</function> ( <type>tsvector</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>lexeme</replaceable> <type>text</type>,
+ <replaceable>positions</replaceable> <type>smallint[]</type>,
+ <replaceable>weights</replaceable> <type>text</type> )
</para>
<para>
Expands a <type>tsvector</type> into a set of rows, one per lexeme.
</indexterm>
<function>ts_debug</function> (
<optional> <replaceable>config</replaceable> <type>regconfig</type>, </optional>
- <replaceable>document</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>dictionaries</replaceable> <type>regdictionary[]</type>,
- <literal>OUT</literal> <replaceable>dictionary</replaceable> <type>regdictionary</type>,
- <literal>OUT</literal> <replaceable>lexemes</replaceable> <type>text[]</type> )
+ <replaceable>document</replaceable> <type>text</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>alias</replaceable> <type>text</type>,
+ <replaceable>description</replaceable> <type>text</type>,
+ <replaceable>token</replaceable> <type>text</type>,
+ <replaceable>dictionaries</replaceable> <type>regdictionary[]</type>,
+ <replaceable>dictionary</replaceable> <type>regdictionary</type>,
+ <replaceable>lexemes</replaceable> <type>text[]</type> )
</para>
<para>
Extracts and normalizes tokens from
<primary>ts_parse</primary>
</indexterm>
<function>ts_parse</function> ( <replaceable>parser_name</replaceable> <type>text</type>,
- <replaceable>document</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
- <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type> )
+ <replaceable>document</replaceable> <type>text</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>tokid</replaceable> <type>integer</type>,
+ <replaceable>token</replaceable> <type>text</type> )
</para>
<para>
Extracts tokens from the <replaceable>document</replaceable> using the
<row>
<entry role="func_table_entry"><para role="func_signature">
<function>ts_parse</function> ( <replaceable>parser_oid</replaceable> <type>oid</type>,
- <replaceable>document</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
- <literal>OUT</literal> <replaceable>token</replaceable> <type>text</type> )
+ <replaceable>document</replaceable> <type>text</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>tokid</replaceable> <type>integer</type>,
+ <replaceable>token</replaceable> <type>text</type> )
</para>
<para>
Extracts tokens from the <replaceable>document</replaceable> using a
<indexterm>
<primary>ts_token_type</primary>
</indexterm>
- <function>ts_token_type</function> ( <replaceable>parser_name</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
- <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type> )
+ <function>ts_token_type</function> ( <replaceable>parser_name</replaceable> <type>text</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>tokid</replaceable> <type>integer</type>,
+ <replaceable>alias</replaceable> <type>text</type>,
+ <replaceable>description</replaceable> <type>text</type> )
</para>
<para>
Returns a table that describes each type of token the named parser can
<row>
<entry role="func_table_entry"><para role="func_signature">
- <function>ts_token_type</function> ( <replaceable>parser_oid</replaceable> <type>oid</type>,
- <literal>OUT</literal> <replaceable>tokid</replaceable> <type>integer</type>,
- <literal>OUT</literal> <replaceable>alias</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>description</replaceable> <type>text</type> )
+ <function>ts_token_type</function> ( <replaceable>parser_oid</replaceable> <type>oid</type> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>tokid</replaceable> <type>integer</type>,
+ <replaceable>alias</replaceable> <type>text</type>,
+ <replaceable>description</replaceable> <type>text</type> )
</para>
<para>
Returns a table that describes each type of token a parser specified
<indexterm>
<primary>ts_stat</primary>
</indexterm>
- <function>ts_stat</function> ( <replaceable>sqlquery</replaceable> <type>text</type>,
- <optional> <replaceable>weights</replaceable> <type>text</type>, </optional>
- <literal>OUT</literal> <replaceable>word</replaceable> <type>text</type>,
- <literal>OUT</literal> <replaceable>ndoc</replaceable> <type>integer</type>,
- <literal>OUT</literal> <replaceable>nentry</replaceable> <type>integer</type> )
+ <function>ts_stat</function> ( <replaceable>sqlquery</replaceable> <type>text</type>
+ <optional>, <replaceable>weights</replaceable> <type>text</type> </optional> )
<returnvalue>setof record</returnvalue>
+ ( <replaceable>word</replaceable> <type>text</type>,
+ <replaceable>ndoc</replaceable> <type>integer</type>,
+ <replaceable>nentry</replaceable> <type>integer</type> )
</para>
<para>
Executes the <replaceable>sqlquery</replaceable>, which must return a
<para>
In addition to these functions, any built-in or user-defined
- general-purpose or statistical
- aggregate (i.e., not ordered-set or hypothetical-set aggregates)
+ ordinary aggregate (i.e., not ordered-set or hypothetical-set aggregates)
can be used as a window function; see
<xref linkend="functions-aggregate"/> for a list of the built-in aggregates.
Aggregate functions act as window functions only when an <literal>OVER</literal>
- clause follows the call; otherwise they act as non-window aggregates
+ clause follows the call; otherwise they act as plain aggregates
and return a single row for the entire set.
</para>
- <table id="functions-window-table">
- <title>General-Purpose Window Functions</title>
-
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <table id="functions-window-table">
+ <title>General-Purpose Window Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry>
- <indexterm>
- <primary>row_number</primary>
- </indexterm>
- <function>row_number()</function>
- </entry>
- <entry>
- <type>bigint</type>
- </entry>
- <entry>number of the current row within its partition, counting from 1</entry>
- </row>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>row_number</primary>
+ </indexterm>
+ <function>row_number</function> ()
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Returns the number of the current row within its partition, counting
+ from 1.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>rank</primary>
- </indexterm>
- <function>rank()</function>
- </entry>
- <entry>
- <type>bigint</type>
- </entry>
- <entry>rank of the current row with gaps; same as <function>row_number</function> of its first peer</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>rank</primary>
+ </indexterm>
+ <function>rank</function> ()
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Returns the rank of the current row, with gaps; that is,
+ the <function>row_number</function> of the first row in its peer
+ group.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>dense_rank</primary>
- </indexterm>
- <function>dense_rank()</function>
- </entry>
- <entry>
- <type>bigint</type>
- </entry>
- <entry>rank of the current row without gaps; this function counts peer groups</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>dense_rank</primary>
+ </indexterm>
+ <function>dense_rank</function> ()
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Returns the rank of the current row, without gaps; this function
+ effectively counts peer groups.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>percent_rank</primary>
- </indexterm>
- <function>percent_rank()</function>
- </entry>
- <entry>
- <type>double precision</type>
- </entry>
- <entry>relative rank of the current row: (<function>rank</function> - 1) / (total partition rows - 1)</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>percent_rank</primary>
+ </indexterm>
+ <function>percent_rank</function> ()
+ <returnvalue>double precision</returnvalue>
+ </para>
+ <para>
+ Returns the relative rank of the current row, that is
+ (<function>rank</function> - 1) / (total partition rows - 1).
+ The value thus ranges from 0 to 1 inclusive.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>cume_dist</primary>
- </indexterm>
- <function>cume_dist()</function>
- </entry>
- <entry>
- <type>double precision</type>
- </entry>
- <entry>cumulative distribution: (number of partition rows preceding or peer with current row) / total partition rows</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>cume_dist</primary>
+ </indexterm>
+ <function>cume_dist</function> ()
+ <returnvalue>double precision</returnvalue>
+ </para>
+ <para>
+ Returns the cumulative distribution, that is (number of partition rows
+ preceding or peers with current row) / (total partition rows).
+ The value thus ranges from 1/<replaceable>N</replaceable> to 1.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>ntile</primary>
- </indexterm>
- <function>ntile(<replaceable class="parameter">num_buckets</replaceable> <type>integer</type>)</function>
- </entry>
- <entry>
- <type>integer</type>
- </entry>
- <entry>integer ranging from 1 to the argument value, dividing the
- partition as equally as possible</entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+
<primary>ntile</primary>
+ </indexterm>
+ <function>ntile</function> ( <replaceable>num_buckets</replaceable> <type>integer</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns an integer ranging from 1 to the argument value, dividing the
+ partition as equally as possible.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>lag</primary>
- </indexterm>
- <function>
- lag(<replaceable class="parameter">value</replaceable> <type>anyelement</type>
- [, <replaceable class="parameter">offset</replaceable> <type>integer</type>
- [, <replaceable class="parameter">default</replaceable> <type>anyelement</type> ]])
- </function>
- </entry>
- <entry>
- <type>same type as <replaceable class="parameter">value</replaceable></type>
- </entry>
- <entry>
- returns <replaceable class="parameter">value</replaceable> evaluated at
- the row that is <replaceable class="parameter">offset</replaceable>
- rows before the current row within the partition; if there is no such
- row, instead return <replaceable class="parameter">default</replaceable>
- (which must be of the same type as
- <replaceable class="parameter">value</replaceable>).
- Both <replaceable class="parameter">offset</replaceable> and
- <replaceable class="parameter">default</replaceable> are evaluated
- with respect to the current row. If omitted,
- <replaceable class="parameter">offset</replaceable> defaults to 1 and
- <replaceable class="parameter">default</replaceable> to null
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>lag</primary>
+ </indexterm>
+ <function>lag</function> ( <replaceable>value</replaceable> <type>anyelement</type>
+ <optional>, <replaceable>offset</replaceable> <type>integer</type>
+ <optional>, <replaceable>default</replaceable> <type>anyelement</type> </optional></optional> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Returns <replaceable>value</replaceable> evaluated at
+ the row that is <replaceable>offset</replaceable>
+ rows before the current row within the partition; if there is no such
+ row, instead returns <replaceable>default</replaceable>
+ (which must be of the same type as
+ <replaceable>value</replaceable>).
+ Both <replaceable>offset</replaceable> and
+ <replaceable>default</replaceable> are evaluated
+ with respect to the current row. If omitted,
+ <replaceable>offset</replaceable> defaults to 1 and
+ <replaceable>default</replaceable> to <literal>NULL</literal>.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>lead</primary>
- </indexterm>
- <function>
- lead(<replaceable class="parameter">value</replaceable> <type>anyelement</type>
- [, <replaceable class="parameter">offset</replaceable> <type>integer</type>
- [, <replaceable class="parameter">default</replaceable> <type>anyelement</type> ]])
- </function>
- </entry>
- <entry>
- <type>same type as <replaceable class="parameter">value</replaceable></type>
- </entry>
- <entry>
- returns <replaceable class="parameter">value</replaceable> evaluated at
- the row that is <replaceable class="parameter">offset</replaceable>
- rows after the current row within the partition; if there is no such
- row, instead return <replaceable class="parameter">default</replaceable>
- (which must be of the same type as
- <replaceable class="parameter">value</replaceable>).
- Both <replaceable class="parameter">offset</replaceable> and
- <replaceable class="parameter">default</replaceable> are evaluated
- with respect to the current row. If omitted,
- <replaceable class="parameter">offset</replaceable> defaults to 1 and
- <replaceable class="parameter">default</replaceable> to null
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>lead</primary>
+ </indexterm>
+ <function>lead</function> ( <replaceable>value</replaceable> <type>anyelement</type>
+ <optional>, <replaceable>offset</replaceable> <type>integer</type>
+ <optional>, <replaceable>default</replaceable> <type>anyelement</type> </optional></optional> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Returns <replaceable>value</replaceable> evaluated at
+ the row that is <replaceable>offset</replaceable>
+ rows after the current row within the partition; if there is no such
+ row, instead returns <replaceable>default</replaceable>
+ (which must be of the same type as
+ <replaceable>value</replaceable>).
+ Both <replaceable>offset</replaceable> and
+ <replaceable>default</replaceable> are evaluated
+ with respect to the current row. If omitted,
+ <replaceable>offset</replaceable> defaults to 1 and
+ <replaceable>default</replaceable> to <literal>NULL</literal>.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>first_value</primary>
- </indexterm>
- <function>first_value(<replaceable class="parameter">value</replaceable> <type>any</type>)</function>
- </entry>
- <entry>
- <type>same type as <replaceable class="parameter">value</replaceable></type>
- </entry>
- <entry>
- returns <replaceable class="parameter">value</replaceable> evaluated
- at the row that is the first row of the window frame
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>first_value</primary>
+ </indexterm>
+ <function>first_value</function> ( <replaceable>value</replaceable> <type>anyelement</type> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Returns <replaceable>value</replaceable> evaluated
+ at the row that is the first row of the window frame.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>last_value</primary>
- </indexterm>
- <function>last_value(<replaceable class="parameter">value</replaceable> <type>any</type>)</function>
- </entry>
- <entry>
- <type>same type as <replaceable class="parameter">value</replaceable></type>
- </entry>
- <entry>
- returns <replaceable class="parameter">value</replaceable> evaluated
- at the row that is the last row of the window frame
- </entry>
- </row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>last_value</primary>
+ </indexterm>
+ <function>last_value</function> ( <replaceable>value</replaceable> <type>anyelement</type> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Returns <replaceable>value</replaceable> evaluated
+ at the row that is the last row of the window frame.
+ </para></entry>
+ </row>
- <row>
- <entry>
- <indexterm>
- <primary>nth_value</primary>
- </indexterm>
- <function>
- nth_value(<replaceable class="parameter">value</replaceable> <type>any</type>, <replaceable class="parameter">nth</replaceable> <type>integer</type>)
- </function>
- </entry>
- <entry>
- <type>same type as <replaceable class="parameter">value</replaceable></type>
- </entry>
- <entry>
- returns <replaceable class="parameter">value</replaceable> evaluated
- at the row that is the <replaceable class="parameter">nth</replaceable>
- row of the window frame (counting from 1); null if no such row
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>nth_value</primary>
+ </indexterm>
+ <function>nth_value</function> ( <replaceable>value</replaceable> <type>anyelement</type>, <replaceable>n</replaceable> <type>integer</type> )
+ <returnvalue>anyelement</returnvalue>
+ </para>
+ <para>
+ Returns <replaceable>value</replaceable> evaluated
+ at the row that is the <replaceable>n</replaceable>'th
+ row of the window frame (counting from 1);
+ returns <literal>NULL</literal> if there is no such row.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
All of the functions listed in
definition. Rows that are not distinct when considering only the
<literal>ORDER BY</literal> columns are said to be <firstterm>peers</firstterm>.
The four ranking functions (including <function>cume_dist</function>) are
- defined so that they give the same answer for all peer rows.
+ defined so that they give the same answer for all rows of a peer group.
</para>
<para>
</para>
</note>
- <para>
- <function>cume_dist</function> computes the fraction of partition rows that
- are less than or equal to the current row and its peers, while
- <function>percent_rank</function> computes the fraction of partition rows that
- are less than the current row, assuming the current row does not exist
- in the partition.
- </para>
-
</sect1>
<sect1 id="functions-subquery">
<secondary>functions</secondary>
</indexterm>
- <indexterm>
- <primary>generate_series</primary>
- </indexterm>
-
<para>
This section describes functions that possibly return more than one row.
The most widely used functions in this class are series generating
set-returning functions.
</para>
- <table id="functions-srf-series">
- <title>Series Generating Functions</title>
- <tgroup cols="4">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Argument Type</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
+ <table id="functions-srf-series">
+ <title>Series Generating Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- <tbody>
- <row>
- <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>)</function></literal></entry>
- <entry><type>int</type>, <type>bigint</type> or <type>numeric</type></entry>
- <entry><type>setof int</type>, <type>setof bigint</type>, or <type>setof numeric</type> (same as argument type)</entry>
- <entry>
- Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
- with a step size of one
- </entry>
- </row>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>generate_series</primary>
+ </indexterm>
+ <function>generate_series</function> ( <parameter>start</parameter> <type>integer</type>, <parameter>stop</parameter> <type>integer</type> <optional>, <parameter>step</parameter> <type>integer</type> </optional> )
+ <returnvalue>setof integer</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>generate_series</function> ( <parameter>start</parameter> <type>bigint</type>, <parameter>stop</parameter> <type>bigint</type> <optional>, <parameter>step</parameter> <type>bigint</type> </optional> )
+ <returnvalue>setof bigint</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>generate_series</function> ( <parameter>start</parameter> <type>numeric</type>, <parameter>stop</parameter> <type>numeric</type> <optional>, <parameter>step</parameter> <type>numeric</type> </optional> )
+ <returnvalue>setof numeric</returnvalue>
+ </para>
+ <para>
+ Generates a series of values from <parameter>start</parameter>
+ to <parameter>stop</parameter>, with a step size
+ of <parameter>step</parameter>. <parameter>step</parameter>
+ defaults to 1.
+ </para></entry>
+ </row>
- <row>
- <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter>)</function></literal></entry>
- <entry><type>int</type>, <type>bigint</type> or <type>numeric</type></entry>
- <entry><type>setof int</type>, <type>setof bigint</type> or <type>setof numeric</type> (same as argument type)</entry>
- <entry>
- Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
- with a step size of <parameter>step</parameter>
- </entry>
- </row>
-
- <row>
- <entry><literal><function>generate_series(<parameter>start</parameter>, <parameter>stop</parameter>, <parameter>step</parameter> <type>interval</type>)</function></literal></entry>
- <entry><type>timestamp</type> or <type>timestamp with time zone</type></entry>
- <entry><type>setof timestamp</type> or <type>setof timestamp with time zone</type> (same as argument type)</entry>
- <entry>
- Generate a series of values, from <parameter>start</parameter> to <parameter>stop</parameter>
- with a step size of <parameter>step</parameter>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>generate_series</function> ( <parameter>start</parameter> <type>timestamp</type>, <parameter>stop</parameter> <type>timestamp</type>, <parameter>step</parameter> <type>interval</type> )
+ <returnvalue>setof timestamp</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>generate_series</function> ( <parameter>start</parameter> <type>timestamp with time zone</type>, <parameter>stop</parameter> <type>timestamp with time zone</type>, <parameter>step</parameter> <type>interval</type> )
+ <returnvalue>setof timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Generates a series of values from <parameter>start</parameter>
+ to <parameter>stop</parameter>, with a step size
+ of <parameter>step</parameter>.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
When <parameter>step</parameter> is positive, zero rows are returned if
<parameter>start</parameter> is greater than <parameter>stop</parameter>.
Conversely, when <parameter>step</parameter> is negative, zero rows are
returned if <parameter>start</parameter> is less than <parameter>stop</parameter>.
- Zero rows are also returned for <literal>NULL</literal> inputs. It is an error
+ Zero rows are also returned if any input is <literal>NULL</literal>.
+ It is an error
for <parameter>step</parameter> to be zero. Some examples follow:
<programlisting>
SELECT * FROM generate_series(2,4);
(0 rows)
SELECT generate_series(1.1, 4, 1.3);
- generate_series
+ generate_series
-----------------
1.1
2.4
3.7
(3 rows)
--- this example relies on the date-plus-integer operator
+-- this example relies on the date-plus-integer operator:
SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a);
dates
------------
SELECT * FROM generate_series('2008-03-01 00:00'::timestamp,
'2008-03-04 12:00', '10 hours');
- generate_series
+ generate_series
---------------------
2008-03-01 00:00:00
2008-03-01 10:00:00
</programlisting>
</para>
- <table id="functions-srf-subscripts">
- <title>Subscript Generating Functions</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal><function>generate_subscripts(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>)</function></literal></entry>
- <entry><type>setof int</type></entry>
- <entry>
- Generate a series comprising the given array's subscripts.
- </entry>
- </row>
-
- <row>
- <entry><literal><function>generate_subscripts(<parameter>array anyarray</parameter>, <parameter>dim int</parameter>, <parameter>reverse boolean</parameter>)</function></literal></entry>
- <entry><type>setof int</type></entry>
- <entry>
- Generate a series comprising the given array's subscripts. When
- <parameter>reverse</parameter> is true, the series is returned in
- reverse order.
- </entry>
- </row>
+ <table id="functions-srf-subscripts">
+ <title>Subscript Generating Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
- </tbody>
- </tgroup>
- </table>
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>generate_subscripts</primary>
+ </indexterm>
+ <function>generate_subscripts</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>dim</parameter> <type>integer</type> )
+ <returnvalue>setof integer</returnvalue>
+ </para>
+ <para>
+ Generates a series comprising the valid subscripts of
+ the <parameter>dim</parameter>'th dimension of the given array.
+ </para></entry>
+ </row>
- <indexterm>
- <primary>generate_subscripts</primary>
- </indexterm>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>generate_subscripts</function> ( <parameter>array</parameter> <type>anyarray</type>, <parameter>dim</parameter> <type>integer</type>, <parameter>reverse</parameter> <type>boolean</type> )
+ <returnvalue>setof integer</returnvalue>
+ </para>
+ <para>
+ Generates a series comprising the valid subscripts of
+ the <parameter>dim</parameter>'th dimension of the given array.
+ When <parameter>reverse</parameter> is true, returns the series in
+ reverse order.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
<function>generate_subscripts</function> is a convenience function that generates
the set of valid subscripts for the specified dimension of the given
array.
Zero rows are returned for arrays that do not have the requested dimension,
- or for NULL arrays (but valid subscripts are returned for NULL array
- elements). Some examples follow:
+ or if any input is <literal>NULL</literal>.
+ Some examples follow:
<programlisting>
--- basic usage
+-- basic usage:
SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s;
- s
+ s
---
1
2
(4 rows)
-- presenting an array, the subscript and the subscripted
--- value requires a subquery
+-- value requires a subquery:
SELECT * FROM arrays;
- a
+ a
--------------------
{-1,-2}
{100,200,300}
{100,200,300} | 3 | 300
(5 rows)
--- unnest a 2D array
+-- unnest a 2D array:
CREATE OR REPLACE FUNCTION unnest2(anyarray)
RETURNS SETOF anyelement AS $$
select $1[i][j]
$$ LANGUAGE sql IMMUTABLE;
CREATE FUNCTION
SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]);
- unnest2
+ unnest2
---------
1
2
<para>
When a function in the <literal>FROM</literal> clause is suffixed
by <literal>WITH ORDINALITY</literal>, a <type>bigint</type> column is
- appended to the output which starts from 1 and increments by 1 for each row
- of the function's output. This is most useful in the case of set returning
+ appended to the function's output column(s), which starts from 1 and
+ increments by 1 for each row of the function's output.
+ This is most useful in the case of set returning
functions such as <function>unnest()</function>.
<programlisting>
--- set returning function WITH ORDINALITY
+-- set returning function WITH ORDINALITY:
SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n);
ls | n
-----------------+----
<table id="functions-info-session-table">
<title>Session Information Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
- </thead>
-
- <tbody>
<row>
- <entry><literal><function>current_catalog</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>name of current database (called <quote>catalog</quote> in the SQL standard)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
+ </thead>
+ <tbody>
<row>
- <entry><literal><function>current_database()</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>name of current database</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_catalog</primary>
+ </indexterm>
+ <function>current_catalog</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para role="func_signature">
+ <indexterm>
+ <primary>current_database</primary>
+ </indexterm>
+ <function>current_database</function> ()
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ Returns the name of the current database. (Databases are
+ called <quote>catalogs</quote> in the SQL standard,
+ so <function>current_catalog</function> is the standard's
+ spelling.)
+ </para></entry>
</row>
<row>
- <entry><literal><function>current_query()</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>text of the currently executing query, as submitted
- by the client (might contain more than one statement)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_query</primary>
+ </indexterm>
+ <function>current_query</function> ()
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the text of the currently executing query, as submitted
+ by the client (which might contain more than one statement).
+ </para></entry>
</row>
<row>
- <entry><literal><function>current_role</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>equivalent to <function>current_user</function></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_role</primary>
+ </indexterm>
+ <function>current_role</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ This is equivalent to <function>current_user</function>.
+ </para></entry>
</row>
<row>
- <entry><literal><function>current_schema</function>[()]</literal></entry>
- <entry><type>name</type></entry>
- <entry>name of current schema</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_schema</primary>
+ </indexterm>
+ <indexterm>
+ <primary>schema</primary>
+ <secondary>current</secondary>
+ </indexterm>
+ <function>current_schema</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>current_schema</function> ()
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ Returns the name of the schema that is first in the search path (or a
+ null value if the search path is empty). This is the schema that will
+ be used for any tables or other named objects that are created without
+ specifying a target schema.
+ </para></entry>
</row>
<row>
- <entry><literal><function>current_schemas(<type>boolean</type>)</function></literal></entry>
- <entry><type>name[]</type></entry>
- <entry>names of schemas in search path, optionally including implicit schemas</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_schemas</primary>
+ </indexterm>
+ <indexterm>
+ <primary>search path</primary>
+ <secondary>current</secondary>
+ </indexterm>
+ <function>current_schemas</function> ( <parameter>include_implicit</parameter> <type>boolean</type> )
+ <returnvalue>name[]</returnvalue>
+ </para>
+ <para>
+ Returns an array of the names of all schemas presently in the
+ effective search path, in their priority order. (Items in the current
+ <xref linkend="guc-search-path"/> setting that do not correspond to
+ existing, searchable schemas are omitted.) If the Boolean argument
+ is <literal>true</literal>, then implicitly-searched system schemas
+ such as <literal>pg_catalog</literal> are included in the result.
+ </para></entry>
</row>
<row>
- <entry><literal><function>current_user</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>user name of current execution context</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>current_user</primary>
+ </indexterm>
+ <indexterm>
+ <primary>user</primary>
+ <secondary>current</secondary>
+ </indexterm>
+ <function>current_user</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ Returns the user name of the current execution context.
+ </para></entry>
</row>
<row>
- <entry><literal><function>inet_client_addr()</function></literal></entry>
- <entry><type>inet</type></entry>
- <entry>address of the remote connection</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>inet_client_addr</primary>
+ </indexterm>
+ <function>inet_client_addr</function> ()
+ <returnvalue>inet</returnvalue>
+ </para>
+ <para>
+ Returns the IP address of the current client,
+ or <literal>NULL</literal> if the current connection is via a
+ Unix-domain socket.
+ </para></entry>
</row>
<row>
- <entry><literal><function>inet_client_port()</function></literal></entry>
- <entry><type>int</type></entry>
- <entry>port of the remote connection</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>inet_client_port</primary>
+ </indexterm>
+ <function>inet_client_port</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the IP port number of the current client,
+ or <literal>NULL</literal> if the current connection is via a
+ Unix-domain socket.
+ </para></entry>
</row>
<row>
- <entry><literal><function>inet_server_addr()</function></literal></entry>
- <entry><type>inet</type></entry>
- <entry>address of the local connection</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>inet_server_addr</primary>
+ </indexterm>
+ <function>inet_server_addr</function> ()
+ <returnvalue>inet</returnvalue>
+ </para>
+ <para>
+ Returns the IP address on which the server accepted the current
+ connection,
+ or <literal>NULL</literal> if the current connection is via a
+ Unix-domain socket.
+ </para></entry>
</row>
<row>
- <entry><literal><function>inet_server_port()</function></literal></entry>
- <entry><type>int</type></entry>
- <entry>port of the local connection</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>inet_server_port</primary>
+ </indexterm>
+ <function>inet_server_port</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the IP port number on which the server accepted the current
+ connection,
+ or <literal>NULL</literal> if the current connection is via a
+ Unix-domain socket.
+ </para></entry>
</row>
<row>
- <!-- See also the entry for this in monitoring.sgml -->
- <entry><literal><function>pg_backend_pid()</function></literal></entry>
- <entry><type>int</type></entry>
- <entry>
- Process ID of the server process attached to the current session
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_backend_pid</primary>
+ </indexterm>
+ <function>pg_backend_pid</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the process ID of the server process attached to the current
+ session.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_blocking_pids(<type>int</type>)</function></literal></entry>
- <entry><type>int[]</type></entry>
- <entry>Process ID(s) that are blocking specified server process ID from acquiring a lock</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_blocking_pids</primary>
+ </indexterm>
+ <function>pg_blocking_pids</function> ( <type>integer</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Returns an array of the process ID(s) of the sessions that are
+ blocking the server process with the specified process ID from
+ acquiring a lock, or an empty array if there is no such server process
+ or it is not blocked.
+ </para>
+ <para>
+ One server process blocks another if it either holds a lock that
+ conflicts with the blocked process's lock request (hard block), or is
+ waiting for a lock that would conflict with the blocked process's lock
+ request and is ahead of it in the wait queue (soft block). When using
+ parallel queries the result always lists client-visible process IDs
+ (that is, <function>pg_backend_pid</function> results) even if the
+ actual lock is held or awaited by a child worker process. As a result
+ of that, there may be duplicated PIDs in the result. Also note that
+ when a prepared transaction holds a conflicting lock, it will be
+ represented by a zero process ID.
+ </para>
+ <para>
+ Frequent calls to this function could have some impact on database
+ performance, because it needs exclusive access to the lock manager's
+ shared state for a short time.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_conf_load_time()</function></literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>configuration load time</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_conf_load_time</primary>
+ </indexterm>
+ <function>pg_conf_load_time</function> ()
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time when the server configuration files were last loaded.
+ If the current session was alive at the time, this will be the time
+ when the session itself re-read the configuration files (so the
+ reading will vary a little in different sessions). Otherwise it is
+ the time when the postmaster process re-read the configuration files.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_current_logfile(<optional><type>text</type></optional>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>Primary log file name, or log in the requested format,
- currently in use by the logging collector</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_logfile</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Logging</primary>
+ <secondary>pg_current_logfile function</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>current_logfiles</primary>
+ <secondary>and the pg_current_logfile function</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>Logging</primary>
+ <secondary>current_logfiles file and the pg_current_logfile
+ function</secondary>
+ </indexterm>
+ <function>pg_current_logfile</function> ( <optional> <type>text</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the path name of the log file currently in use by the logging
+ collector. The path includes the <xref linkend="guc-log-directory"/>
+ directory and the individual log file name. The result
+ is <literal>NULL</literal> if the logging collector is disabled.
+ When multiple log files exist, each in a different
+ format, <function>pg_current_logfile</function> without an argument
+ returns the path of the file having the first format found in the
+ ordered list: <literal>stderr</literal>,
+ <literal>csvlog</literal>. <literal>NULL</literal> is returned
+ if no log file has any of these formats.
+ To request information about a specific log file format, supply
+ either <literal>csvlog</literal> or <literal>stderr</literal> as the
+ value of the optional parameter. The result is <literal>NULL</literal>
+ if the log format requested is not configured in
+ <xref linkend="guc-log-destination"/>.
+ The result reflects the contents of
+ the <filename>current_logfiles</filename> file.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_my_temp_schema()</function></literal></entry>
- <entry><type>oid</type></entry>
- <entry>OID of session's temporary schema, or 0 if none</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_my_temp_schema</primary>
+ </indexterm>
+ <function>pg_my_temp_schema</function> ()
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Returns the OID of the current session's temporary schema, or zero if
+ it has none (because it has not created any temporary tables).
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_is_other_temp_schema(<type>oid</type>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>is schema another session's temporary schema?</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_is_other_temp_schema</primary>
+ </indexterm>
+ <function>pg_is_other_temp_schema</function> ( <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if the given OID is the OID of another session's
+ temporary schema. (This can be useful, for example, to exclude other
+ sessions' temporary tables from a catalog display.)
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_jit_available()</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>is <acronym>JIT</acronym> compilation available in this session
- (see <xref linkend="jit"/>)? Returns <literal>false</literal> if <xref
- linkend="guc-jit"/> is set to false.</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_jit_available</primary>
+ </indexterm>
+ <function>pg_jit_available</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if <acronym>JIT</acronym> compilation is available in
+ this session (see <xref linkend="jit"/>).
+ Returns false if <xref linkend="guc-jit"/> is set to false, or if the
+ feature was not enabled at compile time.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_listening_channels()</function></literal></entry>
- <entry><type>setof text</type></entry>
- <entry>channel names that the session is currently listening on</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_listening_channels</primary>
+ </indexterm>
+ <function>pg_listening_channels</function> ()
+ <returnvalue>setof text</returnvalue>
+ </para>
+ <para>
+ Returns the set of names of asynchronous notification channels that
+ the current session is listening to.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_notification_queue_usage()</function></literal></entry>
- <entry><type>double</type></entry>
- <entry>fraction of the asynchronous notification queue currently occupied (0–1)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_notification_queue_usage</primary>
+ </indexterm>
+ <function>pg_notification_queue_usage</function> ()
+ <returnvalue>double precision</returnvalue>
+ </para>
+ <para>
+ Returns the fraction (0–1) of the asynchronous notification
+ queue's maximum size that is currently occupied by notifications that
+ are waiting to be processed.
+ See <xref linkend="sql-listen"/> and <xref linkend="sql-notify"/>
+ for more information.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_postmaster_start_time()</function></literal></entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>server start time</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_postmaster_start_time</primary>
+ </indexterm>
+ <function>pg_postmaster_start_time</function> ()
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time when the server started.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_safe_snapshot_blocking_pids(<type>int</type>)</function></literal></entry>
- <entry><type>int[]</type></entry>
- <entry>Process ID(s) that are blocking specified server process ID from acquiring a safe snapshot</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_safe_snapshot_blocking_pids</primary>
+ </indexterm>
+ <function>pg_safe_snapshot_blocking_pids</function> ( <type>integer</type> )
+ <returnvalue>integer[]</returnvalue>
+ </para>
+ <para>
+ Returns an array of the process ID(s) of the sessions that are blocking
+ the server process with the specified process ID from acquiring a safe
+ snapshot, or an empty array if there is no such server process or it
+ is not blocked.
+ </para>
+ <para>
+ A session running a <literal>SERIALIZABLE</literal> transaction blocks
+ a <literal>SERIALIZABLE READ ONLY DEFERRABLE</literal> transaction
+ from acquiring a snapshot until the latter determines that it is safe
+ to avoid taking any predicate locks. See
+ <xref linkend="xact-serializable"/> for more information about
+ serializable and deferrable transactions.
+ </para>
+ <para>
+ Frequent calls to this function could have some impact on database
+ performance, because it needs access to the predicate lock manager's
+ shared state for a short time.
+ </para></entry>
</row>
<row>
- <entry><literal><function>pg_trigger_depth()</function></literal></entry>
- <entry><type>int</type></entry>
- <entry>current nesting level of <productname>PostgreSQL</productname> triggers
- (0 if not called, directly or indirectly, from inside a trigger)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_trigger_depth</primary>
+ </indexterm>
+ <function>pg_trigger_depth</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns the current nesting level
+ of <productname>PostgreSQL</productname> triggers (0 if not called,
+ directly or indirectly, from inside a trigger).
+ </para></entry>
</row>
<row>
- <entry><literal><function>session_user</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>session user name</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>session_user</primary>
+ </indexterm>
+ <function>session_user</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ Returns the session user's name.
+ </para></entry>
</row>
<row>
- <entry><literal><function>user</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>equivalent to <function>current_user</function></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>user</primary>
+ </indexterm>
+ <function>user</function>
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ This is equivalent to <function>current_user</function>.
+ </para></entry>
</row>
<row>
- <entry><literal><function>version()</function></literal></entry>
- <entry><type>text</type></entry>
- <entry><productname>PostgreSQL</productname> version information. See also <xref linkend="guc-server-version-num"/> for a machine-readable version.</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>version</primary>
+ </indexterm>
+ <function>version</function> ()
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns a string describing the <productname>PostgreSQL</productname>
+ server's version. You can also get this information from
+ <xref linkend="guc-server-version"/>, or for a machine-readable
+ version use <xref linkend="guc-server-version-num"/>. Software
+ developers should use <varname>server_version_num</varname> (available
+ since 8.2) or <xref linkend="libpq-PQserverVersion"/> instead of
+ parsing the text version.
+ </para></entry>
</row>
</tbody>
</tgroup>
<function>session_user</function>,
and <function>user</function> have special syntactic status
in <acronym>SQL</acronym>: they must be called without trailing
- parentheses. (In PostgreSQL, parentheses can optionally be used with
- <function>current_schema</function>, but not with the others.)
+ parentheses. In PostgreSQL, parentheses can optionally be used with
+ <function>current_schema</function>, but not with the others.
</para>
</note>
- <indexterm>
- <primary>current_catalog</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_database</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_query</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_role</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_schema</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_schemas</primary>
- </indexterm>
-
- <indexterm>
- <primary>current_user</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_backend_pid</primary>
- </indexterm>
-
- <indexterm>
- <primary>schema</primary>
- <secondary>current</secondary>
- </indexterm>
-
- <indexterm>
- <primary>search path</primary>
- <secondary>current</secondary>
- </indexterm>
-
- <indexterm>
- <primary>session_user</primary>
- </indexterm>
-
- <indexterm>
- <primary>user</primary>
- <secondary>current</secondary>
- </indexterm>
-
- <indexterm>
- <primary>user</primary>
- </indexterm>
-
<para>
The <function>session_user</function> is normally the user who initiated
the current database connection; but superusers can change this setting
does not, since it unifies users and roles into a single kind of entity.)
</para>
- <para>
- <function>current_schema</function> returns the name of the schema that is
- first in the search path (or a null value if the search path is
- empty). This is the schema that will be used for any tables or
- other named objects that are created without specifying a target schema.
- <function>current_schemas(boolean)</function> returns an array of the names of all
- schemas presently in the search path. The Boolean option determines whether or not
- implicitly included system schemas such as <literal>pg_catalog</literal> are included in the
- returned search path.
- </para>
-
- <note>
- <para>
- The search path can be altered at run time. The command is:
-<programlisting>
-SET search_path TO <replaceable>schema</replaceable> <optional>, <replaceable>schema</replaceable>, ...</optional>
-</programlisting>
- </para>
- </note>
-
- <indexterm>
- <primary>inet_client_addr</primary>
- </indexterm>
-
- <indexterm>
- <primary>inet_client_port</primary>
- </indexterm>
-
- <indexterm>
- <primary>inet_server_addr</primary>
- </indexterm>
-
- <indexterm>
- <primary>inet_server_port</primary>
- </indexterm>
-
- <para>
- <function>inet_client_addr</function> returns the IP address of the
- current client, and <function>inet_client_port</function> returns the
- port number.
- <function>inet_server_addr</function> returns the IP address on which
- the server accepted the current connection, and
- <function>inet_server_port</function> returns the port number.
- All these functions return NULL if the current connection is via a
- Unix-domain socket.
- </para>
-
- <indexterm>
- <primary>pg_blocking_pids</primary>
- </indexterm>
-
- <para>
- <function>pg_blocking_pids</function> returns an array of the process IDs
- of the sessions that are blocking the server process with the specified
- process ID, or an empty array if there is no such server process or it is
- not blocked. One server process blocks another if it either holds a lock
- that conflicts with the blocked process's lock request (hard block), or is
- waiting for a lock that would conflict with the blocked process's lock
- request and is ahead of it in the wait queue (soft block). When using
- parallel queries the result always lists client-visible process IDs (that
- is, <function>pg_backend_pid</function> results) even if the actual lock is held
- or awaited by a child worker process. As a result of that, there may be
- duplicated PIDs in the result. Also note that when a prepared transaction
- holds a conflicting lock, it will be represented by a zero process ID in
- the result of this function.
- Frequent calls to this function could have some impact on database
- performance, because it needs exclusive access to the lock manager's
- shared state for a short time.
- </para>
-
- <indexterm>
- <primary>pg_conf_load_time</primary>
- </indexterm>
-
- <para>
- <function>pg_conf_load_time</function> returns the
- <type>timestamp with time zone</type> when the
- server configuration files were last loaded.
- (If the current session was alive at the time, this will be the time
- when the session itself re-read the configuration files, so the
- reading will vary a little in different sessions. Otherwise it is
- the time when the postmaster process re-read the configuration files.)
- </para>
-
- <indexterm>
- <primary>pg_current_logfile</primary>
- </indexterm>
-
- <indexterm>
- <primary>Logging</primary>
- <secondary>pg_current_logfile function</secondary>
- </indexterm>
-
- <indexterm>
- <primary>current_logfiles</primary>
- <secondary>and the pg_current_logfile function</secondary>
- </indexterm>
-
- <indexterm>
- <primary>Logging</primary>
- <secondary>current_logfiles file and the pg_current_logfile
- function</secondary>
- </indexterm>
-
- <para>
- <function>pg_current_logfile</function> returns, as <type>text</type>,
- the path of the log file(s) currently in use by the logging collector.
- The path includes the <xref linkend="guc-log-directory"/> directory
- and the log file name. Log collection must be enabled or the return value
- is <literal>NULL</literal>. When multiple log files exist, each in a
- different format, <function>pg_current_logfile</function> called
- without arguments returns the path of the file having the first format
- found in the ordered list: <systemitem>stderr</systemitem>, <systemitem>csvlog</systemitem>.
- <literal>NULL</literal> is returned when no log file has any of these
- formats. To request a specific file format supply, as <type>text</type>,
- either <systemitem>csvlog</systemitem> or <systemitem>stderr</systemitem> as the value of the
- optional parameter. The return value is <literal>NULL</literal> when the
- log format requested is not a configured
- <xref linkend="guc-log-destination"/>. The
- <function>pg_current_logfile</function> reflects the contents of the
- <filename>current_logfiles</filename> file.
- </para>
-
- <indexterm>
- <primary>pg_my_temp_schema</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_is_other_temp_schema</primary>
- </indexterm>
-
- <para>
- <function>pg_my_temp_schema</function> returns the OID of the current
- session's temporary schema, or zero if it has none (because it has not
- created any temporary tables).
- <function>pg_is_other_temp_schema</function> returns true if the
- given OID is the OID of another session's temporary schema.
- (This can be useful, for example, to exclude other sessions' temporary
- tables from a catalog display.)
- </para>
-
- <indexterm>
- <primary>pg_listening_channels</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_notification_queue_usage</primary>
- </indexterm>
-
- <para>
- <function>pg_listening_channels</function> returns a set of names of
- asynchronous notification channels that the current session is listening
- to. <function>pg_notification_queue_usage</function> returns the
- fraction of the total available space for notifications currently
- occupied by notifications that are waiting to be processed, as a
- <type>double</type> in the range 0–1.
- See <xref linkend="sql-listen"/> and <xref linkend="sql-notify"/>
- for more information.
- </para>
-
- <indexterm>
- <primary>pg_postmaster_start_time</primary>
- </indexterm>
-
- <para>
- <function>pg_postmaster_start_time</function> returns the
- <type>timestamp with time zone</type> when the
- server started.
- </para>
-
- <indexterm>
- <primary>pg_safe_snapshot_blocking_pids</primary>
- </indexterm>
-
- <para>
- <function>pg_safe_snapshot_blocking_pids</function> returns an array of
- the process IDs of the sessions that are blocking the server process with
- the specified process ID from acquiring a safe snapshot, or an empty array
- if there is no such server process or it is not blocked. A session
- running a <literal>SERIALIZABLE</literal> transaction blocks
- a <literal>SERIALIZABLE READ ONLY DEFERRABLE</literal> transaction from
- acquiring a snapshot until the latter determines that it is safe to avoid
- taking any predicate locks. See <xref linkend="xact-serializable"/> for
- more information about serializable and deferrable transactions. Frequent
- calls to this function could have some impact on database performance,
- because it needs access to the predicate lock manager's shared
- state for a short time.
- </para>
-
- <indexterm>
- <primary>version</primary>
- </indexterm>
-
- <para>
- <function>version</function> returns a string describing the
- <productname>PostgreSQL</productname> server's version. You can also
- get this information from <xref linkend="guc-server-version"/> or
- for a machine-readable version, <xref linkend="guc-server-version-num"/>.
- Software developers should use <literal>server_version_num</literal>
- (available since 8.2) or <xref linkend="libpq-PQserverVersion"/> instead
- of parsing the text version.
- </para>
-
<indexterm>
<primary>privilege</primary>
<secondary>querying</secondary>
<para>
<xref linkend="functions-info-access-table"/> lists functions that
- allow the user to query object access privileges programmatically.
- See <xref linkend="ddl-priv"/> for more information about
- privileges.
+ allow querying object access privileges programmatically.
+ (See <xref linkend="ddl-priv"/> for more information about
+ privileges.)
+ In these functions, the user whose privileges are being inquired about
+ can be specified by name or by OID
+ (<structname>pg_authid</structname>.<structfield>oid</structfield>), or if
+ the name is given as <literal>public</literal> then the privileges of the
+ PUBLIC pseudo-role are checked. Also, the <parameter>user</parameter>
+ argument can be omitted entirely, in which case
+ the <function>current_user</function> is assumed.
+ The object that is being inquired about can be specified either by name or
+ by OID, too. When specifying by name, a schema name can be included if
+ relevant.
+ The access privilege of interest is specified by a text string, which must
+ evaluate to one of the appropriate privilege keywords for the object's type
+ (e.g., <literal>SELECT</literal>). Optionally, <literal>WITH GRANT
+ OPTION</literal> can be added to a privilege type to test whether the
+ privilege is held with grant option. Also, multiple privilege types can be
+ listed separated by commas, in which case the result will be true if any of
+ the listed privileges is held. (Case of the privilege string is not
+ significant, and extra whitespace is allowed between but not within
+ privilege names.)
+ Some examples:
+<programlisting>
+SELECT has_table_privilege('myschema.mytable', 'select');
+SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
+</programlisting>
</para>
<table id="functions-info-access-table">
<title>Access Privilege Inquiry Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>has_any_column_privilege</function>(<parameter>user</parameter>,
- <parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for any column of table</entry>
- </row>
- <row>
- <entry><literal><function>has_any_column_privilege</function>(<parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for any column of table</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_any_column_privilege</primary>
+ </indexterm>
+ <function>has_any_column_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>table</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for any column of table?
+ This succeeds either if the privilege is held for the whole table, or
+ if there is a column-level grant of the privilege for at least one
+ column.
+ Allowable privilege types are
+ <literal>SELECT</literal>, <literal>INSERT</literal>,
+ <literal>UPDATE</literal>, and <literal>REFERENCES</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_column_privilege</function>(<parameter>user</parameter>,
- <parameter>table</parameter>,
- <parameter>column</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for column</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_column_privilege</primary>
+ </indexterm>
+ <function>has_column_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>table</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>column</parameter> <type>text</type> or <type>smallint</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for the specified table column?
+ This succeeds either if the privilege is held for the whole table, or
+ if there is a column-level grant of the privilege for the column.
+ The column can be specified by name or by attribute number
+ (<structname>pg_attribute</structname>.<structfield>attnum</structfield>).
+ Allowable privilege types are
+ <literal>SELECT</literal>, <literal>INSERT</literal>,
+ <literal>UPDATE</literal>, and <literal>REFERENCES</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_column_privilege</function>(<parameter>table</parameter>,
- <parameter>column</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for column</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_database_privilege</primary>
+ </indexterm>
+ <function>has_database_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>database</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for database?
+ Allowable privilege types are
+ <literal>CREATE</literal>,
+ <literal>CONNECT</literal>,
+ <literal>TEMPORARY</literal>, and
+ <literal>TEMP</literal> (which is equivalent to
+ <literal>TEMPORARY</literal>).
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_database_privilege</function>(<parameter>user</parameter>,
- <parameter>database</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for database</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_foreign_data_wrapper_privilege</primary>
+ </indexterm>
+ <function>has_foreign_data_wrapper_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>fdw</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for foreign-data wrapper?
+ The only allowable privilege type is <literal>USAGE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_database_privilege</function>(<parameter>database</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for database</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_function_privilege</primary>
+ </indexterm>
+ <function>has_function_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>function</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for function?
+ The only allowable privilege type is <literal>EXECUTE</literal>.
+ </para>
+ <para>
+ When specifying a function by name rather than by OID, the allowed
+ input is the same as for the <type>regprocedure</type> data type (see
+ <xref linkend="datatype-oid"/>).
+ An example is:
+<programlisting>
+SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
+</programlisting>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>user</parameter>,
- <parameter>fdw</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for foreign-data wrapper</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_language_privilege</primary>
+ </indexterm>
+ <function>has_language_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>language</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for language?
+ The only allowable privilege type is <literal>USAGE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_foreign_data_wrapper_privilege</function>(<parameter>fdw</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for foreign-data wrapper</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_schema_privilege</primary>
+ </indexterm>
+ <function>has_schema_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>schema</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for schema?
+ Allowable privilege types are
+ <literal>CREATE</literal> and
+ <literal>USAGE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_function_privilege</function>(<parameter>user</parameter>,
- <parameter>function</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for function</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_sequence_privilege</primary>
+ </indexterm>
+ <function>has_sequence_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>sequence</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for sequence?
+ Allowable privilege types are
+ <literal>USAGE</literal>,
+ <literal>SELECT</literal>, and
+ <literal>UPDATE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_function_privilege</function>(<parameter>function</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for function</entry>
- </row>
- <row>
- <entry><literal><function>has_language_privilege</function>(<parameter>user</parameter>,
- <parameter>language</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for language</entry>
- </row>
- <row>
- <entry><literal><function>has_language_privilege</function>(<parameter>language</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for language</entry>
- </row>
- <row>
- <entry><literal><function>has_schema_privilege</function>(<parameter>user</parameter>,
- <parameter>schema</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for schema</entry>
- </row>
- <row>
- <entry><literal><function>has_schema_privilege</function>(<parameter>schema</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for schema</entry>
- </row>
- <row>
- <entry><literal><function>has_sequence_privilege</function>(<parameter>user</parameter>,
- <parameter>sequence</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for sequence</entry>
- </row>
- <row>
- <entry><literal><function>has_sequence_privilege</function>(<parameter>sequence</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for sequence</entry>
- </row>
- <row>
- <entry><literal><function>has_server_privilege</function>(<parameter>user</parameter>,
- <parameter>server</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for foreign server</entry>
- </row>
- <row>
- <entry><literal><function>has_server_privilege</function>(<parameter>server</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for foreign server</entry>
- </row>
- <row>
- <entry><literal><function>has_table_privilege</function>(<parameter>user</parameter>,
- <parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for table</entry>
- </row>
- <row>
- <entry><literal><function>has_table_privilege</function>(<parameter>table</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for table</entry>
- </row>
- <row>
- <entry><literal><function>has_tablespace_privilege</function>(<parameter>user</parameter>,
- <parameter>tablespace</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for tablespace</entry>
- </row>
- <row>
- <entry><literal><function>has_tablespace_privilege</function>(<parameter>tablespace</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for tablespace</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_server_privilege</primary>
+ </indexterm>
+ <function>has_server_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>server</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for foreign server?
+ The only allowable privilege type is <literal>USAGE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_type_privilege</function>(<parameter>user</parameter>,
- <parameter>type</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for type</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_table_privilege</primary>
+ </indexterm>
+ <function>has_table_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>table</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for table?
+ Allowable privilege types
+ are <literal>SELECT</literal>, <literal>INSERT</literal>,
+ <literal>UPDATE</literal>, <literal>DELETE</literal>,
+ <literal>TRUNCATE</literal>, <literal>REFERENCES</literal>,
+ and <literal>TRIGGER</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>has_type_privilege</function>(<parameter>type</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for type</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_tablespace_privilege</primary>
+ </indexterm>
+ <function>has_tablespace_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>tablespace</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for tablespace?
+ The only allowable privilege type is <literal>CREATE</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_has_role</function>(<parameter>user</parameter>,
- <parameter>role</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does user have privilege for role</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>has_type_privilege</primary>
+ </indexterm>
+ <function>has_type_privilege</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>type</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for data type?
+ The only allowable privilege type is <literal>USAGE</literal>.
+ When specifying a type by name rather than by OID, the allowed input
+ is the same as for the <type>regtype</type> data type (see
+ <xref linkend="datatype-oid"/>).
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_has_role</function>(<parameter>role</parameter>,
- <parameter>privilege</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have privilege for role</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_has_role</primary>
+ </indexterm>
+ <function>pg_has_role</function> (
+ <optional> <parameter>user</parameter> <type>name</type> or <type>oid</type>, </optional>
+ <parameter>role</parameter> <type>text</type> or <type>oid</type>,
+ <parameter>privilege</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does user have privilege for role?
+ Allowable privilege types are
+ <literal>MEMBER</literal> and <literal>USAGE</literal>.
+ <literal>MEMBER</literal> denotes direct or indirect membership in
+ the role (that is, the right to do <command>SET ROLE</command>), while
+ <literal>USAGE</literal> denotes whether the privileges of the role
+ are immediately available without doing <command>SET ROLE</command>.
+ This function does not allow the special case of
+ setting <parameter>user</parameter> to <literal>public</literal>,
+ because the PUBLIC pseudo-role can never be a member of real roles.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>row_security_active</function>(<parameter>table</parameter>)</literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>does current user have row level security active for table</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>row_security_active</primary>
+ </indexterm>
+ <function>row_security_active</function> (
+ <parameter>table</parameter> <type>text</type> or <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is row-level security active for the specified table in the context of
+ the current user and current environment?
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <indexterm>
- <primary>has_any_column_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_column_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_database_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_function_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_foreign_data_wrapper_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_language_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_schema_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_server_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_sequence_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_table_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_tablespace_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>has_type_privilege</primary>
- </indexterm>
- <indexterm>
- <primary>pg_has_role</primary>
- </indexterm>
- <indexterm>
- <primary>row_security_active</primary>
- </indexterm>
-
- <para>
- <function>has_table_privilege</function> checks whether a user
- can access a table in a particular way. The user can be
- specified by name, by OID (<literal>pg_authid.oid</literal>),
- <literal>public</literal> to indicate the PUBLIC pseudo-role, or if the argument is
- omitted
- <function>current_user</function> is assumed. The table can be specified
- by name or by OID. (Thus, there are actually six variants of
- <function>has_table_privilege</function>, which can be distinguished by
- the number and types of their arguments.) When specifying by name,
- the name can be schema-qualified if necessary.
- The desired access privilege type
- is specified by a text string, which must evaluate to one of the
- values <literal>SELECT</literal>, <literal>INSERT</literal>,
- <literal>UPDATE</literal>, <literal>DELETE</literal>, <literal>TRUNCATE</literal>,
- <literal>REFERENCES</literal>, or <literal>TRIGGER</literal>. Optionally,
- <literal>WITH GRANT OPTION</literal> can be added to a privilege type to test
- whether the privilege is held with grant option. Also, multiple privilege
- types can be listed separated by commas, in which case the result will
- be <literal>true</literal> if any of the listed privileges is held.
- (Case of the privilege string is not significant, and extra whitespace
- is allowed between but not within privilege names.)
- Some examples:
-<programlisting>
-SELECT has_table_privilege('myschema.mytable', 'select');
-SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');
-</programlisting>
- </para>
-
- <para>
- <function>has_sequence_privilege</function> checks whether a user
- can access a sequence in a particular way. The possibilities for its
- arguments are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to one of
- <literal>USAGE</literal>,
- <literal>SELECT</literal>, or
- <literal>UPDATE</literal>.
- </para>
-
- <para>
- <function>has_any_column_privilege</function> checks whether a user can
- access any column of a table in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>,
- except that the desired access privilege type must evaluate to some
- combination of
- <literal>SELECT</literal>,
- <literal>INSERT</literal>,
- <literal>UPDATE</literal>, or
- <literal>REFERENCES</literal>. Note that having any of these privileges
- at the table level implicitly grants it for each column of the table,
- so <function>has_any_column_privilege</function> will always return
- <literal>true</literal> if <function>has_table_privilege</function> does for the same
- arguments. But <function>has_any_column_privilege</function> also succeeds if
- there is a column-level grant of the privilege for at least one column.
- </para>
-
- <para>
- <function>has_column_privilege</function> checks whether a user
- can access a column in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>,
- with the addition that the column can be specified either by name
- or attribute number.
- The desired access privilege type must evaluate to some combination of
- <literal>SELECT</literal>,
- <literal>INSERT</literal>,
- <literal>UPDATE</literal>, or
- <literal>REFERENCES</literal>. Note that having any of these privileges
- at the table level implicitly grants it for each column of the table.
- </para>
-
- <para>
- <function>has_database_privilege</function> checks whether a user
- can access a database in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to some combination of
- <literal>CREATE</literal>,
- <literal>CONNECT</literal>,
- <literal>TEMPORARY</literal>, or
- <literal>TEMP</literal> (which is equivalent to
- <literal>TEMPORARY</literal>).
- </para>
-
- <para>
- <function>has_function_privilege</function> checks whether a user
- can access a function in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- When specifying a function by a text string rather than by OID,
- the allowed input is the same as for the <type>regprocedure</type> data type
- (see <xref linkend="datatype-oid"/>).
- The desired access privilege type must evaluate to
- <literal>EXECUTE</literal>.
- An example is:
-<programlisting>
-SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');
-</programlisting>
- </para>
-
- <para>
- <function>has_foreign_data_wrapper_privilege</function> checks whether a user
- can access a foreign-data wrapper in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to
- <literal>USAGE</literal>.
- </para>
-
- <para>
- <function>has_language_privilege</function> checks whether a user
- can access a procedural language in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to
- <literal>USAGE</literal>.
- </para>
-
- <para>
- <function>has_schema_privilege</function> checks whether a user
- can access a schema in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to some combination of
- <literal>CREATE</literal> or
- <literal>USAGE</literal>.
- </para>
-
- <para>
- <function>has_server_privilege</function> checks whether a user
- can access a foreign server in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to
- <literal>USAGE</literal>.
- </para>
-
- <para>
- <function>has_tablespace_privilege</function> checks whether a user
- can access a tablespace in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- The desired access privilege type must evaluate to
- <literal>CREATE</literal>.
- </para>
-
- <para>
- <function>has_type_privilege</function> checks whether a user
- can access a type in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>.
- When specifying a type by a text string rather than by OID,
- the allowed input is the same as for the <type>regtype</type> data type
- (see <xref linkend="datatype-oid"/>).
- The desired access privilege type must evaluate to
- <literal>USAGE</literal>.
- </para>
-
- <para>
- <function>pg_has_role</function> checks whether a user
- can access a role in a particular way.
- Its argument possibilities
- are analogous to <function>has_table_privilege</function>,
- except that <literal>public</literal> is not allowed as a user name.
- The desired access privilege type must evaluate to some combination of
- <literal>MEMBER</literal> or
- <literal>USAGE</literal>.
- <literal>MEMBER</literal> denotes direct or indirect membership in
- the role (that is, the right to do <command>SET ROLE</command>), while
- <literal>USAGE</literal> denotes whether the privileges of the role
- are immediately available without doing <command>SET ROLE</command>.
- </para>
-
- <para>
- <function>row_security_active</function> checks whether row level
- security is active for the specified table in the context of the
- <function>current_user</function> and environment. The table can
- be specified by name or by OID.
- </para>
-
<para>
<xref linkend="functions-aclitem-fn-table"/> shows the operators
available for the <type>aclitem</type> type, which is the catalog
for information about how to read access privilege values.
</para>
- <indexterm>
- <primary>acldefault</primary>
- </indexterm>
- <indexterm>
- <primary>aclitemeq</primary>
- </indexterm>
- <indexterm>
- <primary>aclcontains</primary>
- </indexterm>
- <indexterm>
- <primary>aclexplode</primary>
- </indexterm>
- <indexterm>
- <primary>makeaclitem</primary>
- </indexterm>
-
<table id="functions-aclitem-op-table">
<title><type>aclitem</type> Operators</title>
- <tgroup cols="4">
+ <tgroup cols="1">
<thead>
<row>
- <entry>Operator</entry>
- <entry>Description</entry>
- <entry>Example</entry>
- <entry>Result</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ Operator
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
</row>
</thead>
- <tbody>
+ <tbody>
<row>
- <entry> <literal>=</literal> </entry>
- <entry>equal</entry>
- <entry><literal>'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem</literal></entry>
- <entry><literal>f</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>aclitemeq</primary>
+ </indexterm>
+ <type>aclitem</type> <literal>=</literal> <type>aclitem</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Are <type>aclitem</type>s equal? (Notice that
+ type <type>aclitem</type> lacks the usual set of comparison
+ operators; it has only equality. In turn, <type>aclitem</type>
+ arrays can only be compared for equality.)
+ </para>
+ <para>
+ <literal>'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem</literal>
+ <returnvalue>f</returnvalue>
+ </para></entry>
</row>
<row>
- <entry> <literal>@></literal> </entry>
- <entry>contains element</entry>
- <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem</literal></entry>
- <entry><literal>t</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>aclcontains</primary>
+ </indexterm>
+ <type>aclitem[]</type> <literal>@></literal> <type>aclitem</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Does array contain the specified privileges? (This is true if there
+ is an array entry that matches the <type>aclitem</type>'s grantee and
+ grantor, and has at least the specified set of privileges.)
+ </para>
+ <para>
+ <literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitem</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
</row>
<row>
- <entry> <literal>~</literal> </entry>
- <entry>contains element</entry>
- <entry><literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*w/hobbes'::aclitem</literal></entry>
- <entry><literal>t</literal></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <type>aclitem[]</type> <literal>~</literal> <type>aclitem</type>
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ This is a deprecated alias for <literal>@></literal>.
+ </para>
+ <para>
+ <literal>'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem</literal>
+ <returnvalue>t</returnvalue>
+ </para></entry>
</row>
-
</tbody>
</tgroup>
</table>
<table id="functions-aclitem-fn-table">
<title><type>aclitem</type> Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
+
<tbody>
<row>
- <entry><literal><function>acldefault</function>(<parameter>type</parameter>,
- <parameter>ownerId</parameter>)</literal></entry>
- <entry><type>aclitem[]</type></entry>
- <entry>get the default access privileges for an object belonging to <parameter>ownerId</parameter></entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>acldefault</primary>
+ </indexterm>
+ <function>acldefault</function> (
+ <parameter>type</parameter> <type>"char"</type>,
+ <parameter>ownerId</parameter> <type>oid</type> )
+ <returnvalue>aclitem[]</returnvalue>
+ </para>
+ <para>
+ Constructs an <type>aclitem</type> array holding the default access
+ privileges for an object of type <parameter>type</parameter> belonging
+ to the role with OID <parameter>ownerId</parameter>. This represents
+ the access privileges that will be assumed when an object's ACL entry
+ is null. (The default access privileges are described in
+ <xref linkend="ddl-priv"/>.)
+ The <parameter>type</parameter> parameter must be one of
+ 'c' for <literal>COLUMN</literal>,
+ 'r' for <literal>TABLE</literal> and table-like objects,
+ 's' for <literal>SEQUENCE</literal>,
+ 'd' for <literal>DATABASE</literal>,
+ 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
+ 'l' for <literal>LANGUAGE</literal>,
+ 'L' for <literal>LARGE OBJECT</literal>,
+ 'n' for <literal>SCHEMA</literal>,
+ 't' for <literal>TABLESPACE</literal>,
+ 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
+ 'S' for <literal>FOREIGN SERVER</literal>,
+ or
+ 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>aclexplode</function>(<parameter>aclitem[]</parameter>)</literal></entry>
- <entry><type>setof record</type></entry>
- <entry>get <type>aclitem</type> array as tuples</entry>
- </row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>aclexplode</primary>
+ </indexterm>
+ <function>aclexplode</function> ( <type>aclitem[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>grantor</parameter> <type>oid</type>,
+ <parameter>grantee</parameter> <type>oid</type>,
+ <parameter>privilege_type</parameter> <type>text</type>,
+ <parameter>is_grantable</parameter> <type>boolean</type> )
+ </para>
+ <para>
+ Returns the <type>aclitem</type> array as a set of rows.
+ If the grantee is the pseudo-role PUBLIC, it is represented by zero in
+ the <parameter>grantee</parameter> column. Each granted privilege is
+ represented as <literal>SELECT</literal>, <literal>INSERT</literal>,
+ etc. Note that each privilege is broken out as a separate row, so
+ only one keyword appears in the <parameter>privilege_type</parameter>
+ column.
+ </para></entry>
+ </row>
+
<row>
- <entry><literal><function>makeaclitem</function>(<parameter>grantee</parameter>, <parameter>grantor</parameter>, <parameter>privilege</parameter>, <parameter>grantable</parameter>)</literal></entry>
- <entry><type>aclitem</type></entry>
- <entry>build an <type>aclitem</type> from input</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>makeaclitem</primary>
+ </indexterm>
+ <function>makeaclitem</function> (
+ <parameter>grantee</parameter> <type>oid</type>,
+ <parameter>grantor</parameter> <type>oid</type>,
+ <parameter>privileges</parameter> <type>text</type>,
+ <parameter>is_grantable</parameter> <type>boolean</type> )
+ <returnvalue>aclitem</returnvalue>
+ </para>
+ <para>
+ Constructs an <type>aclitem</type> with the given properties.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- <function>acldefault</function> returns the built-in default access
- privileges for an object of type <parameter>type</parameter> belonging to
- role <parameter>ownerId</parameter>. These represent the access
- privileges that will be assumed when an object's ACL entry is null.
- (The default access privileges are described in <xref linkend="ddl-priv"/>.)
- The <parameter>type</parameter> parameter is a <type>CHAR</type>: write
- 'c' for <literal>COLUMN</literal>,
- 'r' for <literal>TABLE</literal> and table-like objects,
- 's' for <literal>SEQUENCE</literal>,
- 'd' for <literal>DATABASE</literal>,
- 'f' for <literal>FUNCTION</literal> or <literal>PROCEDURE</literal>,
- 'l' for <literal>LANGUAGE</literal>,
- 'L' for <literal>LARGE OBJECT</literal>,
- 'n' for <literal>SCHEMA</literal>,
- 't' for <literal>TABLESPACE</literal>,
- 'F' for <literal>FOREIGN DATA WRAPPER</literal>,
- 'S' for <literal>FOREIGN SERVER</literal>,
- or
- 'T' for <literal>TYPE</literal> or <literal>DOMAIN</literal>.
- </para>
-
- <para>
- <function>aclexplode</function> returns an <type>aclitem</type> array
- as a set of rows. Output columns are grantor <type>oid</type>,
- grantee <type>oid</type> (<literal>0</literal> for <literal>PUBLIC</literal>),
- granted privilege as <type>text</type> (<literal>SELECT</literal>, ...)
- and whether the privilege is grantable as <type>boolean</type>.
- <function>makeaclitem</function> performs the inverse operation.
- </para>
-
<para>
<xref linkend="functions-info-schema-table"/> shows functions that
determine whether a certain object is <firstterm>visible</firstterm> in the
containing schema is in the search path and no table of the same
name appears earlier in the search path. This is equivalent to the
statement that the table can be referenced by name without explicit
- schema qualification. To list the names of all visible tables:
+ schema qualification. Thus, to list the names of all visible tables:
<programlisting>
SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);
</programlisting>
+ For functions and operators, an object in the search path is said to be
+ visible if there is no object of the same name <emphasis>and argument data
+ type(s)</emphasis> earlier in the path. For operator classes and families,
+ both the name and the associated index access method are considered.
</para>
<indexterm>
<table id="functions-info-schema-table">
<title>Schema Visibility Inquiry Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>pg_collation_is_visible(<parameter>collation_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is collation visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_collation_is_visible</primary>
+ </indexterm>
+ <function>pg_collation_is_visible</function> ( <parameter>collation</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is collation visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_conversion_is_visible(<parameter>conversion_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is conversion visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_conversion_is_visible</primary>
+ </indexterm>
+ <function>pg_conversion_is_visible</function> ( <parameter>conversion</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is conversion visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_function_is_visible(<parameter>function_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is function visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_function_is_visible</primary>
+ </indexterm>
+ <function>pg_function_is_visible</function> ( <parameter>function</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is function visible in search path?
+ (This also works for procedures and aggregates.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_opclass_is_visible(<parameter>opclass_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is operator class visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_opclass_is_visible</primary>
+ </indexterm>
+ <function>pg_opclass_is_visible</function> ( <parameter>opclass</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is operator class visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_operator_is_visible(<parameter>operator_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is operator visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_operator_is_visible</primary>
+ </indexterm>
+ <function>pg_operator_is_visible</function> ( <parameter>operator</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is operator visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_opfamily_is_visible(<parameter>opclass_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is operator family visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_opfamily_is_visible</primary>
+ </indexterm>
+ <function>pg_opfamily_is_visible</function> ( <parameter>opclass</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is operator family visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_statistics_obj_is_visible(<parameter>stat_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is statistics object visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_statistics_obj_is_visible</primary>
+ </indexterm>
+ <function>pg_statistics_obj_is_visible</function> ( <parameter>stat</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is statistics object visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_table_is_visible(<parameter>table_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is table visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_table_is_visible</primary>
+ </indexterm>
+ <function>pg_table_is_visible</function> ( <parameter>table</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is table visible in search path?
+ (This works for all types of relations, including views, materialized
+ views, indexes, sequences and foreign tables.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_ts_config_is_visible(<parameter>config_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is text search configuration visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ts_config_is_visible</primary>
+ </indexterm>
+ <function>pg_ts_config_is_visible</function> ( <parameter>config</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is text search configuration visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_ts_dict_is_visible(<parameter>dict_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is text search dictionary visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ts_dict_is_visible</primary>
+ </indexterm>
+ <function>pg_ts_dict_is_visible</function> ( <parameter>dict</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is text search dictionary visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_ts_parser_is_visible(<parameter>parser_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is text search parser visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ts_parser_is_visible</primary>
+ </indexterm>
+ <function>pg_ts_parser_is_visible</function> ( <parameter>parser</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is text search parser visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_ts_template_is_visible(<parameter>template_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is text search template visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ts_template_is_visible</primary>
+ </indexterm>
+ <function>pg_ts_template_is_visible</function> ( <parameter>template</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is text search template visible in search path?
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_type_is_visible(<parameter>type_oid</parameter>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>is type (or domain) visible in search path</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_type_is_visible</primary>
+ </indexterm>
+ <function>pg_type_is_visible</function> ( <parameter>type</parameter> <type>oid</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is type (or domain) visible in search path?
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <indexterm>
- <primary>pg_collation_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_conversion_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_function_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_opclass_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_operator_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_opfamily_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_statistics_obj_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_table_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_ts_config_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_ts_dict_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_ts_parser_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_ts_template_is_visible</primary>
- </indexterm>
- <indexterm>
- <primary>pg_type_is_visible</primary>
- </indexterm>
-
- <para>
- Each function performs the visibility check for one type of database
- object. Note that <function>pg_table_is_visible</function> can also be used
- with views, materialized views, indexes, sequences and foreign tables;
- <function>pg_function_is_visible</function> can also be used with
- procedures and aggregates;
- <function>pg_type_is_visible</function> can also be used with domains.
- For functions and operators, an object in
- the search path is visible if there is no object of the same name
- <emphasis>and argument data type(s)</emphasis> earlier in the path. For operator
- classes, both name and associated index access method are considered.
- </para>
-
<para>
All these functions require object OIDs to identify the object to be
checked. If you want to test an object by name, it is convenient to use
type name in this way — if the name can be recognized at all, it must be visible.
</para>
- <indexterm>
- <primary>format_type</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_constraintdef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_expr</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_functiondef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_function_arguments</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_function_identity_arguments</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_function_result</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_indexdef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_keywords</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_ruledef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_serial_sequence</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_statisticsobjdef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_triggerdef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_userbyid</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_viewdef</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_index_column_has_property</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_index_has_property</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_indexam_has_property</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_options_to_table</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_tablespace_databases</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_tablespace_location</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_typeof</primary>
- </indexterm>
-
- <indexterm>
- <primary>collation for</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regclass</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regcollation</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regnamespace</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regrole</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regoper</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regoperator</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regproc</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regprocedure</primary>
- </indexterm>
-
- <indexterm>
- <primary>to_regtype</primary>
- </indexterm>
-
<para>
<xref linkend="functions-info-catalog-table"/> lists functions that
extract information from the system catalogs.
<table id="functions-info-catalog-table">
<title>System Catalog Information Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>format_type(<parameter>type_oid</parameter>, <parameter>typemod</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get SQL name of a data type</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_constraintdef(<parameter>constraint_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get definition of a constraint</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_constraintdef(<parameter>constraint_oid</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get definition of a constraint</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_expr(<parameter>pg_node_tree</parameter>, <parameter>relation_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>decompile internal form of an expression, assuming that any Vars
- in it refer to the relation indicated by the second parameter</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_expr(<parameter>pg_node_tree</parameter>, <parameter>relation_oid</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>decompile internal form of an expression, assuming that any Vars
- in it refer to the relation indicated by the second parameter</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_functiondef(<parameter>func_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get definition of a function or procedure</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_function_arguments(<parameter>func_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get argument list of function's or procedure's definition (with default values)</entry>
- </row>
- <row>
- <entry><literal><function>pg_get_function_identity_arguments(<parameter>func_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get argument list to identify a function or procedure (without default values)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>format_type</primary>
+ </indexterm>
+ <function>format_type</function> ( <parameter>type</parameter> <type>oid</type>, <parameter>typemod</parameter> <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the SQL name for a data type that is identified by its type
+ OID and possibly a type modifier. Pass NULL for the type modifier if
+ no specific modifier is known.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_function_result(<parameter>func_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <literal>RETURNS</literal> clause for function (returns null for a procedure)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_constraintdef</primary>
+ </indexterm>
+ <function>pg_get_constraintdef</function> ( <parameter>constraint</parameter> <type>oid</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for a constraint.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_indexdef(<parameter>index_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE INDEX</command> command for index</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_expr</primary>
+ </indexterm>
+ <function>pg_get_expr</function> ( <parameter>expr</parameter> <type>pg_node_tree</type>, <parameter>relation</parameter> <type>oid</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Decompiles the internal form of an expression stored in the system
+ catalogs, such as the default value for a column. If the expression
+ might contain Vars, specify the OID of the relation they refer to as
+ the second parameter; if no Vars are expected, passing zero is
+ sufficient.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_indexdef(<parameter>index_oid</parameter>, <parameter>column_no</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE INDEX</command> command for index,
- or definition of just one index column when
- <parameter>column_no</parameter> is not zero</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_functiondef</primary>
+ </indexterm>
+ <function>pg_get_functiondef</function> ( <parameter>func</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for a function or procedure.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ The result is a complete <command>CREATE OR REPLACE FUNCTION</command>
+ or <command>CREATE OR REPLACE PROCEDURE</command> statement.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_keywords()</function></literal></entry>
- <entry><type>setof record</type></entry>
- <entry>get list of SQL keywords and their categories</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_function_arguments</primary>
+ </indexterm>
+ <function>pg_get_function_arguments</function> ( <parameter>func</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the argument list of a function or procedure, in the form
+ it would need to appear in within <command>CREATE FUNCTION</command>
+ (including default values).
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_ruledef(<parameter>rule_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE RULE</command> command for rule</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_function_identity_arguments</primary>
+ </indexterm>
+ <function>pg_get_function_identity_arguments</function> ( <parameter>func</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the argument list necessary to identify a function or
+ procedure, in the form it would need to appear in within commands such
+ as <command>ALTER FUNCTION</command>. This form omits default values.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_ruledef(<parameter>rule_oid</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE RULE</command> command for rule</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_function_result</primary>
+ </indexterm>
+ <function>pg_get_function_result</function> ( <parameter>func</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the <literal>RETURNS</literal> clause of a function, in
+ the form it would need to appear in within <command>CREATE
+ FUNCTION</command>. Returns <literal>NULL</literal> for a procedure.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_serial_sequence(<parameter>table_name</parameter>, <parameter>column_name</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get name of the sequence that a serial or identity column uses</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_indexdef</primary>
+ </indexterm>
+ <function>pg_get_indexdef</function> ( <parameter>index</parameter> <type>oid</type> <optional>, <parameter>column</parameter> <type>integer</type>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for an index.
+ (This is a decompiled reconstruction, not the original text
+ of the command.) If <parameter>column</parameter> is supplied and is
+ not zero, only the definition of that column is reconstructed.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_statisticsobjdef(<parameter>statobj_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE STATISTICS</command> command for extended statistics object</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_keywords</primary>
+ </indexterm>
+ <function>pg_get_keywords</function> ()
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>word</parameter> <type>text</type>,
+ <parameter>catcode</parameter> <type>"char"</type>,
+ <parameter>catdesc</parameter> <type>text</type> )
+ </para>
+ <para>
+ Returns a set of records describing the SQL keywords recognized by the
+ server. The <parameter>word</parameter> column contains the
+ keyword. The <parameter>catcode</parameter> column contains a
+ category code: <literal>U</literal> for an unreserved
+ keyword, <literal>C</literal> for a keyword that can be a column
+ name, <literal>T</literal> for a keyword that can be a type or
+ function name, or <literal>R</literal> for a fully reserved keyword.
+ The <parameter>catdesc</parameter> column contains a
+ possibly-localized string describing the category.
+ </para></entry>
</row>
+
<row>
- <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>)</entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</command> command for trigger</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_ruledef</primary>
+ </indexterm>
+ <function>pg_get_ruledef</function> ( <parameter>rule</parameter> <type>oid</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for a rule.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </para></entry>
</row>
+
<row>
- <entry><function>pg_get_triggerdef</function>(<parameter>trigger_oid</parameter>, <parameter>pretty_bool</parameter>)</entry>
- <entry><type>text</type></entry>
- <entry>get <command>CREATE [ CONSTRAINT ] TRIGGER</command> command for trigger</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_serial_sequence</primary>
+ </indexterm>
+ <function>pg_get_serial_sequence</function> ( <parameter>table</parameter> <type>text</type>, <parameter>column</parameter> <type>text</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the name of the sequence associated with a column,
+ or NULL if no sequence is associated with the column.
+ If the column is an identity column, the associated sequence is the
+ sequence internally created for that column.
+ For columns created using one of the serial types
+ (<type>serial</type>, <type>smallserial</type>, <type>bigserial</type>),
+ it is the sequence created for that serial column definition.
+ In the latter case, the association can be modified or removed
+ with <command>ALTER SEQUENCE OWNED BY</command>.
+ (This function probably should have been
+ called <function>pg_get_owned_sequence</function>; its current name
+ reflects the fact that it has historically been used with serial-type
+ columns.) The first parameter is a table name with optional
+ schema, and the second parameter is a column name. Because the first
+ parameter potentially contains both schema and table names, it is
+ parsed per usual SQL rules, meaning it is lower-cased by default.
+ The second parameter, being just a column name, is treated literally
+ and so has its case preserved. The result is suitably formatted
+ for passing to the sequence functions (see
+ <xref linkend="functions-sequence"/>).
+ </para>
+ <para>
+ A typical use is in reading the current value of the sequence for an
+ identity or serial column, for example:
+<programlisting>
+SELECT currval(pg_get_serial_sequence('sometable', 'id'));
+</programlisting>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_userbyid(<parameter>role_oid</parameter>)</function></literal></entry>
- <entry><type>name</type></entry>
- <entry>get role name with given OID</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_statisticsobjdef</primary>
+ </indexterm>
+ <function>pg_get_statisticsobjdef</function> ( <parameter>statobj</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for an extended statistics object.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_viewdef(<parameter>view_name</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get underlying <command>SELECT</command> command for view or materialized view (<emphasis>deprecated</emphasis>)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_triggerdef</primary>
+ </indexterm>
+<function>pg_get_triggerdef</function> ( <parameter>trigger</parameter> <type>oid</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the creating command for a trigger.
+ (This is a decompiled reconstruction, not the original text
+ of the command.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_viewdef(<parameter>view_name</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get underlying <command>SELECT</command> command for view or materialized view (<emphasis>deprecated</emphasis>)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_userbyid</primary>
+ </indexterm>
+ <function>pg_get_userbyid</function> ( <parameter>role</parameter> <type>oid</type> )
+ <returnvalue>name</returnvalue>
+ </para>
+ <para>
+ Returns a role's name given its OID.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_viewdef(<parameter>view_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get underlying <command>SELECT</command> command for view or materialized view</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_viewdef</primary>
+ </indexterm>
+ <function>pg_get_viewdef</function> ( <parameter>view</parameter> <type>oid</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the underlying <command>SELECT</command> command for a
+ view or materialized view. (This is a decompiled reconstruction, not
+ the original text of the command.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_viewdef(<parameter>view_oid</parameter>, <parameter>pretty_bool</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get underlying <command>SELECT</command> command for view or materialized view</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_get_viewdef</function> ( <parameter>view</parameter> <type>oid</type>, <parameter>wrap_column</parameter> <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the underlying <command>SELECT</command> command for a
+ view or materialized view. (This is a decompiled reconstruction, not
+ the original text of the command.) In this form of the function,
+ pretty-printing is always enabled, and long lines are wrapped to try
+ to keep them shorter than the specified number of columns.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_viewdef(<parameter>view_oid</parameter>, <parameter>wrap_column_int</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get underlying <command>SELECT</command> command for view or
- materialized view; lines with fields are wrapped to specified
- number of columns, pretty-printing is implied</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_get_viewdef</function> ( <parameter>view</parameter> <type>text</type> <optional>, <parameter>pretty</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reconstructs the underlying <command>SELECT</command> command for a
+ view or materialized view, working from a textual name for the view
+ rather than its OID. (This is deprecated; use the OID variant
+ instead.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_index_column_has_property(<parameter>index_oid</parameter>, <parameter>column_no</parameter>, <parameter>prop_name</parameter>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>test whether an index column has a specified property</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_index_column_has_property</primary>
+ </indexterm>
+ <function>pg_index_column_has_property</function> ( <parameter>index</parameter> <type>regclass</type>, <parameter>column</parameter> <type>integer</type>, <parameter>property</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Tests whether an index column has the named property.
+ Common index column properties are listed in
+ <xref linkend="functions-info-index-column-props"/>.
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ <literal>NULL</literal> is returned if the property name is not known
+ or does not apply to the particular object, or if the OID or column
+ number does not identify a valid object.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_index_has_property(<parameter>index_oid</parameter>, <parameter>prop_name</parameter>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>test whether an index has a specified property</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_index_has_property</primary>
+ </indexterm>
+ <function>pg_index_has_property</function> ( <parameter>index</parameter> <type>regclass</type>, <parameter>property</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Tests whether an index has the named property.
+ Common index properties are listed in
+ <xref linkend="functions-info-index-props"/>.
+ (Note that extension access methods can define additional property
+ names for their indexes.)
+ <literal>NULL</literal> is returned if the property name is not known
+ or does not apply to the particular object, or if the OID does not
+ identify a valid object.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_indexam_has_property(<parameter>am_oid</parameter>, <parameter>prop_name</parameter>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>test whether an index access method has a specified property</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_indexam_has_property</primary>
+ </indexterm>
+ <function>pg_indexam_has_property</function> ( <parameter>am</parameter> <type>oid</type>, <parameter>property</parameter> <type>text</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Tests whether an index access method has the named property.
+ Access method properties are listed in
+ <xref linkend="functions-info-indexam-props"/>.
+ <literal>NULL</literal> is returned if the property name is not known
+ or does not apply to the particular object, or if the OID does not
+ identify a valid object.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_options_to_table(<parameter>reloptions</parameter>)</function></literal></entry>
- <entry><type>setof record</type></entry>
- <entry>get the set of storage option name/value pairs</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_options_to_table</primary>
+ </indexterm>
+ <function>pg_options_to_table</function> ( <parameter>reloptions</parameter> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>option_name</parameter> <type>text</type>,
+ <parameter>option_value</parameter> <type>text</type> )
+ </para>
+ <para>
+ Returns the set of storage options represented by a value from
+ <structname>pg_class</structname>.<structfield>reloptions</structfield> or
+ <structname>pg_attribute</structname>.<structfield>attoptions</structfield>.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_tablespace_databases(<parameter>tablespace_oid</parameter>)</function></literal></entry>
- <entry><type>setof oid</type></entry>
- <entry>get the set of database OIDs that have objects in the tablespace</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_tablespace_databases</primary>
+ </indexterm>
+ <function>pg_tablespace_databases</function> ( <parameter>tablespace</parameter> <type>oid</type> )
+ <returnvalue>setof oid</returnvalue>
+ </para>
+ <para>
+ Returns the set of OIDs of databases that have objects stored in the
+ specified tablespace. If this function returns any rows, the
+ tablespace is not empty and cannot be dropped. To identify the specific
+ objects populating the tablespace, you will need to connect to the
+ database(s) identified by <function>pg_tablespace_databases</function>
+ and query their <structname>pg_class</structname> catalogs.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_tablespace_location(<parameter>tablespace_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get the path in the file system that this tablespace is located in</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_tablespace_location</primary>
+ </indexterm>
+ <function>pg_tablespace_location</function> ( <parameter>tablespace</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the file system path that this tablespace is located in.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_typeof(<parameter>any</parameter>)</function></literal></entry>
- <entry><type>regtype</type></entry>
- <entry>get the data type of any value</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_typeof</primary>
+ </indexterm>
+ <function>pg_typeof</function> ( <type>"any"</type> )
+ <returnvalue>regtype</returnvalue>
+ </para>
+ <para>
+ Returns the OID of the data type of the value that is passed to it.
+ This can be helpful for troubleshooting or dynamically constructing
+ SQL queries. The function is declared as
+ returning <type>regtype</type>, which is an OID alias type (see
+ <xref linkend="datatype-oid"/>); this means that it is the same as an
+ OID for comparison purposes but displays as a type name.
+ </para>
+ <para>
+ For example:
+<programlisting>
+SELECT pg_typeof(33);
+ pg_typeof
+-----------
+ integer
+
+SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
+ typlen
+--------
+ 4
+</programlisting>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>collation for (<parameter>any</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get the collation of the argument</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>COLLATION FOR</primary>
+ </indexterm>
+ <function>COLLATION FOR</function> ( <type>"any"</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the name of the collation of the value that is passed to it.
+ The value is quoted and schema-qualified if necessary. If no
+ collation was derived for the argument expression,
+ then <literal>NULL</literal> is returned. If the argument is not of a
+ collatable data type, then an error is raised.
+ </para>
+ <para>
+ For example:
+<programlisting>
+SELECT collation for (description) FROM pg_description LIMIT 1;
+ pg_collation_for
+------------------
+ "default"
+
+SELECT collation for ('foo' COLLATE "de_DE");
+ pg_collation_for
+------------------
+ "de_DE"
+</programlisting>
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regclass(<parameter>rel_name</parameter>)</function></literal></entry>
- <entry><type>regclass</type></entry>
- <entry>get the OID of the named relation</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regclass</primary>
+ </indexterm>
+ <function>to_regclass</function> ( <type>text</type> )
+ <returnvalue>regclass</returnvalue>
+ </para>
+ <para>
+ Translates a textual relation name to its OID. A similar result is
+ obtained by casting the string to type <type>regclass</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regcollation(<parameter>coll_name</parameter>)</function></literal></entry>
- <entry><type>regcollation</type></entry>
- <entry>get the OID of the named collation</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regcollation</primary>
+ </indexterm>
+ <function>to_regcollation</function> ( <type>text</type> )
+ <returnvalue>regcollation</returnvalue>
+ </para>
+ <para>
+ Translates a textual collation name to its OID. A similar result is
+ obtained by casting the string to type <type>regcollation</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regnamespace(<parameter>schema_name</parameter>)</function></literal></entry>
- <entry><type>regnamespace</type></entry>
- <entry>get the OID of the named schema</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regnamespace</primary>
+ </indexterm>
+ <function>to_regnamespace</function> ( <type>text</type> )
+ <returnvalue>regnamespace</returnvalue>
+ </para>
+ <para>
+ Translates a textual schema name to its OID. A similar result is
+ obtained by casting the string to type <type>regnamespace</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regoper(<parameter>operator_name</parameter>)</function></literal></entry>
- <entry><type>regoper</type></entry>
- <entry>get the OID of the named operator</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regoper</primary>
+ </indexterm>
+ <function>to_regoper</function> ( <type>text</type> )
+ <returnvalue>regoper</returnvalue>
+ </para>
+ <para>
+ Translates a textual operator name to its OID. A similar result is
+ obtained by casting the string to type <type>regoper</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found or is ambiguous. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regoperator(<parameter>operator_name</parameter>)</function></literal></entry>
- <entry><type>regoperator</type></entry>
- <entry>get the OID of the named operator</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regoperator</primary>
+ </indexterm>
+ <function>to_regoperator</function> ( <type>text</type> )
+ <returnvalue>regoperator</returnvalue>
+ </para>
+ <para>
+ Translates a textual operator name (with parameter types) to its OID. A similar result is
+ obtained by casting the string to type <type>regoperator</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regrole(<parameter>role_name</parameter>)</function></literal></entry>
- <entry><type>regrole</type></entry>
- <entry>get the OID of the named role</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regproc</primary>
+ </indexterm>
+ <function>to_regproc</function> ( <type>text</type> )
+ <returnvalue>regproc</returnvalue>
+ </para>
+ <para>
+ Translates a textual function or procedure name to its OID. A similar result is
+ obtained by casting the string to type <type>regproc</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found or is ambiguous. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regproc(<parameter>func_name</parameter>)</function></literal></entry>
- <entry><type>regproc</type></entry>
- <entry>get the OID of the named function</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regprocedure</primary>
+ </indexterm>
+ <function>to_regprocedure</function> ( <type>text</type> )
+ <returnvalue>regprocedure</returnvalue>
+ </para>
+ <para>
+ Translates a textual function or procedure name (with argument types) to its OID. A similar result is
+ obtained by casting the string to type <type>regprocedure</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regprocedure(<parameter>func_name</parameter>)</function></literal></entry>
- <entry><type>regprocedure</type></entry>
- <entry>get the OID of the named function</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regrole</primary>
+ </indexterm>
+ <function>to_regrole</function> ( <type>text</type> )
+ <returnvalue>regrole</returnvalue>
+ </para>
+ <para>
+ Translates a textual role name to its OID. A similar result is
+ obtained by casting the string to type <type>regrole</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>to_regtype(<parameter>type_name</parameter>)</function></literal></entry>
- <entry><type>regtype</type></entry>
- <entry>get the OID of the named type</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>to_regtype</primary>
+ </indexterm>
+ <function>to_regtype</function> ( <type>text</type> )
+ <returnvalue>regtype</returnvalue>
+ </para>
+ <para>
+ Translates a textual type name to its OID. A similar result is
+ obtained by casting the string to type <type>regtype</type> (see
+ <xref linkend="datatype-oid"/>); however, this function will return
+ <literal>NULL</literal> rather than throwing an error if the name is
+ not found. Also unlike the cast, this does not accept
+ a numeric OID as input.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
- <function>format_type</function> returns the SQL name of a data type that
- is identified by its type OID and possibly a type modifier. Pass NULL
- for the type modifier if no specific modifier is known.
- </para>
-
- <para>
- <function>pg_get_keywords</function> returns a set of records describing
- the SQL keywords recognized by the server. The <structfield>word</structfield> column
- contains the keyword. The <structfield>catcode</structfield> column contains a
- category code: <literal>U</literal> for unreserved, <literal>C</literal> for column name,
- <literal>T</literal> for type or function name, or <literal>R</literal> for reserved.
- The <structfield>catdesc</structfield> column contains a possibly-localized string
- describing the category.
- </para>
-
- <para>
- <function>pg_get_constraintdef</function>,
- <function>pg_get_indexdef</function>, <function>pg_get_ruledef</function>,
- <function>pg_get_statisticsobjdef</function>, and
- <function>pg_get_triggerdef</function>, respectively reconstruct the
- creating command for a constraint, index, rule, extended statistics object,
- or trigger. (Note that this is a decompiled reconstruction, not the
- original text of the command.) <function>pg_get_expr</function> decompiles
- the internal form of an individual expression, such as the default value
- for a column. It can be useful when examining the contents of system
- catalogs. If the expression might contain Vars, specify the OID of the
- relation they refer to as the second parameter; if no Vars are expected,
- zero is sufficient. <function>pg_get_viewdef</function> reconstructs the
- <command>SELECT</command> query that defines a view. Most of these functions come
- in two variants, one of which can optionally <quote>pretty-print</quote> the
- result. The pretty-printed format is more readable, but the default format
+ Most of the functions that reconstruct (decompile) database objects
+ have an optional <parameter>pretty</parameter> flag, which
+ if <literal>true</literal> causes the result to
+ be <quote>pretty-printed</quote>. Pretty-printing suppresses unnecessary
+ parentheses and adds whitespace for legibility.
+ The pretty-printed format is more readable, but the default format
is more likely to be interpreted the same way by future versions of
- <productname>PostgreSQL</productname>; avoid using pretty-printed output for dump
- purposes. Passing <literal>false</literal> for the pretty-print parameter yields
- the same result as the variant that does not have the parameter at all.
- </para>
-
- <para>
- <function>pg_get_functiondef</function> returns a complete
- <command>CREATE OR REPLACE FUNCTION</command> statement for a function.
- <function>pg_get_function_arguments</function> returns the argument list
- of a function, in the form it would need to appear in within
- <command>CREATE FUNCTION</command>.
- <function>pg_get_function_result</function> similarly returns the
- appropriate <literal>RETURNS</literal> clause for the function.
- <function>pg_get_function_identity_arguments</function> returns the
- argument list necessary to identify a function, in the form it
- would need to appear in within <command>ALTER FUNCTION</command>, for
- instance. This form omits default values.
- </para>
-
- <para>
- <function>pg_get_serial_sequence</function> returns the name of the
- sequence associated with a column, or NULL if no sequence is associated
- with the column. If the column is an identity column, the associated
- sequence is the sequence internally created for the identity column. For
- columns created using one of the serial types
- (<type>serial</type>, <type>smallserial</type>, <type>bigserial</type>), it
- is the sequence created for that serial column definition. In the latter
- case, this association can be modified or removed with <command>ALTER
- SEQUENCE OWNED BY</command>. (The function probably should have been called
- <function>pg_get_owned_sequence</function>; its current name reflects the
- fact that it has typically been used with <type>serial</type>
- or <type>bigserial</type> columns.) The first input parameter is a table name
- with optional schema, and the second parameter is a column name. Because
- the first parameter is potentially a schema and table, it is not treated as
- a double-quoted identifier, meaning it is lower cased by default, while the
- second parameter, being just a column name, is treated as double-quoted and
- has its case preserved. The function returns a value suitably formatted
- for passing to sequence functions
- (see <xref linkend="functions-sequence"/>). A typical use is in reading the
- current value of a sequence for an identity or serial column, for example:
-<programlisting>
-SELECT currval(pg_get_serial_sequence('sometable', 'id'));
-</programlisting>
- </para>
-
- <para>
- <function>pg_get_userbyid</function> extracts a role's name given
- its OID.
- </para>
-
- <para>
- <function>pg_index_column_has_property</function>,
- <function>pg_index_has_property</function>, and
- <function>pg_indexam_has_property</function> return whether the
- specified index column, index, or index access method possesses the named
- property. <literal>NULL</literal> is returned if the property name is not
- known or does not apply to the particular object, or if the OID or column
- number does not identify a valid object. Refer to
- <xref linkend="functions-info-index-column-props"/> for column properties,
- <xref linkend="functions-info-index-props"/> for index properties, and
- <xref linkend="functions-info-indexam-props"/> for access method properties.
- (Note that extension access methods can define additional property names
- for their indexes.)
+ <productname>PostgreSQL</productname>; so avoid using pretty-printed output
+ for dump purposes. Passing <literal>false</literal> for
+ the <parameter>pretty</parameter> parameter yields the same result as
+ omitting the parameter.
</para>
<table id="functions-info-index-column-props">
</tgroup>
</table>
- <para>
- <function>pg_options_to_table</function> returns the set of storage
- option name/value pairs
- (<replaceable>option_name</replaceable>/<replaceable>option_value</replaceable>) when passed
- <structname>pg_class</structname>.<structfield>reloptions</structfield> or
- <structname>pg_attribute</structname>.<structfield>attoptions</structfield>.
- </para>
-
- <para>
- <function>pg_tablespace_databases</function> allows a tablespace to be
- examined. It returns the set of OIDs of databases that have objects stored
- in the tablespace. If this function returns any rows, the tablespace is not
- empty and cannot be dropped. To display the specific objects populating the
- tablespace, you will need to connect to the databases identified by
- <function>pg_tablespace_databases</function> and query their
- <structname>pg_class</structname> catalogs.
- </para>
-
- <para>
- <function>pg_typeof</function> returns the OID of the data type of the
- value that is passed to it. This can be helpful for troubleshooting or
- dynamically constructing SQL queries. The function is declared as
- returning <type>regtype</type>, which is an OID alias type (see
- <xref linkend="datatype-oid"/>); this means that it is the same as an
- OID for comparison purposes but displays as a type name. For example:
-<programlisting>
-SELECT pg_typeof(33);
-
- pg_typeof
------------
- integer
-(1 row)
-
-SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
- typlen
---------
- 4
-(1 row)
-</programlisting>
- </para>
-
- <para>
- The expression <literal>collation for</literal> returns the collation of the
- value that is passed to it. Example:
-<programlisting>
-SELECT collation for (description) FROM pg_description LIMIT 1;
- pg_collation_for
-------------------
- "default"
-(1 row)
-
-SELECT collation for ('foo' COLLATE "de_DE");
- pg_collation_for
-------------------
- "de_DE"
-(1 row)
-</programlisting>
- The value might be quoted and schema-qualified. If no collation is derived
- for the argument expression, then a null value is returned. If the argument
- is not of a collatable data type, then an error is raised.
- </para>
-
- <para>
- The functions <function>to_regclass</function>, <function>to_regcollation</function>,
- <function>to_regnamespace</function>, <function>to_regoper</function>,
- <function>to_regoperator</function>, <function>to_regrole</function>,
- <function>to_regproc</function>, <function>to_regprocedure</function> and
- <function>to_regtype</function> translate relation, collation, schema,
- operator, role, function, and type names (given as <type>text</type>) to
- objects of the corresponding <type>reg*</type> type (see <xref
- linkend="datatype-oid"/> about the types). These functions differ from a
- cast from text in that they don't accept a numeric OID, and that they
- return null rather than throwing an error if the name is not found (or, for
- <function>to_regproc</function> and <function>to_regoper</function>, if the
- given name matches multiple objects).
- </para>
-
- <indexterm>
- <primary>pg_describe_object</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_identify_object</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_identify_object_as_address</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_get_object_address</primary>
- </indexterm>
-
<para>
<xref linkend="functions-info-object-table"/> lists functions related to
database object identification and addressing.
<table id="functions-info-object-table">
<title>Object Information and Addressing Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>pg_describe_object(<parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get description of a database object</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_describe_object</primary>
+ </indexterm>
+ <function>pg_describe_object</function> ( <parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns a textual description of a database object identified by
+ catalog OID, object OID, and sub-object ID (such as a column number
+ within a table; the sub-object ID is zero when referring to a whole
+ object). This description is intended to be human-readable, and might
+ be translated, depending on server configuration. This is especially
+ useful to determine the identity of an object referenced in the
+ <structname>pg_depend</structname> catalog.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_identify_object(<parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type>)</function></literal></entry>
- <entry><parameter>type</parameter> <type>text</type>, <parameter>schema</parameter> <type>text</type>, <parameter>name</parameter> <type>text</type>, <parameter>identity</parameter> <type>text</type></entry>
- <entry>get identity of a database object</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_identify_object</primary>
+ </indexterm>
+ <function>pg_identify_object</function> ( <parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>type</parameter> <type>text</type>,
+ <parameter>schema</parameter> <type>text</type>,
+ <parameter>name</parameter> <type>text</type>,
+ <parameter>identity</parameter> <type>text</type> )
+ </para>
+ <para>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by catalog OID, object OID and sub-object
+ ID.
+ This information is intended to be machine-readable, and is never
+ translated.
+ <parameter>type</parameter> identifies the type of database object;
+ <parameter>schema</parameter> is the schema name that the object
+ belongs in, or <literal>NULL</literal> for object types that do not
+ belong to schemas;
+ <parameter>name</parameter> is the name of the object, quoted if
+ necessary, if the name (along with schema name, if pertinent) is
+ sufficient to uniquely identify the object,
+ otherwise <literal>NULL</literal>;
+ <parameter>identity</parameter> is the complete object identity, with
+ the precise format depending on object type, and each name within the
+ format being schema-qualified and quoted as necessary.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_identify_object_as_address(<parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type>)</function></literal></entry>
- <entry><parameter>type</parameter> <type>text</type>, <parameter>object_names</parameter> <type>text[]</type>, <parameter>object_args</parameter> <type>text[]</type></entry>
- <entry>get external representation of a database object's address</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_identify_object_as_address</primary>
+ </indexterm>
+ <function>pg_identify_object_as_address</function> ( <parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>type</parameter> <type>text</type>,
+ <parameter>object_names</parameter> <type>text[]</type>,
+ <parameter>object_args</parameter> <type>text[]</type> )
+ </para>
+ <para>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by catalog OID, object OID and sub-object
+ ID.
+ The returned information is independent of the current server, that
+ is, it could be used to identify an identically named object in
+ another server.
+ <parameter>type</parameter> identifies the type of database object;
+ <parameter>object_names</parameter> and
+ <parameter>object_args</parameter>
+ are text arrays that together form a reference to the object.
+ These three values can be passed
+ to <function>pg_get_object_address</function> to obtain the internal
+ address of the object.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_get_object_address(<parameter>type</parameter> <type>text</type>, <parameter>object_names</parameter> <type>text[]</type>, <parameter>object_args</parameter> <type>text[]</type>)</function></literal></entry>
- <entry><parameter>classid</parameter> <type>oid</type>, <parameter>objid</parameter> <type>oid</type>, <parameter>objsubid</parameter> <type>integer</type></entry>
- <entry>get address of a database object from its external representation</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_get_object_address</primary>
+ </indexterm>
+ <function>pg_get_object_address</function> ( <parameter>type</parameter> <type>text</type>, <parameter>object_names</parameter> <type>text[]</type>, <parameter>object_args</parameter> <type>text[]</type> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>classid</parameter> <type>oid</type>,
+ <parameter>objid</parameter> <type>oid</type>,
+ <parameter>objsubid</parameter> <type>integer</type> )
+ </para>
+ <para>
+ Returns a row containing enough information to uniquely identify the
+ database object specified by a type code and object name and argument
+ arrays.
+ The returned values are the ones that would be used in system catalogs
+ such as <structname>pg_depend</structname>; they can be passed to
+ other system functions such as <function>pg_describe_object</function>
+ or <function>pg_identify_object</function>.
+ <parameter>classid</parameter> is the OID of the system catalog
+ containing the object;
+ <parameter>objid</parameter> is the OID of the object itself, and
+ <parameter>objsubid</parameter> is the sub-object ID, or zero if none.
+ This function is the inverse
+ of <function>pg_identify_object_as_address</function>.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- <function>pg_describe_object</function> returns a textual description of a database
- object specified by catalog OID, object OID, and sub-object ID (such as
- a column number within a table; the sub-object ID is zero when referring
- to a whole object).
- This description is intended to be human-readable, and might be translated,
- depending on server configuration.
- This is useful to determine the identity of an object as stored in the
- <structname>pg_depend</structname> catalog.
- </para>
-
- <para>
- <function>pg_identify_object</function> returns a row containing enough information
- to uniquely identify the database object specified by catalog OID, object OID and
- sub-object ID. This information is intended to be machine-readable,
- and is never translated.
- <parameter>type</parameter> identifies the type of database object;
- <parameter>schema</parameter> is the schema name that the object belongs in, or
- <literal>NULL</literal> for object types that do not belong to schemas;
- <parameter>name</parameter> is the name of the object, quoted if necessary,
- if the name (along with schema name, if pertinent) is sufficient to
- uniquely identify the object, otherwise <literal>NULL</literal>;
- <parameter>identity</parameter> is the complete object identity, with the
- precise format depending on object type, and each name within the format
- being schema-qualified and quoted as necessary.
- </para>
-
- <para>
- <function>pg_identify_object_as_address</function> returns a row containing
- enough information to uniquely identify the database object specified by
- catalog OID, object OID and sub-object ID. The returned
- information is independent of the current server, that is, it could be used
- to identify an identically named object in another server.
- <parameter>type</parameter> identifies the type of database object;
- <parameter>object_names</parameter> and <parameter>object_args</parameter>
- are text arrays that together form a reference to the object.
- These three values can be passed to
- <function>pg_get_object_address</function> to obtain the internal address
- of the object.
- This function is the inverse of <function>pg_get_object_address</function>.
- </para>
-
- <para>
- <function>pg_get_object_address</function> returns a row containing enough
- information to uniquely identify the database object specified by its
- type and object name and argument arrays. The returned values are the
- ones that would be used in system catalogs such as <structname>pg_depend</structname>
- and can be passed to other system functions such as
- <function>pg_identify_object</function> or <function>pg_describe_object</function>.
- <parameter>classid</parameter> is the OID of the system catalog containing the
- object;
- <parameter>objid</parameter> is the OID of the object itself, and
- <parameter>objsubid</parameter> is the sub-object ID, or zero if none.
- This function is the inverse of <function>pg_identify_object_as_address</function>.
- </para>
-
- <indexterm>
- <primary>col_description</primary>
- </indexterm>
-
- <indexterm>
- <primary>obj_description</primary>
- </indexterm>
-
- <indexterm>
- <primary>shobj_description</primary>
- </indexterm>
-
<indexterm>
<primary>comment</primary>
<secondary sortas="database objects">about database objects</secondary>
<table id="functions-info-comment-table">
<title>Comment Information Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>col_description(<parameter>table_oid</parameter>, <parameter>column_number</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get comment for a table column</entry>
- </row>
- <row>
- <entry><literal><function>obj_description(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get comment for a database object</entry>
- </row>
- <row>
- <entry><literal><function>obj_description(<parameter>object_oid</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get comment for a database object (<emphasis>deprecated</emphasis>)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>col_description</primary>
+ </indexterm>
+ <function>col_description</function> ( <parameter>table</parameter> <type>oid</type>, <parameter>column</parameter> <type>integer</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the comment for a table column, which is specified by the OID
+ of its table and its column number.
+ (<function>obj_description</function> cannot be used for table
+ columns, since columns do not have OIDs of their own.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>shobj_description(<parameter>object_oid</parameter>, <parameter>catalog_name</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>get comment for a shared database object</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>obj_description</primary>
+ </indexterm>
+ <function>obj_description</function> ( <parameter>object</parameter> <type>oid</type>, <parameter>catalog</parameter> <type>name</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the comment for a database object specified by its OID and the
+ name of the containing system catalog. For
+ example, <literal>obj_description(123456, 'pg_class')</literal> would
+ retrieve the comment for the table with OID 123456.
+ </para></entry>
</row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- <function>col_description</function> returns the comment for a table
- column, which is specified by the OID of its table and its column number.
- (<function>obj_description</function> cannot be used for table columns
- since columns do not have OIDs of their own.)
- </para>
-
- <para>
- The two-parameter form of <function>obj_description</function> returns the
- comment for a database object specified by its OID and the name of the
- containing system catalog. For example,
- <literal>obj_description(123456,'pg_class')</literal>
- would retrieve the comment for the table with OID 123456.
- The one-parameter form of <function>obj_description</function> requires only
- the object OID. It is deprecated since there is no guarantee that
- OIDs are unique across different system catalogs; therefore, the wrong
- comment might be returned.
- </para>
-
- <para>
- <function>shobj_description</function> is used just like
- <function>obj_description</function> except it is used for retrieving
- comments on shared objects. Some system catalogs are global to all
- databases within each cluster, and the descriptions for objects in them
- are stored globally as well.
- </para>
-
- <indexterm>
- <primary>pg_current_xact_id</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_current_xact_id_if_assigned</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_current_snapshot</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_snapshot_xip</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_snapshot_xmax</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_snapshot_xmin</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_visible_in_snapshot</primary>
- </indexterm>
-
- <indexterm>
- <primary>pg_xact_status</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_current</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_current_if_assigned</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_current_snapshot</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_snapshot_xip</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_snapshot_xmax</primary>
- </indexterm>
-
- <indexterm>
- <primary>txid_snapshot_xmin</primary>
- </indexterm>
- <indexterm>
- <primary>txid_visible_in_snapshot</primary>
- </indexterm>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>obj_description</function> ( <parameter>object</parameter> <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the comment for a database object specified by its OID alone.
+ This is <emphasis>deprecated</emphasis> since there is no guarantee
+ that OIDs are unique across different system catalogs; therefore, the
+ wrong comment might be returned.
+ </para></entry>
+ </row>
- <indexterm>
- <primary>txid_status</primary>
- </indexterm>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>shobj_description</primary>
+ </indexterm>
+ <function>shobj_description</function> ( <parameter>object</parameter> <type>oid</type>, <parameter>catalog</parameter> <type>name</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the comment for a shared database object specified by its OID
+ and the name of the containing system catalog. This is just
+ like <function>obj_description</function> except that it is used for
+ retrieving comments on shared objects (that is, databases, roles, and
+ tablespaces). Some system catalogs are global to all databases within
+ each cluster, and the descriptions for objects in them are stored
+ globally as well.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
The functions shown in <xref linkend="functions-pg-snapshot"/>
</para>
<table id="functions-pg-snapshot">
- <title>Transaction IDs and Snapshots</title>
- <tgroup cols="3">
+ <title>Transaction ID and Snapshot Information Functions</title>
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry><literal><function>pg_current_xact_id()</function></literal></entry>
- <entry><type>xid8</type></entry>
- <entry>get current transaction ID, assigning a new one if the current transaction does not have one</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_xact_id</primary>
+ </indexterm>
+ <function>pg_current_xact_id</function> ()
+ <returnvalue>xid8</returnvalue>
+ </para>
+ <para>
+ Returns the current transaction's ID. It will assign a new one if the
+ current transaction does not have one already (because it has not
+ performed any database updates).
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_current_xact_id_if_assigned()</function></literal></entry>
- <entry><type>xid8</type></entry>
- <entry>same as <function>pg_current_xact_id()</function> but returns null instead of assigning a new transaction ID if none is already assigned</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_xact_id_if_assigned</primary>
+ </indexterm>
+ <function>pg_current_xact_id_if_assigned</function> ()
+ <returnvalue>xid8</returnvalue>
+ </para>
+ <para>
+ Returns the current transaction's ID, or <literal>NULL</literal> if no
+ ID is assigned yet. (It's best to use this variant if the transaction
+ might otherwise be read-only, to avoid unnecessary consumption of an
+ XID.)
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_xact_status(<parameter>xid8</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>report the status of the given transaction: <literal>committed</literal>, <literal>aborted</literal>, <literal>in progress</literal>, or null if the transaction ID is too old</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_xact_status</primary>
+ </indexterm>
+ <function>pg_xact_status</function> ( <type>xid8</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Reports the commit status of a recent transaction.
+ The result is one of <literal>in progress</literal>,
+ <literal>committed</literal>, or <literal>aborted</literal>,
+ provided that the transaction is recent enough that the system retains
+ the commit status of that transaction.
+ If it is old enough that no references to the transaction survive in
+ the system and the commit status information has been discarded, the
+ result is <literal>NULL</literal>.
+ Applications might use this function, for example, to determine
+ whether their transaction committed or aborted after the application
+ and database server become disconnected while
+ a <literal>COMMIT</literal> is in progress.
+ Note that prepared transactions are reported as <literal>in
+ progress</literal>; applications must check <link
+ linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>
+ if they need to determine whether a transaction ID belongs to a
+ prepared transaction.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_current_snapshot()</function></literal></entry>
- <entry><type>pg_snapshot</type></entry>
- <entry>get current snapshot</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_snapshot</primary>
+ </indexterm>
+ <function>pg_current_snapshot</function> ()
+ <returnvalue>pg_snapshot</returnvalue>
+ </para>
+ <para>
+ Returns a current <firstterm>snapshot</firstterm>, a data structure
+ showing which transaction IDs are now in-progress.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_snapshot_xip(<parameter>pg_snapshot</parameter>)</function></literal></entry>
- <entry><type>setof xid8</type></entry>
- <entry>get in-progress transaction IDs in snapshot</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_snapshot_xip</primary>
+ </indexterm>
+ <function>pg_snapshot_xip</function> ( <type>pg_snapshot</type> )
+ <returnvalue>setof xid8</returnvalue>
+ </para>
+ <para>
+ Returns the set of in-progress transaction IDs contained in a snapshot.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_snapshot_xmax(<parameter>pg_snapshot</parameter>)</function></literal></entry>
- <entry><type>xid8</type></entry>
- <entry>get <literal>xmax</literal> of snapshot</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_snapshot_xmax</primary>
+ </indexterm>
+ <function>pg_snapshot_xmax</function> ( <type>pg_snapshot</type> )
+ <returnvalue>xid8</returnvalue>
+ </para>
+ <para>
+ Returns the <structfield>xmax</structfield> of a snapshot.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_snapshot_xmin(<parameter>pg_snapshot</parameter>)</function></literal></entry>
- <entry><type>xid8</type></entry>
- <entry>get <literal>xmin</literal> of snapshot</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_snapshot_xmin</primary>
+ </indexterm>
+ <function>pg_snapshot_xmin</function> ( <type>pg_snapshot</type> )
+ <returnvalue>xid8</returnvalue>
+ </para>
+ <para>
+ Returns the <structfield>xmin</structfield> of a snapshot.
+ </para></entry>
</row>
+
<row>
- <entry><literal><function>pg_visible_in_snapshot(<parameter>xid8</parameter>, <parameter>pg_snapshot</parameter>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>is transaction ID visible in snapshot? (do not use with subtransaction IDs)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_visible_in_snapshot</primary>
+ </indexterm>
+ <function>pg_visible_in_snapshot</function> ( <type>xid8</type>, <type>pg_snapshot</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Is the given transaction ID <firstterm>visible</firstterm> according
+ to this snapshot (that is, was it completed before the snapshot was
+ taken)? Note that this function will not give the correct answer for
+ a subtransaction ID.
+ </para></entry>
</row>
</tbody>
</tgroup>
<para>
The internal transaction ID type <type>xid</type> is 32 bits wide and
- wraps around every 4 billion transactions. However, these functions use a
- 64-bit variant <type>xid8</type> that does not wrap around during the life
+ wraps around every 4 billion transactions. However,
+ the functions shown in <xref linkend="functions-pg-snapshot"/> use a
+ 64-bit type <type>xid8</type> that does not wrap around during the life
of an installation, and can be converted to <type>xid</type> by casting if
required. The data type <type>pg_snapshot</type> stores information about
transaction ID visibility at a particular moment in time. Its components
are described in <xref linkend="functions-pg-snapshot-parts"/>.
+ <type>pg_snapshot</type>'s textual representation is
+ <literal><replaceable>xmin</replaceable>:<replaceable>xmax</replaceable>:<replaceable>xip_list</replaceable></literal>.
+ For example <literal>10:20:10,14,15</literal> means
+ <literal>xmin=10, xmax=20, xip_list=10, 14, 15</literal>.
</para>
- <para>
- In releases of <productname>PostgreSQL</productname> before 13 there was
- no <type>xid8</type> type, so variants of these functions were provided
- that used <type>bigint</type>. These older functions with
- <literal>txid</literal> in their names are still supported for backward
- compatibility, but may be removed from a future
- release. See <xref linkend="functions-txid-snapshot"/>.
- </para>
-
- <table id="functions-txid-snapshot">
- <title>Transaction IDs and Snapshots (Deprecated Functions)</title>
- <tgroup cols="3">
- <thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
- </thead>
-
- <tbody>
- <row>
- <entry><literal><function>txid_current()</function></literal></entry>
- <entry><type>bigint</type></entry>
- <entry>see <function>pg_current_xact_id()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_current_if_assigned()</function></literal></entry>
- <entry><type>bigint</type></entry>
- <entry>see <function>pg_current_xact_id_if_assigned()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_current_snapshot()</function></literal></entry>
- <entry><type>txid_snapshot</type></entry>
- <entry>see <function>pg_current_snapshot()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_snapshot_xip(<parameter>txid_snapshot</parameter>)</function></literal></entry>
- <entry><type>setof bigint</type></entry>
- <entry>see <function>pg_snapshot_xip()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_snapshot_xmax(<parameter>txid_snapshot</parameter>)</function></literal></entry>
- <entry><type>bigint</type></entry>
- <entry>see <function>pg_snapshot_xmax()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_snapshot_xmin(<parameter>txid_snapshot</parameter>)</function></literal></entry>
- <entry><type>bigint</type></entry>
- <entry>see <function>pg_snapshot_xmin()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_visible_in_snapshot(<parameter>bigint</parameter>, <parameter>txid_snapshot</parameter>)</function></literal></entry>
- <entry><type>boolean</type></entry>
- <entry>see <function>pg_visible_in_snapshot()</function></entry>
- </row>
- <row>
- <entry><literal><function>txid_status(<parameter>bigint</parameter>)</function></literal></entry>
- <entry><type>text</type></entry>
- <entry>see <function>pg_xact_status()</function></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
<table id="functions-pg-snapshot-parts">
<title>Snapshot Components</title>
<tgroup cols="2">
</thead>
<tbody>
-
<row>
- <entry><type>xmin</type></entry>
+ <entry><structfield>xmin</structfield></entry>
<entry>
Lowest transaction ID that was still active. All transaction IDs
- less than <literal>xmin</literal> are either committed and visible,
+ less than <structfield>xmin</structfield> are either committed and visible,
or rolled back and dead.
</entry>
</row>
<row>
- <entry><type>xmax</type></entry>
+ <entry><structfield>xmax</structfield></entry>
<entry>
One past the highest completed transaction ID. All transaction IDs
- greater than or equal to <literal>xmax</literal> had not yet
+ greater than or equal to <structfield>xmax</structfield> had not yet
completed as of the time of the snapshot, and thus are invisible.
</entry>
</row>
<row>
- <entry><type>xip_list</type></entry>
+ <entry><structfield>xip_list</structfield></entry>
<entry>
Transactions in progress at the time of the snapshot. A transaction
- ID that is <literal>xmin <= X < xmax</literal> and not in this
- list was already completed at the time of the snapshot, and is thus
- either visible or dead according to its commit status. The list does
- not include the transaction IDs of subtransactions.
+ ID that is <literal>xmin <= <replaceable>X</replaceable> <
+ xmax</literal> and not in this list was already completed at the time
+ of the snapshot, and thus is either visible or dead according to its
+ commit status. This list does not include the transaction IDs of
+ subtransactions.
</entry>
</row>
-
</tbody>
</tgroup>
</table>
<para>
- <type>pg_snapshot</type>'s textual representation is
- <literal><replaceable>xmin</replaceable>:<replaceable>xmax</replaceable>:<replaceable>xip_list</replaceable></literal>.
- For example <literal>10:20:10,14,15</literal> means
- <literal>xmin=10, xmax=20, xip_list=10, 14, 15</literal>.
+ In releases of <productname>PostgreSQL</productname> before 13 there was
+ no <type>xid8</type> type, so variants of these functions were provided
+ that used <type>bigint</type> to represent a 64-bit XID, with a
+ correspondingly distinct snapshot data type <type>txid_snapshot</type>.
+ These older functions have <literal>txid</literal> in their names. They
+ are still supported for backward compatibility, but may be removed from a
+ future release. See <xref linkend="functions-txid-snapshot"/>.
</para>
- <para>
- <function>pg_xact_status(xid8)</function> reports the commit status of a recent
- transaction. Applications may use it to determine whether a transaction
- committed or aborted when the application and database server become
- disconnected while a <literal>COMMIT</literal> is in progress.
- The status of a transaction will be reported as either
- <literal>in progress</literal>,
- <literal>committed</literal>, or <literal>aborted</literal>, provided that the
- transaction is recent enough that the system retains the commit status
- of that transaction. If is old enough that no references to that
- transaction survive in the system and the commit status information has
- been discarded, this function will return NULL. Note that prepared
- transactions are reported as <literal>in progress</literal>; applications must
- check <link
- linkend="view-pg-prepared-xacts"><literal>pg_prepared_xacts</literal></link> if they
- need to determine whether the transaction ID belongs to a prepared transaction.
- </para>
+ <table id="functions-txid-snapshot">
+ <title>Deprecated Transaction ID and Snapshot Information Functions</title>
+ <tgroup cols="1">
+ <thead>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_current</primary>
+ </indexterm>
+ <function>txid_current</function> ()
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ See <function>pg_current_xact_id()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_current_if_assigned</primary>
+ </indexterm>
+ <function>txid_current_if_assigned</function> ()
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ See <function>pg_current_xact_id_if_assigned()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_current_snapshot</primary>
+ </indexterm>
+ <function>txid_current_snapshot</function> ()
+ <returnvalue>txid_snapshot</returnvalue>
+ </para>
+ <para>
+ See <function>pg_current_snapshot()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_snapshot_xip</primary>
+ </indexterm>
+ <function>txid_snapshot_xip</function> ( <type>txid_snapshot</type> )
+ <returnvalue>setof bigint</returnvalue>
+ </para>
+ <para>
+ See <function>pg_snapshot_xip()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_snapshot_xmax</primary>
+ </indexterm>
+ <function>txid_snapshot_xmax</function> ( <type>txid_snapshot</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ See <function>pg_snapshot_xmax()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_snapshot_xmin</primary>
+ </indexterm>
+ <function>txid_snapshot_xmin</function> ( <type>txid_snapshot</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ See <function>pg_snapshot_xmin()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_visible_in_snapshot</primary>
+ </indexterm>
+ <function>txid_visible_in_snapshot</function> ( <type>bigint</type>, <type>txid_snapshot</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ See <function>pg_visible_in_snapshot()</function>.
+ </para></entry>
+ </row>
+
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>txid_status</primary>
+ </indexterm>
+ <function>txid_status</function> ( <type>bigint</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ See <function>pg_xact_status()</function>.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
The functions shown in <xref linkend="functions-commit-timestamp"/>
- provide information about transactions that have been already committed.
- These functions mainly provide information about when the transactions
- were committed. They only provide useful data when
- <xref linkend="guc-track-commit-timestamp"/> configuration option is enabled
- and only for transactions that were committed after it was enabled.
+ provide information about when past transactions were committed.
+ They only provide useful data when the
+ <xref linkend="guc-track-commit-timestamp"/> configuration option is
+ enabled, and only for transactions that were committed after it was
+ enabled.
</para>
<table id="functions-commit-timestamp">
- <title>Committed Transaction Information</title>
- <tgroup cols="3">
+ <title>Committed Transaction Information Functions</title>
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <indexterm><primary>pg_xact_commit_timestamp</primary></indexterm>
- <literal><function>pg_xact_commit_timestamp(<parameter>xid</parameter>)</function></literal>
- </entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>get commit timestamp of a transaction</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_xact_commit_timestamp</primary>
+ </indexterm>
+ <function>pg_xact_commit_timestamp</function> ( <type>xid</type> )
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the commit timestamp of a transaction.
+ </para></entry>
</row>
<row>
- <entry>
- <indexterm><primary>pg_last_committed_xact</primary></indexterm>
- <literal><function>pg_last_committed_xact()</function></literal>
- </entry>
- <entry><parameter>xid</parameter> <type>xid</type>, <parameter>timestamp</parameter> <type>timestamp with time zone</type></entry>
- <entry>get transaction ID and commit timestamp of latest committed transaction</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_last_committed_xact</primary>
+ </indexterm>
+ <function>pg_last_committed_xact</function> ()
+ <returnvalue>record</returnvalue>
+ ( <parameter>xid</parameter> <type>xid</type>,
+ <parameter>timestamp</parameter> <type>timestamp with time zone</type> )
+ </para>
+ <para>
+ Returns the transaction ID and commit timestamp of the latest
+ committed transaction.
+ </para></entry>
</row>
</tbody>
</tgroup>
print information initialized during <command>initdb</command>, such
as the catalog version. They also show information about write-ahead
logging and checkpoint processing. This information is cluster-wide,
- and not specific to any one database. They provide most of the same
- information, from the same source, as
- <xref linkend="app-pgcontroldata"/>, although in a form better suited
- to <acronym>SQL</acronym> functions.
+ not specific to any one database. These functions provide most of the same
+ information, from the same source, as the
+ <xref linkend="app-pgcontroldata"/> application.
</para>
<table id="functions-controldata">
<title>Control Data Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <indexterm><primary>pg_control_checkpoint</primary></indexterm>
- <literal><function>pg_control_checkpoint()</function></literal>
- </entry>
- <entry><type>record</type></entry>
- <entry>
- Returns information about current checkpoint state.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_control_checkpoint</primary>
+ </indexterm>
+ <function>pg_control_checkpoint</function> ()
+ <returnvalue>record</returnvalue>
+ </para>
+ <para>
+ Returns information about current checkpoint state, as shown in
+ <xref linkend="functions-pg-control-checkpoint"/>.
+ </para></entry>
</row>
<row>
- <entry>
- <indexterm><primary>pg_control_system</primary></indexterm>
- <literal><function>pg_control_system()</function></literal>
- </entry>
- <entry><type>record</type></entry>
- <entry>
- Returns information about current control file state.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_control_system</primary>
+ </indexterm>
+ <function>pg_control_system</function> ()
+ <returnvalue>record</returnvalue>
+ </para>
+ <para>
+ Returns information about current control file state, as shown in
+ <xref linkend="functions-pg-control-system"/>.
+ </para></entry>
</row>
<row>
- <entry>
- <indexterm><primary>pg_control_init</primary></indexterm>
- <literal><function>pg_control_init()</function></literal>
- </entry>
- <entry><type>record</type></entry>
- <entry>
- Returns information about cluster initialization state.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_control_init</primary>
+ </indexterm>
+ <function>pg_control_init</function> ()
+ <returnvalue>record</returnvalue>
+ </para>
+ <para>
+ Returns information about cluster initialization state, as shown in
+ <xref linkend="functions-pg-control-init"/>.
+ </para></entry>
</row>
<row>
- <entry>
- <indexterm><primary>pg_control_recovery</primary></indexterm>
- <literal><function>pg_control_recovery()</function></literal>
- </entry>
- <entry><type>record</type></entry>
- <entry>
- Returns information about recovery state.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_control_recovery</primary>
+ </indexterm>
+ <function>pg_control_recovery</function> ()
+ <returnvalue>record</returnvalue>
+ </para>
+ <para>
+ Returns information about recovery state, as shown in
+ <xref linkend="functions-pg-control-recovery"/>.
+ </para></entry>
</row>
-
</tbody>
</tgroup>
</table>
- <para>
- <function>pg_control_checkpoint</function> returns a record, shown in
- <xref linkend="functions-pg-control-checkpoint"/>
- </para>
-
<table id="functions-pg-control-checkpoint">
- <title><function>pg_control_checkpoint</function> Columns</title>
+ <title><function>pg_control_checkpoint</function> Output Columns</title>
<tgroup cols="2">
<thead>
<row>
<tbody>
<row>
- <entry><literal>checkpoint_lsn</literal></entry>
+ <entry><structfield>checkpoint_lsn</structfield></entry>
<entry><type>pg_lsn</type></entry>
</row>
<row>
- <entry><literal>redo_lsn</literal></entry>
+ <entry><structfield>redo_lsn</structfield></entry>
<entry><type>pg_lsn</type></entry>
</row>
<row>
- <entry><literal>redo_wal_file</literal></entry>
+ <entry><structfield>redo_wal_file</structfield></entry>
<entry><type>text</type></entry>
</row>
<row>
- <entry><literal>timeline_id</literal></entry>
+ <entry><structfield>timeline_id</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>prev_timeline_id</literal></entry>
+ <entry><structfield>prev_timeline_id</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>full_page_writes</literal></entry>
+ <entry><structfield>full_page_writes</structfield></entry>
<entry><type>boolean</type></entry>
</row>
<row>
- <entry><literal>next_xid</literal></entry>
+ <entry><structfield>next_xid</structfield></entry>
<entry><type>text</type></entry>
</row>
<row>
- <entry><literal>next_oid</literal></entry>
+ <entry><structfield>next_oid</structfield></entry>
<entry><type>oid</type></entry>
</row>
<row>
- <entry><literal>next_multixact_id</literal></entry>
+ <entry><structfield>next_multixact_id</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>next_multi_offset</literal></entry>
+ <entry><structfield>next_multi_offset</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>oldest_xid</literal></entry>
+ <entry><structfield>oldest_xid</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>oldest_xid_dbid</literal></entry>
+ <entry><structfield>oldest_xid_dbid</structfield></entry>
<entry><type>oid</type></entry>
</row>
<row>
- <entry><literal>oldest_active_xid</literal></entry>
+ <entry><structfield>oldest_active_xid</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>oldest_multi_xid</literal></entry>
+ <entry><structfield>oldest_multi_xid</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>oldest_multi_dbid</literal></entry>
+ <entry><structfield>oldest_multi_dbid</structfield></entry>
<entry><type>oid</type></entry>
</row>
<row>
- <entry><literal>oldest_commit_ts_xid</literal></entry>
+ <entry><structfield>oldest_commit_ts_xid</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>newest_commit_ts_xid</literal></entry>
+ <entry><structfield>newest_commit_ts_xid</structfield></entry>
<entry><type>xid</type></entry>
</row>
<row>
- <entry><literal>checkpoint_time</literal></entry>
+ <entry><structfield>checkpoint_time</structfield></entry>
<entry><type>timestamp with time zone</type></entry>
</row>
</tgroup>
</table>
- <para>
- <function>pg_control_system</function> returns a record, shown in
- <xref linkend="functions-pg-control-system"/>
- </para>
-
<table id="functions-pg-control-system">
- <title><function>pg_control_system</function> Columns</title>
+ <title><function>pg_control_system</function> Output Columns</title>
<tgroup cols="2">
<thead>
<row>
<tbody>
<row>
- <entry><literal>pg_control_version</literal></entry>
+ <entry><structfield>pg_control_version</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>catalog_version_no</literal></entry>
+ <entry><structfield>catalog_version_no</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>system_identifier</literal></entry>
+ <entry><structfield>system_identifier</structfield></entry>
<entry><type>bigint</type></entry>
</row>
<row>
- <entry><literal>pg_control_last_modified</literal></entry>
+ <entry><structfield>pg_control_last_modified</structfield></entry>
<entry><type>timestamp with time zone</type></entry>
</row>
</tgroup>
</table>
- <para>
- <function>pg_control_init</function> returns a record, shown in
- <xref linkend="functions-pg-control-init"/>
- </para>
-
<table id="functions-pg-control-init">
- <title><function>pg_control_init</function> Columns</title>
+ <title><function>pg_control_init</function> Output Columns</title>
<tgroup cols="2">
<thead>
<row>
<tbody>
<row>
- <entry><literal>max_data_alignment</literal></entry>
+ <entry><structfield>max_data_alignment</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>database_block_size</literal></entry>
+ <entry><structfield>database_block_size</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>blocks_per_segment</literal></entry>
+ <entry><structfield>blocks_per_segment</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>wal_block_size</literal></entry>
+ <entry><structfield>wal_block_size</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>bytes_per_wal_segment</literal></entry>
+ <entry><structfield>bytes_per_wal_segment</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>max_identifier_length</literal></entry>
+ <entry><structfield>max_identifier_length</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>max_index_columns</literal></entry>
+ <entry><structfield>max_index_columns</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>max_toast_chunk_size</literal></entry>
+ <entry><structfield>max_toast_chunk_size</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>large_object_chunk_size</literal></entry>
+ <entry><structfield>large_object_chunk_size</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>float8_pass_by_value</literal></entry>
+ <entry><structfield>float8_pass_by_value</structfield></entry>
<entry><type>boolean</type></entry>
</row>
<row>
- <entry><literal>data_page_checksum_version</literal></entry>
+ <entry><structfield>data_page_checksum_version</structfield></entry>
<entry><type>integer</type></entry>
</row>
</tgroup>
</table>
- <para>
- <function>pg_control_recovery</function> returns a record, shown in
- <xref linkend="functions-pg-control-recovery"/>
- </para>
-
<table id="functions-pg-control-recovery">
- <title><function>pg_control_recovery</function> Columns</title>
+ <title><function>pg_control_recovery</function> Output Columns</title>
<tgroup cols="2">
<thead>
<row>
<tbody>
<row>
- <entry><literal>min_recovery_end_lsn</literal></entry>
+ <entry><structfield>min_recovery_end_lsn</structfield></entry>
<entry><type>pg_lsn</type></entry>
</row>
<row>
- <entry><literal>min_recovery_end_timeline</literal></entry>
+ <entry><structfield>min_recovery_end_timeline</structfield></entry>
<entry><type>integer</type></entry>
</row>
<row>
- <entry><literal>backup_start_lsn</literal></entry>
+ <entry><structfield>backup_start_lsn</structfield></entry>
<entry><type>pg_lsn</type></entry>
</row>
<row>
- <entry><literal>backup_end_lsn</literal></entry>
+ <entry><structfield>backup_end_lsn</structfield></entry>
<entry><type>pg_lsn</type></entry>
</row>
<row>
- <entry><literal>end_of_backup_record_required</literal></entry>
+ <entry><structfield>end_of_backup_record_required</structfield></entry>
<entry><type>boolean</type></entry>
</row>
<sect2 id="functions-admin-set">
<title>Configuration Settings Functions</title>
+ <indexterm>
+ <primary>SET</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>SHOW</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>configuration</primary>
+ <secondary sortas="server">of the server</secondary>
+ <tertiary>functions</tertiary>
+ </indexterm>
+
<para>
<xref linkend="functions-admin-set-table"/> shows the functions
available to query and alter run-time configuration parameters.
<table id="functions-admin-set-table">
<title>Configuration Settings Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para>
+ <para>
+ Example(s)
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>current_setting</primary>
</indexterm>
- <literal><function>current_setting(<parameter>setting_name</parameter> [, <parameter>missing_ok</parameter> ])</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>get current value of setting</entry>
+ <function>current_setting</function> ( <parameter>setting_name</parameter> <type>text</type> <optional>, <parameter>missing_ok</parameter> <type>boolean</type> </optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the current value of the
+ setting <parameter>setting_name</parameter>. If there is no such
+ setting, <function>current_setting</function> throws an error
+ unless <parameter>missing_ok</parameter> is supplied and
+ is <literal>true</literal>. This function corresponds to
+ the <acronym>SQL</acronym> command <command>SHOW</command>.
+ </para>
+ <para>
+ <literal>current_setting('datestyle')</literal>
+ <returnvalue>ISO, MDY</returnvalue>
+ </para></entry>
</row>
+
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>set_config</primary>
</indexterm>
- <literal><function>set_config(<parameter>setting_name</parameter>,
- <parameter>new_value</parameter>,
- <parameter>is_local</parameter>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>set parameter and return new value</entry>
+ <function>set_config</function> (
+ <parameter>setting_name</parameter> <type>text</type>,
+ <parameter>new_value</parameter> <type>text</type>,
+ <parameter>is_local</parameter> <type>boolean</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Sets the parameter <parameter>setting_name</parameter>
+ to <parameter>new_value</parameter>, and returns that value.
+ If <parameter>is_local</parameter> is <literal>true</literal>, the new
+ value will only apply for the current transaction. If you want the new
+ value to apply for the current session, use <literal>false</literal>
+ instead. This function corresponds to the SQL
+ command <command>SET</command>.
+ </para>
+ <para>
+ <literal>set_config('log_statement_stats', 'off', false)</literal>
+ <returnvalue>off</returnvalue>
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <indexterm>
- <primary>SET</primary>
- </indexterm>
-
- <indexterm>
- <primary>SHOW</primary>
- </indexterm>
-
- <indexterm>
- <primary>configuration</primary>
- <secondary sortas="server">of the server</secondary>
- <tertiary>functions</tertiary>
- </indexterm>
-
- <para>
- The function <function>current_setting</function> yields the
- current value of the setting <parameter>setting_name</parameter>.
- It corresponds to the <acronym>SQL</acronym> command
- <command>SHOW</command>. An example:
-<programlisting>
-SELECT current_setting('datestyle');
-
- current_setting
------------------
- ISO, MDY
-(1 row)
-</programlisting>
-
- If there is no setting named <parameter>setting_name</parameter>,
- <function>current_setting</function> throws an error
- unless <parameter>missing_ok</parameter> is supplied and is
- <literal>true</literal>.
- </para>
-
- <para>
- <function>set_config</function> sets the parameter
- <parameter>setting_name</parameter> to
- <parameter>new_value</parameter>. If
- <parameter>is_local</parameter> is <literal>true</literal>, the
- new value will only apply to the current transaction. If you want
- the new value to apply for the current session, use
- <literal>false</literal> instead. The function corresponds to the
- SQL command <command>SET</command>. An example:
-<programlisting>
-SELECT set_config('log_statement_stats', 'off', false);
-
- set_config
-------------
- off
-(1 row)
-</programlisting>
- </para>
-
</sect2>
<sect2 id="functions-admin-signal">
<title>Server Signaling Functions</title>
- <indexterm>
- <primary>pg_cancel_backend</primary>
- </indexterm>
- <indexterm>
- <primary>pg_reload_conf</primary>
- </indexterm>
- <indexterm>
- <primary>pg_rotate_logfile</primary>
- </indexterm>
- <indexterm>
- <primary>pg_terminate_backend</primary>
- </indexterm>
-
<indexterm>
<primary>signal</primary>
<secondary sortas="backend">backend processes</secondary>
<command>GRANT</command>, with noted exceptions.
</para>
+ <para>
+ Each of these functions returns <literal>true</literal> if
+ successful and <literal>false</literal> otherwise.
+ </para>
+
<table id="functions-admin-signal-table">
<title>Server Signaling Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_cancel_backend(<parameter>pid</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Cancel a backend's current query. This is also allowed if the
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_cancel_backend</primary>
+ </indexterm>
+ <function>pg_cancel_backend</function> ( <parameter>pid</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Cancels the current query of the session whose backend process has the
+ specified process ID. This is also allowed if the
calling role is a member of the role whose backend is being canceled or
the calling role has been granted <literal>pg_signal_backend</literal>,
however only superusers can cancel superuser backends.
- </entry>
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_reload_conf()</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Cause server processes to reload their configuration files</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_reload_conf</primary>
+ </indexterm>
+ <function>pg_reload_conf</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Causes all processes of the <productname>PostgreSQL</productname>
+ server to reload their configuration files. (This is initiated by
+ sending a <systemitem>SIGHUP</systemitem> signal to the postmaster
+ process, which in turn sends <systemitem>SIGHUP</systemitem> to each
+ of its children.)
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_rotate_logfile()</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Rotate server's log file</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_rotate_logfile</primary>
+ </indexterm>
+ <function>pg_rotate_logfile</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Signals the log-file manager to switch to a new output file
+ immediately. This works only when the built-in log collector is
+ running, since otherwise there is no log-file manager subprocess.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_terminate_backend(<parameter>pid</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Terminate a backend. This is also allowed if the calling role
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_terminate_backend</primary>
+ </indexterm>
+ <function>pg_terminate_backend</function> ( <parameter>pid</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Terminates the session whose backend process has the
+ specified process ID. This is also allowed if the calling role
is a member of the role whose backend is being terminated or the
calling role has been granted <literal>pg_signal_backend</literal>,
however only superusers can terminate superuser backends.
- </entry>
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- Each of these functions returns <literal>true</literal> if
- successful and <literal>false</literal> otherwise.
- </para>
-
<para>
<function>pg_cancel_backend</function> and <function>pg_terminate_backend</function>
send signals (<systemitem>SIGINT</systemitem> or <systemitem>SIGTERM</systemitem>
<structname>pg_stat_activity</structname> view.
</para>
- <para>
- <function>pg_reload_conf</function> sends a <systemitem>SIGHUP</systemitem> signal
- to the server, causing configuration files
- to be reloaded by all server processes.
- </para>
-
- <para>
- <function>pg_rotate_logfile</function> signals the log-file manager to switch
- to a new output file immediately. This works only when the built-in
- log collector is running, since otherwise there is no log-file manager
- subprocess.
- </para>
-
</sect2>
<sect2 id="functions-admin-backup">
<indexterm>
<primary>backup</primary>
</indexterm>
- <indexterm>
- <primary>pg_create_restore_point</primary>
- </indexterm>
- <indexterm>
- <primary>pg_current_wal_flush_lsn</primary>
- </indexterm>
- <indexterm>
- <primary>pg_current_wal_insert_lsn</primary>
- </indexterm>
- <indexterm>
- <primary>pg_current_wal_lsn</primary>
- </indexterm>
- <indexterm>
- <primary>pg_start_backup</primary>
- </indexterm>
- <indexterm>
- <primary>pg_stop_backup</primary>
- </indexterm>
- <indexterm>
- <primary>pg_is_in_backup</primary>
- </indexterm>
- <indexterm>
- <primary>pg_backup_start_time</primary>
- </indexterm>
- <indexterm>
- <primary>pg_switch_wal</primary>
- </indexterm>
- <indexterm>
- <primary>pg_walfile_name</primary>
- </indexterm>
- <indexterm>
- <primary>pg_walfile_name_offset</primary>
- </indexterm>
- <indexterm>
- <primary>pg_wal_lsn_diff</primary>
- </indexterm>
<para>
The functions shown in <xref
and <function>pg_wal_lsn_diff</function>).
</para>
+ <para>
+ For details about proper usage of these functions, see
+ <xref linkend="continuous-archiving"/>.
+ </para>
+
<table id="functions-admin-backup-table">
<title>Backup Control Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_create_restore_point(<parameter>name</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Create a named point for performing restore (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_create_restore_point</primary>
+ </indexterm>
+ <function>pg_create_restore_point</function> ( <parameter>name</parameter> <type>text</type> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Creates a named marker record in the write-ahead log that can later be
+ used as a recovery target, and returns the corresponding write-ahead
+ log location. The given name can then be used with
+ <xref linkend="guc-recovery-target-name"/> to specify the point up to
+ which recovery will proceed. Avoid creating multiple restore points
+ with the same name, since recovery will stop at the first one whose
+ name matches the recovery target.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_current_wal_flush_lsn()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Get current write-ahead log flush location</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_wal_flush_lsn</primary>
+ </indexterm>
+ <function>pg_current_wal_flush_lsn</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the current write-ahead log flush location (see notes below).
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_current_wal_insert_lsn()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Get current write-ahead log insert location</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_wal_insert_lsn</primary>
+ </indexterm>
+ <function>pg_current_wal_insert_lsn</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the current write-ahead log insert location (see notes below).
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_current_wal_lsn()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Get current write-ahead log write location</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_current_wal_lsn</primary>
+ </indexterm>
+ <function>pg_current_wal_lsn</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the current write-ahead log write location (see notes below).
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_start_backup(<parameter>label</parameter> <type>text</type> <optional>, <parameter>fast</parameter> <type>boolean</type> <optional>, <parameter>exclusive</parameter> <type>boolean</type> </optional></optional>)</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Prepare for performing on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_start_backup</primary>
+ </indexterm>
+ <function>pg_start_backup</function> (
+ <parameter>label</parameter> <type>text</type>
+ <optional>, <parameter>fast</parameter> <type>boolean</type>
+ <optional>, <parameter>exclusive</parameter> <type>boolean</type>
+ </optional></optional> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Prepares the server to begin an on-line backup. The only required
+ parameter is an arbitrary user-defined label for the backup.
+ (Typically this would be the name under which the backup dump file
+ will be stored.)
+ If the optional second parameter is given as <literal>true</literal>,
+ it specifies executing <function>pg_start_backup</function> as quickly
+ as possible. This forces an immediate checkpoint which will cause a
+ spike in I/O operations, slowing any concurrently executing queries.
+ The optional third parameter specifies whether to perform an exclusive
+ or non-exclusive backup (default is exclusive).
+ </para>
+ <para>
+ When used in exclusive mode, this function writes a backup label file
+ (<filename>backup_label</filename>) and, if there are any links in
+ the <filename>pg_tblspc/</filename> directory, a tablespace map file
+ (<filename>tablespace_map</filename>) into the database cluster's data
+ directory, then performs a checkpoint, and then returns the backup's
+ starting write-ahead log location. (The user can ignore this
+ result value, but it is provided in case it is useful.) When used in
+ non-exclusive mode, the contents of these files are instead returned
+ by the <function>pg_stop_backup</function> function, and should be
+ copied to the backup area by the user.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_stop_backup()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Finish performing exclusive on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stop_backup</primary>
+ </indexterm>
+ <function>pg_stop_backup</function> (
+ <parameter>exclusive</parameter> <type>boolean</type>
+ <optional>, <parameter>wait_for_archive</parameter> <type>boolean</type>
+ </optional> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>lsn</parameter> <type>pg_lsn</type>,
+ <parameter>labelfile</parameter> <type>text</type>,
+ <parameter>spcmapfile</parameter> <type>text</type> )
+ </para>
+ <para>
+ Finishes performing an exclusive or non-exclusive on-line backup.
+ The <parameter>exclusive</parameter> parameter must match the
+ previous <function>pg_start_backup</function> call.
+ In an exclusive backup, <function>pg_stop_backup</function> removes
+ the backup label file and, if it exists, the tablespace map file
+ created by <function>pg_start_backup</function>. In a non-exclusive
+ backup, the desired contents of these files are returned as part of
+ the result of the function, and should be written to files in the
+ backup area (not in the data directory).
+ </para>
+ <para>
+ There is an optional second parameter of type <type>boolean</type>.
+ If false, the function will return immediately after the backup is
+ completed, without waiting for WAL to be archived. This behavior is
+ only useful with backup software that independently monitors WAL
+ archiving. Otherwise, WAL required to make the backup consistent might
+ be missing and make the backup useless. By default or when this
+ parameter is true, <function>pg_stop_backup</function> will wait for
+ WAL to be archived when archiving is enabled. (On a standby, this
+ means that it will wait only when <varname>archive_mode</varname> =
+ <literal>always</literal>. If write activity on the primary is low,
+ it may be useful to run <function>pg_switch_wal</function> on the
+ primary in order to trigger an immediate segment switch.)
+ </para>
+ <para>
+ When executed on a primary, this function also creates a backup
+ history file in the write-ahead log archive area. The history file
+ includes the label given to <function>pg_start_backup</function>, the
+ starting and ending write-ahead log locations for the backup, and the
+ starting and ending times of the backup. After recording the ending
+ location, the current write-ahead log insertion point is automatically
+ advanced to the next write-ahead log file, so that the ending
+ write-ahead log file can be archived immediately to complete the
+ backup.
+ </para>
+ <para>
+ The result of the function is a single record.
+ The <parameter>lsn</parameter> column holds the backup's ending
+ write-ahead log location (which again can be ignored). The second and
+ third columns are <literal>NULL</literal> when ending an exclusive
+ backup; after a non-exclusive backup they hold the desired contents of
+ the label and tablespace map files.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_stop_backup(<parameter>exclusive</parameter> <type>boolean</type> <optional>, <parameter>wait_for_archive</parameter> <type>boolean</type> </optional>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>Finish performing exclusive or non-exclusive on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <function>pg_stop_backup</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Finishes performing an exclusive on-line backup. This simplified
+ version is equivalent to <literal>pg_stop_backup(true,
+ true)</literal>, except that it only returns the <type>pg_lsn</type>
+ result.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_is_in_backup()</function></literal>
- </entry>
- <entry><type>bool</type></entry>
- <entry>True if an on-line exclusive backup is still in progress.</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_is_in_backup</primary>
+ </indexterm>
+ <function>pg_is_in_backup</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if an on-line exclusive backup is in progress.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_backup_start_time()</function></literal>
- </entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Get start time of an on-line exclusive backup in progress.</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_backup_start_time</primary>
+ </indexterm>
+ <function>pg_backup_start_time</function> ()
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the start time of the current on-line exclusive backup if one
+ is in progress, otherwise <literal>NULL</literal>.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_switch_wal()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Force switch to a new write-ahead log file (restricted to superusers by default, but other users can be granted EXECUTE to run the function)</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_switch_wal</primary>
+ </indexterm>
+ <function>pg_switch_wal</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Forces the server to switch to a new write-ahead log file, which
+ allows the current file to be archived (assuming you are using
+ continuous archiving). The result is the ending write-ahead log
+ location plus 1 within the just-completed write-ahead log file. If
+ there has been no write-ahead log activity since the last write-ahead
+ log switch, <function>pg_switch_wal</function> does nothing and
+ returns the start location of the write-ahead log file currently in
+ use.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_walfile_name(<parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>Convert write-ahead log location to file name</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_walfile_name</primary>
+ </indexterm>
+ <function>pg_walfile_name</function> ( <parameter>lsn</parameter> <type>pg_lsn</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Converts a write-ahead log location to the name of the WAL file
+ holding that location.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_walfile_name_offset(<parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal>
- </entry>
- <entry><type>text</type>, <type>integer</type></entry>
- <entry>Convert write-ahead log location to file name and decimal byte offset within file</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_walfile_name_offset</primary>
+ </indexterm>
+ <function>pg_walfile_name_offset</function> ( <parameter>lsn</parameter> <type>pg_lsn</type> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>file_name</parameter> <type>text</type>,
+ <parameter>file_offset</parameter> <type>integer</type> )
+ </para>
+ <para>
+ Converts a write-ahead log location to a WAL file name and byte offset
+ within that file.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_wal_lsn_diff(<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal>
- </entry>
- <entry><type>numeric</type></entry>
- <entry>Calculate the difference between two write-ahead log locations</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_wal_lsn_diff</primary>
+ </indexterm>
+ <function>pg_wal_lsn_diff</function> ( <parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>lsn</parameter> <type>pg_lsn</type> )
+ <returnvalue>numeric</returnvalue>
+ </para>
+ <para>
+ Calculates the difference in bytes between two write-ahead log
+ locations. This can be used
+ with <structname>pg_stat_replication</structname> or some of the
+ functions shown in <xref linkend="functions-admin-backup-table"/> to
+ get the replication lag.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
- <function>pg_start_backup</function> accepts an arbitrary user-defined label for
- the backup. (Typically this would be the name under which the backup dump
- file will be stored.) When used in exclusive mode, the function writes a
- backup label file (<filename>backup_label</filename>) and, if there are any links
- in the <filename>pg_tblspc/</filename> directory, a tablespace map file
- (<filename>tablespace_map</filename>) into the database cluster's data directory,
- performs a checkpoint, and then returns the backup's starting write-ahead
- log location as text. The user can ignore this result value, but it is
- provided in case it is useful. When used in non-exclusive mode, the
- contents of these files are instead returned by the
- <function>pg_stop_backup</function> function, and should be written to the backup
- by the caller.
-
-<programlisting>
-postgres=# select pg_start_backup('label_goes_here');
- pg_start_backup
------------------
- 0/D4445B8
-(1 row)
-</programlisting>
- There is an optional second parameter of type <type>boolean</type>. If <literal>true</literal>,
- it specifies executing <function>pg_start_backup</function> as quickly as
- possible. This forces an immediate checkpoint which will cause a
- spike in I/O operations, slowing any concurrently executing queries.
- </para>
-
- <para>
- In an exclusive backup, <function>pg_stop_backup</function> removes the label file
- and, if it exists, the <filename>tablespace_map</filename> file created by
- <function>pg_start_backup</function>. In a non-exclusive backup, the contents of
- the <filename>backup_label</filename> and <filename>tablespace_map</filename> are returned
- in the result of the function, and should be written to files in the
- backup (and not in the data directory). There is an optional second
- parameter of type <type>boolean</type>. If false, the <function>pg_stop_backup</function>
- will return immediately after the backup is completed without waiting for
- WAL to be archived. This behavior is only useful for backup
- software which independently monitors WAL archiving. Otherwise, WAL
- required to make the backup consistent might be missing and make the backup
- useless. When this parameter is set to true, <function>pg_stop_backup</function>
- will wait for WAL to be archived when archiving is enabled; on the standby,
- this means that it will wait only when <varname>archive_mode = always</varname>.
- If write activity on the primary is low, it may be useful to run
- <function>pg_switch_wal</function> on the primary in order to trigger
- an immediate segment switch.
- </para>
-
- <para>
- When executed on a primary, the function also creates a backup history file
- in the write-ahead log
- archive area. The history file includes the label given to
- <function>pg_start_backup</function>, the starting and ending write-ahead log locations for
- the backup, and the starting and ending times of the backup. The return
- value is the backup's ending write-ahead log location (which again
- can be ignored). After recording the ending location, the current
- write-ahead log insertion
- point is automatically advanced to the next write-ahead log file, so that the
- ending write-ahead log file can be archived immediately to complete the backup.
- </para>
-
- <para>
- <function>pg_switch_wal</function> moves to the next write-ahead log file, allowing the
- current file to be archived (assuming you are using continuous archiving).
- The return value is the ending write-ahead log location + 1 within the just-completed write-ahead log file.
- If there has been no write-ahead log activity since the last write-ahead log switch,
- <function>pg_switch_wal</function> does nothing and returns the start location
- of the write-ahead log file currently in use.
- </para>
-
- <para>
- <function>pg_create_restore_point</function> creates a named write-ahead log
- record that can be used as recovery target, and returns the corresponding
- write-ahead log location. The given name can then be used with
- <xref linkend="guc-recovery-target-name"/> to specify the point up to which
- recovery will proceed. Avoid creating multiple restore points with the
- same name, since recovery will stop at the first one whose name matches
- the recovery target.
- </para>
-
- <para>
- <function>pg_current_wal_lsn</function> displays the current write-ahead log write
- location in the same format used by the above functions. Similarly,
- <function>pg_current_wal_insert_lsn</function> displays the current write-ahead log
- insertion location and <function>pg_current_wal_flush_lsn</function> displays the
- current write-ahead log flush location. The insertion location is the <quote>logical</quote>
- end of the write-ahead log at any instant, while the write location is the end of
- what has actually been written out from the server's internal buffers and flush
- location is the location guaranteed to be written to durable storage. The write
- location is the end of what can be examined from outside the server, and is usually
- what you want if you are interested in archiving partially-complete write-ahead log
- files. The insertion and flush locations are made available primarily for server
- debugging purposes. These are both read-only operations and do not
- require superuser permissions.
+ <function>pg_current_wal_lsn</function> displays the current write-ahead
+ log write location in the same format used by the above functions.
+ Similarly, <function>pg_current_wal_insert_lsn</function> displays the
+ current write-ahead log insertion location
+ and <function>pg_current_wal_flush_lsn</function> displays the current
+ write-ahead log flush location. The insertion location is
+ the <quote>logical</quote> end of the write-ahead log at any instant,
+ while the write location is the end of what has actually been written out
+ from the server's internal buffers, and the flush location is the last
+ location known to be written to durable storage. The write location is the
+ end of what can be examined from outside the server, and is usually what
+ you want if you are interested in archiving partially-complete write-ahead
+ log files. The insertion and flush locations are made available primarily
+ for server debugging purposes. These are all read-only operations and do
+ not require superuser permissions.
</para>
<para>
You can use <function>pg_walfile_name_offset</function> to extract the
- corresponding write-ahead log file name and byte offset from the results of any of the
- above functions. For example:
+ corresponding write-ahead log file name and byte offset from
+ a <type>pg_lsn</type> value. For example:
<programlisting>
postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup());
- file_name | file_offset
+ file_name | file_offset
--------------------------+-------------
00000001000000000000000D | 4039624
(1 row)
needs to be archived.
</para>
- <para>
- <function>pg_wal_lsn_diff</function> calculates the difference in bytes
- between two write-ahead log locations. It can be used with
- <structname>pg_stat_replication</structname> or some functions shown in
- <xref linkend="functions-admin-backup-table"/> to get the replication lag.
- </para>
-
- <para>
- For details about proper usage of these functions, see
- <xref linkend="continuous-archiving"/>.
- </para>
-
</sect2>
<sect2 id="functions-recovery-control">
<title>Recovery Control Functions</title>
- <indexterm>
- <primary>pg_is_in_recovery</primary>
- </indexterm>
- <indexterm>
- <primary>pg_last_wal_receive_lsn</primary>
- </indexterm>
- <indexterm>
- <primary>pg_last_wal_replay_lsn</primary>
- </indexterm>
- <indexterm>
- <primary>pg_last_xact_replay_timestamp</primary>
- </indexterm>
-
<para>
The functions shown in <xref
linkend="functions-recovery-info-table"/> provide information
- about the current status of the standby.
+ about the current status of a standby server.
These functions may be executed both during recovery and in normal running.
</para>
<table id="functions-recovery-info-table">
<title>Recovery Information Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_is_in_recovery()</function></literal>
- </entry>
- <entry><type>bool</type></entry>
- <entry>True if recovery is still in progress.
- </entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_last_wal_receive_lsn()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Get last write-ahead log location received and synced to disk by
- streaming replication. While streaming replication is in progress
- this will increase monotonically. If recovery has completed this will
- remain static at
- the value of the last WAL record received and synced to disk during
- recovery. If streaming replication is disabled, or if it has not yet
- started, the function returns NULL.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_is_in_recovery</primary>
+ </indexterm>
+ <function>pg_is_in_recovery</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if recovery is still in progress.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_last_wal_replay_lsn()</function></literal>
- </entry>
- <entry><type>pg_lsn</type></entry>
- <entry>Get last write-ahead log location replayed during recovery.
- If recovery is still in progress this will increase monotonically.
- If recovery has completed then this value will remain static at
- the value of the last WAL record applied during that recovery.
- When the server has been started normally without recovery
- the function returns NULL.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_last_wal_receive_lsn</primary>
+ </indexterm>
+ <function>pg_last_wal_receive_lsn</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the last write-ahead log location that has been received and
+ synced to disk by streaming replication. While streaming replication
+ is in progress this will increase monotonically. If recovery has
+ completed then this will remain static at the location of the last WAL
+ record received and synced to disk during recovery. If streaming
+ replication is disabled, or if it has not yet started, the function
+ returns <literal>NULL</literal>.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_last_xact_replay_timestamp()</function></literal>
- </entry>
- <entry><type>timestamp with time zone</type></entry>
- <entry>Get time stamp of last transaction replayed during recovery.
- This is the time at which the commit or abort WAL record for that
- transaction was generated on the primary.
- If no transactions have been replayed during recovery, this function
- returns NULL. Otherwise, if recovery is still in progress this will
- increase monotonically. If recovery has completed then this value will
- remain static at the value of the last transaction applied during that
- recovery. When the server has been started normally without recovery
- the function returns NULL.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_last_wal_replay_lsn</primary>
+ </indexterm>
+ <function>pg_last_wal_replay_lsn</function> ()
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the last write-ahead log location that has been replayed
+ during recovery. If recovery is still in progress this will increase
+ monotonically. If recovery has completed then this will remain
+ static at the location of the last WAL record applied during recovery.
+ When the server has been started normally without recovery, the
+ function returns <literal>NULL</literal>.
+ </para></entry>
</row>
- </tbody>
- </tgroup>
- </table>
- <indexterm>
- <primary>pg_is_wal_replay_paused</primary>
- </indexterm>
- <indexterm>
- <primary>pg_promote</primary>
- </indexterm>
- <indexterm>
- <primary>pg_wal_replay_pause</primary>
- </indexterm>
- <indexterm>
- <primary>pg_wal_replay_resume</primary>
- </indexterm>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_last_xact_replay_timestamp</primary>
+ </indexterm>
+ <function>pg_last_xact_replay_timestamp</function> ()
+ <returnvalue>timestamp with time zone</returnvalue>
+ </para>
+ <para>
+ Returns the time stamp of the last transaction replayed during
+ recovery. This is the time at which the commit or abort WAL record
+ for that transaction was generated on the primary. If no transactions
+ have been replayed during recovery, the function
+ returns <literal>NULL</literal>. Otherwise, if recovery is still in
+ progress this will increase monotonically. If recovery has completed
+ then this will remain static at the time of the last transaction
+ applied during recovery. When the server has been started normally
+ without recovery, the function returns <literal>NULL</literal>.
+ </para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<para>
The functions shown in <xref
<table id="functions-recovery-control-table">
<title>Recovery Control Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_is_wal_replay_paused()</function></literal>
- </entry>
- <entry><type>bool</type></entry>
- <entry>True if recovery is paused.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_is_wal_replay_paused</primary>
+ </indexterm>
+ <function>pg_is_wal_replay_paused</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if recovery is paused.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_promote(<parameter>wait</parameter> <type>boolean</type> DEFAULT true, <parameter>wait_seconds</parameter> <type>integer</type> DEFAULT 60)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>
- Promotes a physical standby server. With <parameter>wait</parameter>
- set to <literal>true</literal> (the default), the function waits until
- promotion is completed or <parameter>wait_seconds</parameter> seconds
- have passed, and returns <literal>true</literal> if promotion is
- successful and <literal>false</literal> otherwise.
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_promote</primary>
+ </indexterm>
+ <function>pg_promote</function> ( <parameter>wait</parameter> <type>boolean</type> <literal>DEFAULT</literal> <literal>true</literal>, <parameter>wait_seconds</parameter> <type>integer</type> <literal>DEFAULT</literal> <literal>60</literal> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Promotes a standby server to primary status.
+ With <parameter>wait</parameter> set to <literal>true</literal> (the
+ default), the function waits until promotion is completed
+ or <parameter>wait_seconds</parameter> seconds have passed, and
+ returns <literal>true</literal> if promotion is successful
+ and <literal>false</literal> otherwise.
If <parameter>wait</parameter> is set to <literal>false</literal>, the
- function returns <literal>true</literal> immediately after sending
- <literal>SIGUSR1</literal> to the postmaster to trigger the promotion.
+ function returns <literal>true</literal> immediately after sending a
+ <literal>SIGUSR1</literal> signal to the postmaster to trigger
+ promotion.
+ </para>
+ <para>
This function is restricted to superusers by default, but other users
can be granted EXECUTE to run the function.
- </entry>
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_wal_replay_pause()</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Pauses recovery immediately (restricted to superusers by default, but other users can be granted EXECUTE to run the function).
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_wal_replay_pause</primary>
+ </indexterm>
+ <function>pg_wal_replay_pause</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Pauses recovery. While recovery is paused, no further database
+ changes are applied. If hot standby is active, all new queries will
+ see the same consistent snapshot of the database, and no further query
+ conflicts will be generated until recovery is resumed.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_wal_replay_resume()</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Restarts recovery if it was paused (restricted to superusers by default, but other users can be granted EXECUTE to run the function).
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_wal_replay_resume</primary>
+ </indexterm>
+ <function>pg_wal_replay_resume</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Restarts recovery if it was paused.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- While recovery is paused no further database changes are applied.
- If in hot standby, all new queries will see the same consistent snapshot
- of the database, and no further query conflicts will be generated until
- recovery is resumed.
- </para>
-
<para>
<function>pg_wal_replay_pause</function> and
<function>pg_wal_replay_resume</function> cannot be executed while
a promotion is ongoing. If a promotion is triggered while recovery
- is paused, the paused state ends and a promotion continues.
+ is paused, the paused state ends and promotion continues.
</para>
<para>
If streaming replication is disabled, the paused state may continue
- indefinitely without problem. While streaming replication is in
- progress WAL records will continue to be received, which will
+ indefinitely without a problem. If streaming replication is in
+ progress then WAL records will continue to be received, which will
eventually fill available disk space, depending upon the duration of
the pause, the rate of WAL generation and available disk space.
</para>
<sect2 id="functions-snapshot-synchronization">
<title>Snapshot Synchronization Functions</title>
- <indexterm>
- <primary>pg_export_snapshot</primary>
- </indexterm>
-
<para>
<productname>PostgreSQL</productname> allows database sessions to synchronize their
snapshots. A <firstterm>snapshot</firstterm> determines which data is visible to the
<table id="functions-snapshot-synchronization-table">
<title>Snapshot Synchronization Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_export_snapshot()</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>Save the current snapshot and return its identifier</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_export_snapshot</primary>
+ </indexterm>
+ <function>pg_export_snapshot</function> ()
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Saves the transaction's current snapshot and returns
+ a <type>text</type> string identifying the snapshot. This string must
+ be passed (outside the database) to clients that want to import the
+ snapshot. The snapshot is available for import only until the end of
+ the transaction that exported it.
+ </para>
+ <para>
+ A transaction can export more than one snapshot, if needed. Note that
+ doing so is only useful in <literal>READ COMMITTED</literal>
+ transactions, since in <literal>REPEATABLE READ</literal> and higher
+ isolation levels, transactions use the same snapshot throughout their
+ lifetime. Once a transaction has exported any snapshots, it cannot be
+ prepared with <xref linkend="sql-prepare-transaction"/>.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- The function <function>pg_export_snapshot</function> saves the current snapshot
- and returns a <type>text</type> string identifying the snapshot. This string
- must be passed (outside the database) to clients that want to import the
- snapshot. The snapshot is available for import only until the end of the
- transaction that exported it. A transaction can export more than one
- snapshot, if needed. Note that doing so is only useful in <literal>READ
- COMMITTED</literal> transactions, since in <literal>REPEATABLE READ</literal> and
- higher isolation levels, transactions use the same snapshot throughout
- their lifetime. Once a transaction has exported any snapshots, it cannot
- be prepared with <xref linkend="sql-prepare-transaction"/>.
- </para>
-
- <para>
- See <xref linkend="sql-set-transaction"/> for details of how to use an
- exported snapshot.
- </para>
</sect2>
<sect2 id="functions-replication">
- <title>Replication Functions</title>
+ <title>Replication Management Functions</title>
<para>
The functions shown
<xref linkend="replication-origins"/>
for information about the underlying features.
Use of functions for replication origin is restricted to superusers.
- Use of functions for replication slot is restricted to superusers
+ Use of functions for replication slots is restricted to superusers
and users having <literal>REPLICATION</literal> privilege.
</para>
</para>
<table id="functions-replication-table">
- <title>Replication <acronym>SQL</acronym> Functions</title>
- <tgroup cols="3">
+ <title>Replication Management Functions</title>
+ <tgroup cols="1">
<thead>
<row>
- <entry>Function</entry>
- <entry>Return Type</entry>
- <entry>Description</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
+
<tbody>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_create_physical_replication_slot</primary>
</indexterm>
- <literal><function>pg_create_physical_replication_slot(<parameter>slot_name</parameter> <type>name</type> <optional>, <parameter>immediately_reserve</parameter> <type>boolean</type>, <parameter>temporary</parameter> <type>boolean</type></optional>)</function></literal>
- </entry>
- <entry>
- (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
- </entry>
- <entry>
+ <function>pg_create_physical_replication_slot</function> ( <parameter>slot_name</parameter> <type>name</type> <optional>, <parameter>immediately_reserve</parameter> <type>boolean</type>, <parameter>temporary</parameter> <type>boolean</type> </optional> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>slot_name</parameter> <type>name</type>,
+ <parameter>lsn</parameter> <type>pg_lsn</type> )
+ </para>
+ <para>
Creates a new physical replication slot named
<parameter>slot_name</parameter>. The optional second parameter,
when <literal>true</literal>, specifies that the <acronym>LSN</acronym> for this
see <xref linkend="protocol-replication"/>. The optional third
parameter, <parameter>temporary</parameter>, when set to true, specifies that
the slot should not be permanently stored to disk and is only meant
- for use by current session. Temporary slots are also
+ for use by the current session. Temporary slots are also
released upon any error. This function corresponds
to the replication protocol command <literal>CREATE_REPLICATION_SLOT
... PHYSICAL</literal>.
- </entry>
+ </para></entry>
</row>
+
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_drop_replication_slot</primary>
</indexterm>
- <literal><function>pg_drop_replication_slot(<parameter>slot_name</parameter> <type>name</type>)</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
+ <function>pg_drop_replication_slot</function> ( <parameter>slot_name</parameter> <type>name</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
Drops the physical or logical replication slot
named <parameter>slot_name</parameter>. Same as replication protocol
command <literal>DROP_REPLICATION_SLOT</literal>. For logical slots, this must
- be called when connected to the same database the slot was created on.
- </entry>
+ be called while connected to the same database the slot was created on.
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_create_logical_replication_slot</primary>
</indexterm>
- <literal><function>pg_create_logical_replication_slot(<parameter>slot_name</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type></optional>)</function></literal>
- </entry>
- <entry>
- (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
- </entry>
- <entry>
+ <function>pg_create_logical_replication_slot</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>plugin</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type> </optional> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>slot_name</parameter> <type>name</type>,
+ <parameter>lsn</parameter> <type>pg_lsn</type> )
+ </para>
+ <para>
Creates a new logical (decoding) replication slot named
<parameter>slot_name</parameter> using the output plugin
<parameter>plugin</parameter>. The optional third
parameter, <parameter>temporary</parameter>, when set to true, specifies that
the slot should not be permanently stored to disk and is only meant
- for use by current session. Temporary slots are also
+ for use by the current session. Temporary slots are also
released upon any error. A call to this function has the same
effect as the replication protocol command
<literal>CREATE_REPLICATION_SLOT ... LOGICAL</literal>.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_copy_physical_replication_slot</primary>
</indexterm>
- <literal><function>pg_copy_physical_replication_slot(<parameter>src_slot_name</parameter> <type>name</type>, <parameter>dst_slot_name</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type></optional>)</function></literal>
- </entry>
- <entry>
- (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
- </entry>
- <entry>
+ <function>pg_copy_physical_replication_slot</function> ( <parameter>src_slot_name</parameter> <type>name</type>, <parameter>dst_slot_name</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type> </optional> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>slot_name</parameter> <type>name</type>,
+ <parameter>lsn</parameter> <type>pg_lsn</type> )
+ </para>
+ <para>
Copies an existing physical replication slot named <parameter>src_slot_name</parameter>
to a physical replication slot named <parameter>dst_slot_name</parameter>.
The copied physical slot starts to reserve WAL from the same <acronym>LSN</acronym> as the
source slot.
<parameter>temporary</parameter> is optional. If <parameter>temporary</parameter>
is omitted, the same value as the source slot is used.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_copy_logical_replication_slot</primary>
</indexterm>
- <literal><function>pg_copy_logical_replication_slot(<parameter>src_slot_name</parameter> <type>name</type>, <parameter>dst_slot_name</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type> <optional>, <parameter>plugin</parameter> <type>name</type></optional></optional>)</function></literal>
- </entry>
- <entry>
- (<parameter>slot_name</parameter> <type>name</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)
- </entry>
- <entry>
- Copies an existing logical replication slot named <parameter>src_slot_name</parameter>
- to a logical replication slot named <parameter>dst_slot_name</parameter>
- while changing the output plugin and persistence. The copied logical slot starts
- from the same <acronym>LSN</acronym> as the source logical slot. Both
- <parameter>temporary</parameter> and <parameter>plugin</parameter> are optional.
- If <parameter>temporary</parameter> or <parameter>plugin</parameter> are omitted,
- the same values as the source logical slot are used.
- </entry>
+ <function>pg_copy_logical_replication_slot</function> ( <parameter>src_slot_name</parameter> <type>name</type>, <parameter>dst_slot_name</parameter> <type>name</type> <optional>, <parameter>temporary</parameter> <type>boolean</type> <optional>, <parameter>plugin</parameter> <type>name</type> </optional></optional> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>slot_name</parameter> <type>name</type>,
+ <parameter>lsn</parameter> <type>pg_lsn</type> )
+ </para>
+ <para>
+ Copies an existing logical replication slot
+ named <parameter>src_slot_name</parameter> to a logical replication
+ slot named <parameter>dst_slot_name</parameter>, optionally changing
+ the output plugin and persistence. The copied logical slot starts
+ from the same <acronym>LSN</acronym> as the source logical slot. Both
+ <parameter>temporary</parameter> and <parameter>plugin</parameter> are
+ optional; if they are omitted, the values of the source slot are used.
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_get_changes</primary>
</indexterm>
- <literal><function>pg_logical_slot_get_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
- </entry>
- <entry>
- (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
- </entry>
- <entry>
+ <function>pg_logical_slot_get_changes</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>integer</type>, <literal>VARIADIC</literal> <parameter>options</parameter> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>lsn</parameter> <type>pg_lsn</type>,
+ <parameter>xid</parameter> <type>xid</type>,
+ <parameter>data</parameter> <type>text</type> )
+ </para>
+ <para>
Returns changes in the slot <parameter>slot_name</parameter>, starting
- from the point at which since changes have been consumed last. If
- <parameter>upto_lsn</parameter> and <parameter>upto_nchanges</parameter> are NULL,
+ from the point from which changes have been consumed last. If
+ <parameter>upto_lsn</parameter>
+ and <parameter>upto_nchanges</parameter> are NULL,
logical decoding will continue until end of WAL. If
<parameter>upto_lsn</parameter> is non-NULL, decoding will include only
those transactions which commit prior to the specified LSN. If
the specified value. Note, however, that the actual number of
rows returned may be larger, since this limit is only checked after
adding the rows produced when decoding each new transaction commit.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_peek_changes</primary>
</indexterm>
- <literal><function>pg_logical_slot_peek_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
- </entry>
- <entry>
- (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>text</type>)
- </entry>
- <entry>
+ <function>pg_logical_slot_peek_changes</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>integer</type>, <literal>VARIADIC</literal> <parameter>options</parameter> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>lsn</parameter> <type>pg_lsn</type>,
+ <parameter>xid</parameter> <type>xid</type>,
+ <parameter>data</parameter> <type>text</type> )
+ </para>
+ <para>
Behaves just like
the <function>pg_logical_slot_get_changes()</function> function,
except that changes are not consumed; that is, they will be returned
again on future calls.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_get_binary_changes</primary>
</indexterm>
- <literal><function>pg_logical_slot_get_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
- </entry>
- <entry>
- (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
- </entry>
- <entry>
+ <function>pg_logical_slot_get_binary_changes</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>integer</type>, <literal>VARIADIC</literal> <parameter>options</parameter> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>lsn</parameter> <type>pg_lsn</type>,
+ <parameter>xid</parameter> <type>xid</type>,
+ <parameter>data</parameter> <type>bytea</type> )
+ </para>
+ <para>
Behaves just like
the <function>pg_logical_slot_get_changes()</function> function,
except that changes are returned as <type>bytea</type>.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_slot_peek_binary_changes</primary>
</indexterm>
- <literal><function>pg_logical_slot_peek_binary_changes(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>int</type>, VARIADIC <parameter>options</parameter> <type>text[]</type>)</function></literal>
- </entry>
- <entry>
- (<parameter>lsn</parameter> <type>pg_lsn</type>, <parameter>xid</parameter> <type>xid</type>, <parameter>data</parameter> <type>bytea</type>)
- </entry>
- <entry>
+ <function>pg_logical_slot_peek_binary_changes</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>, <parameter>upto_nchanges</parameter> <type>integer</type>, <literal>VARIADIC</literal> <parameter>options</parameter> <type>text[]</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>lsn</parameter> <type>pg_lsn</type>,
+ <parameter>xid</parameter> <type>xid</type>,
+ <parameter>data</parameter> <type>bytea</type> )
+ </para>
+ <para>
Behaves just like
- the <function>pg_logical_slot_get_changes()</function> function,
- except that changes are returned as <type>bytea</type> and that
- changes are not consumed; that is, they will be returned again
- on future calls.
- </entry>
+ the <function>pg_logical_slot_peek_changes()</function> function,
+ except that changes are returned as <type>bytea</type>.
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_slot_advance</primary>
</indexterm>
- <literal><function>pg_replication_slot_advance(<parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type>)</function></literal>
- </entry>
- <entry>
- (<parameter>slot_name</parameter> <type>name</type>, <parameter>end_lsn</parameter> <type>pg_lsn</type>)
- <type>bool</type>
- </entry>
- <entry>
+ <function>pg_replication_slot_advance</function> ( <parameter>slot_name</parameter> <type>name</type>, <parameter>upto_lsn</parameter> <type>pg_lsn</type> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>slot_name</parameter> <type>name</type>,
+ <parameter>end_lsn</parameter> <type>pg_lsn</type> )
+ </para>
+ <para>
Advances the current confirmed position of a replication slot named
<parameter>slot_name</parameter>. The slot will not be moved backwards,
and it will not be moved beyond the current insert location. Returns
- the name of the slot and the real position to which it was advanced to.
- The information of the updated slot is written out at the follow-up
- checkpoint if any advancing is done. In the event of a crash, the
+ the name of the slot and the actual position that it was advanced to.
+ The updated slot position information is written out at the next
+ checkpoint if any advancing is done. So in the event of a crash, the
slot may return to an earlier position.
- </entry>
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-create">
+ <entry id="pg-replication-origin-create" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_create</primary>
</indexterm>
- <literal><function>pg_replication_origin_create(<parameter>node_name</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry>
- <type>oid</type>
- </entry>
- <entry>
- Create a replication origin with the given external
- name, and return the internal id assigned to it.
- </entry>
+ <function>pg_replication_origin_create</function> ( <parameter>node_name</parameter> <type>text</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Creates a replication origin with the given external
+ name, and returns the internal ID assigned to it.
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-drop">
+ <entry id="pg-replication-origin-drop" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_drop</primary>
</indexterm>
- <literal><function>pg_replication_origin_drop(<parameter>node_name</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Delete a previously created replication origin, including any
+ <function>pg_replication_origin_drop</function> ( <parameter>node_name</parameter> <type>text</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Deletes a previously-created replication origin, including any
associated replay progress.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_oid</primary>
</indexterm>
- <literal><function>pg_replication_origin_oid(<parameter>node_name</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry>
- <type>oid</type>
- </entry>
- <entry>
- Lookup a replication origin by name and return the internal id. If no
- corresponding replication origin is found an error is thrown.
- </entry>
+ <function>pg_replication_origin_oid</function> ( <parameter>node_name</parameter> <type>text</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Looks up a replication origin by name and returns the internal ID. If
+ no such replication origin is found an error is thrown.
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-session-setup">
+ <entry id="pg-replication-origin-session-setup" role="func_table_entry"><para role="func_signature">
<indexterm>
- <primary>pg_replication_origin_session_setup</primary>
- </indexterm>
- <literal><function>pg_replication_origin_session_setup(<parameter>node_name</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Mark the current session as replaying from the given
- origin, allowing replay progress to be tracked. Use
- <function>pg_replication_origin_session_reset</function> to revert.
- Can only be used if no previous origin is configured.
- </entry>
+ <primary>pg_replication_origin_session_setup</primary>
+ </indexterm>
+ <function>pg_replication_origin_session_setup</function> ( <parameter>node_name</parameter> <type>text</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Marks the current session as replaying from the given
+ origin, allowing replay progress to be tracked.
+ Can only be used if no origin is currently selected.
+ Use <function>pg_replication_origin_session_reset</function> to undo.
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_session_reset</primary>
</indexterm>
- <literal><function>pg_replication_origin_session_reset()</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Cancel the effects
+ <function>pg_replication_origin_session_reset</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Cancels the effects
of <function>pg_replication_origin_session_setup()</function>.
- </entry>
+ </para></entry>
</row>
<row>
- <entry>
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_session_is_setup</primary>
</indexterm>
- <literal><function>pg_replication_origin_session_is_setup()</function></literal>
- </entry>
- <entry>
- <type>bool</type>
- </entry>
- <entry>
- Has a replication origin been configured in the current session?
- </entry>
+ <function>pg_replication_origin_session_is_setup</function> ()
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Returns true if a replication origin has been selected in the
+ current session.
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-session-progress">
+ <entry id="pg-replication-origin-session-progress" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_session_progress</primary>
</indexterm>
- <literal><function>pg_replication_origin_session_progress(<parameter>flush</parameter> <type>bool</type>)</function></literal>
- </entry>
- <entry>
- <type>pg_lsn</type>
- </entry>
- <entry>
- Return the replay location for the replication origin configured in
+ <function>pg_replication_origin_session_progress</function> ( <parameter>flush</parameter> <type>boolean</type> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the replay location for the replication origin selected in
the current session. The parameter <parameter>flush</parameter>
determines whether the corresponding local transaction will be
guaranteed to have been flushed to disk or not.
- </entry>
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-xact-setup">
+ <entry id="pg-replication-origin-xact-setup" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_xact_setup</primary>
</indexterm>
- <literal><function>pg_replication_origin_xact_setup(<parameter>origin_lsn</parameter> <type>pg_lsn</type>, <parameter>origin_timestamp</parameter> <type>timestamptz</type>)</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Mark the current transaction as replaying a transaction that has
+ <function>pg_replication_origin_xact_setup</function> ( <parameter>origin_lsn</parameter> <type>pg_lsn</type>, <parameter>origin_timestamp</parameter> <type>timestamp with time zone</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Marks the current transaction as replaying a transaction that has
committed at the given <acronym>LSN</acronym> and timestamp. Can
- only be called when a replication origin has previously been
- configured using
- <function>pg_replication_origin_session_setup()</function>.
- </entry>
+ only be called when a replication origin has been selected
+ using <function>pg_replication_origin_session_setup</function>.
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-xact-reset">
+ <entry id="pg-replication-origin-xact-reset" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_xact_reset</primary>
</indexterm>
- <literal><function>pg_replication_origin_xact_reset()</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Cancel the effects of
+ <function>pg_replication_origin_xact_reset</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Cancels the effects of
<function>pg_replication_origin_xact_setup()</function>.
- </entry>
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-advance">
+ <entry id="pg-replication-origin-advance" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_advance</primary>
</indexterm>
- <literal>pg_replication_origin_advance<function>(<parameter>node_name</parameter> <type>text</type>, <parameter>lsn</parameter> <type>pg_lsn</type>)</function></literal>
- </entry>
- <entry>
- <type>void</type>
- </entry>
- <entry>
- Set replication progress for the given node to the given
- location. This primarily is useful for setting up the initial location
- or a new location after configuration changes and similar. Be aware
- that careless use of this function can lead to inconsistently
- replicated data.
- </entry>
+ <function>pg_replication_origin_advance</function> ( <parameter>node_name</parameter> <type>text</type>, <parameter>lsn</parameter> <type>pg_lsn</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Sets replication progress for the given node to the given
+ location. This is primarily useful for setting up the initial
+ location, or setting a new location after configuration changes and
+ similar. Be aware that careless use of this function can lead to
+ inconsistently replicated data.
+ </para></entry>
</row>
<row>
- <entry id="pg-replication-origin-progress">
+ <entry id="pg-replication-origin-progress" role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_replication_origin_progress</primary>
</indexterm>
- <literal><function>pg_replication_origin_progress(<parameter>node_name</parameter> <type>text</type>, <parameter>flush</parameter> <type>bool</type>)</function></literal>
- </entry>
- <entry>
- <type>pg_lsn</type>
- </entry>
- <entry>
- Return the replay location for the given replication origin. The
+ <function>pg_replication_origin_progress</function> ( <parameter>node_name</parameter> <type>text</type>, <parameter>flush</parameter> <type>boolean</type> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Returns the replay location for the given replication origin. The
parameter <parameter>flush</parameter> determines whether the
corresponding local transaction will be guaranteed to have been
flushed to disk or not.
- </entry>
+ </para></entry>
</row>
<row>
- <entry id="pg-logical-emit-message-text">
+ <entry role="func_table_entry"><para role="func_signature">
<indexterm>
<primary>pg_logical_emit_message</primary>
</indexterm>
- <literal><function>pg_logical_emit_message(<parameter>transactional</parameter> <type>bool</type>, <parameter>prefix</parameter> <type>text</type>, <parameter>content</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry>
- <type>pg_lsn</type>
- </entry>
- <entry>
- Emit text logical decoding message. This can be used to pass generic
- messages to logical decoding plugins through WAL. The parameter
- <parameter>transactional</parameter> specifies if the message should
- be part of current transaction or if it should be written immediately
- and decoded as soon as the logical decoding reads the record. The
- <parameter>prefix</parameter> is textual prefix used by the logical
- decoding plugins to easily recognize interesting messages for them.
- The <parameter>content</parameter> is the text of the message.
- </entry>
- </row>
-
- <row>
- <entry id="pg-logical-emit-message-bytea">
- <literal><function>pg_logical_emit_message(<parameter>transactional</parameter> <type>bool</type>, <parameter>prefix</parameter> <type>text</type>, <parameter>content</parameter> <type>bytea</type>)</function></literal>
- </entry>
- <entry>
- <type>pg_lsn</type>
- </entry>
- <entry>
- Emit binary logical decoding message. This can be used to pass generic
- messages to logical decoding plugins through WAL. The parameter
- <parameter>transactional</parameter> specifies if the message should
- be part of current transaction or if it should be written immediately
- and decoded as soon as the logical decoding reads the record. The
- <parameter>prefix</parameter> is textual prefix used by the logical
- decoding plugins to easily recognize interesting messages for them.
- The <parameter>content</parameter> is the binary content of the
- message.
- </entry>
+ <function>pg_logical_emit_message</function> ( <parameter>transactional</parameter> <type>boolean</type>, <parameter>prefix</parameter> <type>text</type>, <parameter>content</parameter> <type>text</type> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_logical_emit_message</function> ( <parameter>transactional</parameter> <type>boolean</type>, <parameter>prefix</parameter> <type>text</type>, <parameter>content</parameter> <type>bytea</type> )
+ <returnvalue>pg_lsn</returnvalue>
+ </para>
+ <para>
+ Emits a logical decoding message. This can be used to pass generic
+ messages to logical decoding plugins through
+ WAL. The <parameter>transactional</parameter> parameter specifies if
+ the message should be part of the current transaction, or if it should
+ be written immediately and decoded as soon as the logical decoder
+ reads the record. The <parameter>prefix</parameter> parameter is a
+ textual prefix that can be used by logical decoding plugins to easily
+ recognize messages that are interesting for them.
+ The <parameter>content</parameter> parameter is the content of the
+ message, given either in text or binary form.
+ </para></entry>
</row>
-
</tbody>
</tgroup>
</table>
<para>
The functions shown in <xref linkend="functions-admin-dbsize"/> calculate
- the disk space usage of database objects.
+ the disk space usage of database objects, or assist in presentation
+ of usage results.
+ All these functions return sizes measured in bytes. If an OID that does
+ not represent an existing object is passed to one of these
+ functions, <literal>NULL</literal> is returned.
</para>
- <indexterm>
- <primary>pg_column_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_database_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_indexes_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_relation_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_size_bytes</primary>
- </indexterm>
- <indexterm>
- <primary>pg_size_pretty</primary>
- </indexterm>
- <indexterm>
- <primary>pg_table_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_tablespace_size</primary>
- </indexterm>
- <indexterm>
- <primary>pg_total_relation_size</primary>
- </indexterm>
-
<table id="functions-admin-dbsize">
<title>Database Object Size Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry><literal><function>pg_column_size(<type>any</type>)</function></literal></entry>
- <entry><type>int</type></entry>
- <entry>Number of bytes used to store a particular value (possibly compressed)</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_database_size(<type>oid</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the database with the specified OID</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_database_size(<type>name</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the database with the specified name</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_indexes_size(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Total disk space used by indexes attached to the specified table
- </entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_relation_size(<parameter>relation</parameter> <type>regclass</type>, <parameter>fork</parameter> <type>text</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Disk space used by the specified fork (<literal>'main'</literal>,
- <literal>'fsm'</literal>, <literal>'vm'</literal>, or <literal>'init'</literal>)
- of the specified table or index
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_column_size</primary>
+ </indexterm>
+ <function>pg_column_size</function> ( <type>"any"</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Shows the number of bytes used to store any individual data value. If
+ applied directly to a table column value, this reflects any
+ compression that was done.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_relation_size(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Shorthand for <literal>pg_relation_size(..., 'main')</literal>
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_database_size</primary>
+ </indexterm>
+ <function>pg_database_size</function> ( <type>name</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_database_size</function> ( <type>oid</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the total disk space used by the database with the specified
+ name or OID. To use this function, you must
+ have <literal>CONNECT</literal> privilege on the specified database
+ (which is granted by default) or be a member of
+ the <literal>pg_read_all_stats</literal> role.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_size_bytes(<type>text</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Converts a size in human-readable format with size units into bytes
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_indexes_size</primary>
+ </indexterm>
+ <function>pg_indexes_size</function> ( <type>regclass</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the total disk space used by indexes attached to the
+ specified table.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_size_pretty(<type>bigint</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>
- Converts a size in bytes expressed as a 64-bit integer into a
- human-readable format with size units
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_relation_size</primary>
+ </indexterm>
+ <function>pg_relation_size</function> ( <parameter>relation</parameter> <type>regclass</type> <optional>, <parameter>fork</parameter> <type>text</type> </optional> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the disk space used by one <quote>fork</quote> of the
+ specified relation. (Note that for most purposes it is more
+ convenient to use the higher-level
+ functions <function>pg_total_relation_size</function>
+ or <function>pg_table_size</function>, which sum the sizes of all
+ forks.) With one argument, this returns the size of the main data
+ fork of the relation. The second argument can be provided to specify
+ which fork to examine:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <para>
+ <literal>main</literal> returns the size of the main
+ data fork of the relation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fsm</literal> returns the size of the Free Space Map
+ (see <xref linkend="storage-fsm"/>) associated with the relation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>vm</literal> returns the size of the Visibility Map
+ (see <xref linkend="storage-vm"/>) associated with the relation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>init</literal> returns the size of the initialization
+ fork, if any, associated with the relation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_size_pretty(<type>numeric</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>
- Converts a size in bytes expressed as a numeric value into a
- human-readable format with size units
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_size_bytes</primary>
+ </indexterm>
+ <function>pg_size_bytes</function> ( <type>text</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Converts a size in human-readable format (as returned
+ by <function>pg_size_pretty</function>) into bytes.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_table_size(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Disk space used by the specified table, excluding indexes
- (but including TOAST, free space map, and visibility map)
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_size_pretty</primary>
+ </indexterm>
+ <function>pg_size_pretty</function> ( <type>bigint</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_size_pretty</function> ( <type>numeric</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Converts a size in bytes into a more easily human-readable format with
+ size units (bytes, kB, MB, GB or TB as appropriate). Note that the
+ units are powers of 2 rather than powers of 10, so 1kB is 1024 bytes,
+ 1MB is 1024<superscript>2</superscript> = 1048576 bytes, and so on.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_tablespace_size(<type>oid</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the tablespace with the specified OID</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_table_size</primary>
+ </indexterm>
+ <function>pg_table_size</function> ( <type>regclass</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the disk space used by the specified table, excluding indexes
+ (but including its TOAST table if any, free space map, and visibility
+ map).
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_tablespace_size(<type>name</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>Disk space used by the tablespace with the specified name</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_tablespace_size</primary>
+ </indexterm>
+ <function>pg_tablespace_size</function> ( <type>name</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_tablespace_size</function> ( <type>oid</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the total disk space used in the tablespace with the
+ specified name or OID. To use this function, you must
+ have <literal>CREATE</literal> privilege on the specified tablespace
+ or be a member of the <literal>pg_read_all_stats</literal> role,
+ unless it is the default tablespace for the current database.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_total_relation_size(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>
- Total disk space used by the specified table,
- including all indexes and <acronym>TOAST</acronym> data
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_total_relation_size</primary>
+ </indexterm>
+ <function>pg_total_relation_size</function> ( <type>regclass</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Computes the total disk space used by the specified table, including
+ all indexes and <acronym>TOAST</acronym> data. The result is
+ equivalent to <function>pg_table_size</function>
+ <literal>+</literal> <function>pg_indexes_size</function>.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- <function>pg_column_size</function> shows the space used to store any individual
- data value.
- </para>
-
- <para>
- <function>pg_total_relation_size</function> accepts the OID or name of a
- table or toast table, and returns the total on-disk space used for
- that table, including all associated indexes. This function is
- equivalent to <function>pg_table_size</function>
- <literal>+</literal> <function>pg_indexes_size</function>.
- </para>
-
- <para>
- <function>pg_table_size</function> accepts the OID or name of a table and
- returns the disk space needed for that table, exclusive of indexes.
- (TOAST space, free space map, and visibility map are included.)
- </para>
-
- <para>
- <function>pg_indexes_size</function> accepts the OID or name of a table and
- returns the total disk space used by all the indexes attached to that
- table.
- </para>
-
- <para>
- <function>pg_database_size</function> and <function>pg_tablespace_size</function>
- accept the OID or name of a database or tablespace, and return the total
- disk space used therein. To use <function>pg_database_size</function>,
- you must have <literal>CONNECT</literal> permission on the specified database
- (which is granted by default), or be a member of the <literal>pg_read_all_stats</literal>
- role. To use <function>pg_tablespace_size</function>, you must have
- <literal>CREATE</literal> permission on the specified tablespace, or be a member
- of the <literal>pg_read_all_stats</literal> role unless it is the default tablespace for
- the current database.
- </para>
-
- <para>
- <function>pg_relation_size</function> accepts the OID or name of a table, index
- or toast table, and returns the on-disk size in bytes of one fork of
- that relation. (Note that for most purposes it is more convenient to
- use the higher-level functions <function>pg_total_relation_size</function>
- or <function>pg_table_size</function>, which sum the sizes of all forks.)
- With one argument, it returns the size of the main data fork of the
- relation. The second argument can be provided to specify which fork
- to examine:
- <itemizedlist spacing="compact">
- <listitem>
- <para>
- <literal>'main'</literal> returns the size of the main
- data fork of the relation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>'fsm'</literal> returns the size of the Free Space Map
- (see <xref linkend="storage-fsm"/>) associated with the relation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>'vm'</literal> returns the size of the Visibility Map
- (see <xref linkend="storage-vm"/>) associated with the relation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>'init'</literal> returns the size of the initialization
- fork, if any, associated with the relation.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- <function>pg_size_pretty</function> can be used to format the result of one of
- the other functions in a human-readable way, using bytes, kB, MB, GB or TB
- as appropriate.
- </para>
-
- <para>
- <function>pg_size_bytes</function> can be used to get the size in bytes from a
- string in human-readable format. The input may have units of bytes, kB,
- MB, GB or TB, and is parsed case-insensitively. If no units are specified,
- bytes are assumed.
- </para>
-
- <note>
- <para>
- The units kB, MB, GB and TB used by the functions
- <function>pg_size_pretty</function> and <function>pg_size_bytes</function> are defined
- using powers of 2 rather than powers of 10, so 1kB is 1024 bytes, 1MB is
- 1024<superscript>2</superscript> = 1048576 bytes, and so on.
- </para>
- </note>
-
<para>
The functions above that operate on tables or indexes accept a
<type>regclass</type> argument, which is simply the OID of the table or index
the table name.
</para>
- <para>
- If an OID that does not represent an existing object is passed as
- argument to one of the above functions, NULL is returned.
- </para>
-
<para>
The functions shown in <xref linkend="functions-admin-dblocation"/> assist
in identifying the specific disk files associated with database objects.
</para>
- <indexterm>
- <primary>pg_relation_filenode</primary>
- </indexterm>
- <indexterm>
- <primary>pg_relation_filepath</primary>
- </indexterm>
- <indexterm>
- <primary>pg_filenode_relation</primary>
- </indexterm>
-
<table id="functions-admin-dblocation">
<title>Database Object Location Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_relation_filenode(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
- </entry>
- <entry><type>oid</type></entry>
- <entry>
- Filenode number of the specified relation
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_relation_filenode</primary>
+ </indexterm>
+ <function>pg_relation_filenode</function> ( <parameter>relation</parameter> <type>regclass</type> )
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Returns the <quote>filenode</quote> number currently assigned to the
+ specified relation. The filenode is the base component of the file
+ name(s) used for the relation (see
+ <xref linkend="storage-file-layout"/> for more information).
+ For most relations the result is the same as
+ <structname>pg_class</structname>.<structfield>relfilenode</structfield>,
+ but for certain system catalogs <structfield>relfilenode</structfield>
+ is zero and this function must be used to get the correct value. The
+ function returns NULL if passed a relation that does not have storage,
+ such as a view.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_relation_filepath(<parameter>relation</parameter> <type>regclass</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>
- File path name of the specified relation
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_relation_filepath</primary>
+ </indexterm>
+ <function>pg_relation_filepath</function> ( <parameter>relation</parameter> <type>regclass</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the entire file path name (relative to the database cluster's
+ data directory, <varname>PGDATA</varname>) of the relation.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_filenode_relation(<parameter>tablespace</parameter> <type>oid</type>, <parameter>filenode</parameter> <type>oid</type>)</function></literal>
- </entry>
- <entry><type>regclass</type></entry>
- <entry>
- Find the relation associated with a given tablespace and filenode
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_filenode_relation</primary>
+ </indexterm>
+ <function>pg_filenode_relation</function> ( <parameter>tablespace</parameter> <type>oid</type>, <parameter>filenode</parameter> <type>oid</type> )
+ <returnvalue>regclass</returnvalue>
+ </para>
+ <para>
+ Returns a relation's OID given the tablespace OID and filenode it is
+ stored under. This is essentially the inverse mapping of
+ <function>pg_relation_filepath</function>. For a relation in the
+ database's default tablespace, the tablespace can be specified as zero.
+ Returns <literal>NULL</literal> if no relation in the current database
+ is associated with the given values.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- <function>pg_relation_filenode</function> accepts the OID or name of a table,
- index, sequence, or toast table, and returns the <quote>filenode</quote> number
- currently assigned to it. The filenode is the base component of the file
- name(s) used for the relation (see <xref linkend="storage-file-layout"/>
- for more information). For most tables the result is the same as
- <structname>pg_class</structname>.<structfield>relfilenode</structfield>, but for certain
- system catalogs <structfield>relfilenode</structfield> is zero and this function must
- be used to get the correct value. The function returns NULL if passed
- a relation that does not have storage, such as a view.
- </para>
-
- <para>
- <function>pg_relation_filepath</function> is similar to
- <function>pg_relation_filenode</function>, but it returns the entire file path name
- (relative to the database cluster's data directory <varname>PGDATA</varname>) of
- the relation.
- </para>
-
- <para>
- <function>pg_filenode_relation</function> is the reverse of
- <function>pg_relation_filenode</function>. Given a <quote>tablespace</quote> OID and
- a <quote>filenode</quote>, it returns the associated relation's OID. For a table
- in the database's default tablespace, the tablespace can be specified as 0.
- </para>
-
<para>
<xref linkend="functions-admin-collation"/> lists functions used to manage
collations.
<table id="functions-admin-collation">
<title>Collation Management Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <indexterm><primary>pg_collation_actual_version</primary></indexterm>
- <literal><function>pg_collation_actual_version(<type>oid</type>)</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>Return actual version of collation from operating system</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_collation_actual_version</primary>
+ </indexterm>
+ <function>pg_collation_actual_version</function> ( <type>oid</type> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns the actual version of the collation object as it is currently
+ installed in the operating system. If this is different from the
+ value in
+ <structname>pg_collation</structname>.<structfield>collversion</structfield>,
+ then objects depending on the collation might need to be rebuilt. See
+ also <xref linkend="sql-altercollation"/>.
+ </para></entry>
</row>
+
<row>
- <entry>
- <indexterm><primary>pg_import_system_collations</primary></indexterm>
- <literal><function>pg_import_system_collations(<parameter>schema</parameter> <type>regnamespace</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>Import operating system collations</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_import_system_collations</primary>
+ </indexterm>
+ <function>pg_import_system_collations</function> ( <parameter>schema</parameter> <type>regnamespace</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Adds collations to the system
+ catalog <structname>pg_collation</structname> based on all the locales
+ it finds in the operating system. This is
+ what <command>initdb</command> uses; see
+ <xref linkend="collation-managing"/> for more details. If additional
+ locales are installed into the operating system later on, this
+ function can be run again to add collations for the new locales.
+ Locales that match existing entries
+ in <structname>pg_collation</structname> will be skipped. (But
+ collation objects based on locales that are no longer present in the
+ operating system are not removed by this function.)
+ The <parameter>schema</parameter> parameter would typically
+ be <literal>pg_catalog</literal>, but that is not a requirement; the
+ collations could be installed into some other schema as well. The
+ function returns the number of new collation objects it created.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
- <function>pg_collation_actual_version</function> returns the actual
- version of the collation object as it is currently installed in the
- operating system. If this is different from the value
- in <literal>pg_collation.collversion</literal>, then objects depending on
- the collation might need to be rebuilt. See also
- <xref linkend="sql-altercollation"/>.
- </para>
-
- <para>
- <function>pg_import_system_collations</function> adds collations to the system
- catalog <literal>pg_collation</literal> based on all the
- locales it finds in the operating system. This is
- what <command>initdb</command> uses;
- see <xref linkend="collation-managing"/> for more details. If additional
- locales are installed into the operating system later on, this function
- can be run again to add collations for the new locales. Locales that
- match existing entries in <literal>pg_collation</literal> will be skipped.
- (But collation objects based on locales that are no longer
- present in the operating system are not removed by this function.)
- The <parameter>schema</parameter> parameter would typically
- be <literal>pg_catalog</literal>, but that is not a requirement;
- the collations could be installed into some other schema as well.
- The function returns the number of new collation objects it created.
+ <xref linkend="functions-info-partition"/> lists functions that provide
+ information about the structure of partitioned tables.
</para>
<table id="functions-info-partition">
<title>Partitioning Information Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <indexterm><primary>pg_partition_tree</primary></indexterm>
- <literal><function>pg_partition_tree(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- List information about tables or indexes in a partition tree for a
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_partition_tree</primary>
+ </indexterm>
+ <function>pg_partition_tree</function> ( <type>regclass</type> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>relid</parameter> <type>regclass</type>,
+ <parameter>parentrelid</parameter> <type>regclass</type>,
+ <parameter>isleaf</parameter> <type>boolean</type>,
+ <parameter>level</parameter> <type>integer</type> )
+ </para>
+ <para>
+ Lists the tables or indexes in the partition tree of the
given partitioned table or partitioned index, with one row for each
- partition. Information provided includes the name of the partition,
- the name of its immediate parent, a boolean value telling if the
+ partition. Information provided includes the OID of the partition,
+ the OID of its immediate parent, a boolean value telling if the
partition is a leaf, and an integer telling its level in the hierarchy.
- The value of level begins at <literal>0</literal> for the input table
- or index in its role as the root of the partition tree,
- <literal>1</literal> for its partitions, <literal>2</literal> for
- their partitions, and so on.
- </entry>
+ The level value is 0 for the input table or index, 1 for its
+ immediate child partitions, 2 for their partitions, and so on.
+ Returns no rows if the relation does not exist or is not a partition
+ or partitioned table.
+ </para></entry>
</row>
+
<row>
- <entry>
- <indexterm><primary>pg_partition_ancestors</primary></indexterm>
- <literal><function>pg_partition_ancestors(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>setof regclass</type></entry>
- <entry>
- List the ancestor relations of the given partition,
- including the partition itself.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_partition_ancestors</primary>
+ </indexterm>
+ <function>pg_partition_ancestors</function> ( <type>regclass</type> )
+ <returnvalue>setof regclass</returnvalue>
+ </para>
+ <para>
+ Lists the ancestor relations of the given partition,
+ including the relation itself. Returns no rows if the relation
+ does not exist or is not a partition or partitioned table.
+ </para></entry>
</row>
+
<row>
- <entry>
- <indexterm><primary>pg_partition_root</primary></indexterm>
- <literal><function>pg_partition_root(<type>regclass</type>)</function></literal>
- </entry>
- <entry><type>regclass</type></entry>
- <entry>
- Return the top-most parent of a partition tree to which the given
- relation belongs.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_partition_root</primary>
+ </indexterm>
+ <function>pg_partition_root</function> ( <type>regclass</type> )
+ <returnvalue>regclass</returnvalue>
+ </para>
+ <para>
+ Returns the top-most parent of the partition tree to which the given
+ relation belongs. Returns <literal>NULL</literal> if the relation
+ does not exist or is not a partition or partitioned table.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
- To check the total size of the data contained in
- <structname>measurement</structname> table described in
- <xref linkend="ddl-partitioning-declarative-example"/>, one could use the
+ For example, to check the total size of the data contained in a
+ partitioned table <structname>measurement</structname>, one could use the
following query:
- </para>
-
<programlisting>
-=# SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
- FROM pg_partition_tree('measurement');
- total_size
-------------
- 24 kB
-(1 row)
+SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
+ FROM pg_partition_tree('measurement');
</programlisting>
+ </para>
</sect2>
<sect2 id="functions-admin-index">
<title>Index Maintenance Functions</title>
- <indexterm>
- <primary>brin_summarize_new_values</primary>
- </indexterm>
-
- <indexterm>
- <primary>gin_clean_pending_list</primary>
- </indexterm>
-
- <indexterm>
- <primary>brin_summarize_range</primary>
- </indexterm>
-
- <indexterm>
- <primary>brin_desummarize_range</primary>
- </indexterm>
-
<para>
<xref linkend="functions-admin-index-table"/> shows the functions
- available for index maintenance tasks.
+ available for index maintenance tasks. (Note that these maintenance
+ tasks are normally done automatically by autovacuum; use of these
+ functions is only required in special cases.)
These functions cannot be executed during recovery.
Use of these functions is restricted to superusers and the owner
of the given index.
<table id="functions-admin-index-table">
<title>Index Maintenance Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>brin_summarize_new_values(<parameter>index</parameter> <type>regclass</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>summarize page ranges not already summarized</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>brin_summarize_new_values</primary>
+ </indexterm>
+ <function>brin_summarize_new_values</function> ( <parameter>index</parameter> <type>regclass</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Scans the specified BRIN index to find page ranges in the base table
+ that are not currently summarized by the index; for any such range it
+ creates a new summary index tuple by scanning those table pages.
+ Returns the number of new page range summaries that were inserted
+ into the index.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>brin_summarize_range(<parameter>index</parameter> <type>regclass</type>, <parameter>blockNumber</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>summarize the page range covering the given block, if not already summarized</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>brin_summarize_range</primary>
+ </indexterm>
+ <function>brin_summarize_range</function> ( <parameter>index</parameter> <type>regclass</type>, <parameter>blockNumber</parameter> <type>bigint</type> )
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Summarizes the page range covering the given block, if not already
+ summarized. This is
+ like <function>brin_summarize_new_values</function> except that it
+ only processes the page range that covers the given table block number.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>brin_desummarize_range(<parameter>index</parameter> <type>regclass</type>, <parameter>blockNumber</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>integer</type></entry>
- <entry>de-summarize the page range covering the given block, if summarized</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>brin_desummarize_range</primary>
+ </indexterm>
+ <function>brin_desummarize_range</function> ( <parameter>index</parameter> <type>regclass</type>, <parameter>blockNumber</parameter> <type>bigint</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Removes the BRIN index tuple that summarizes the page range covering
+ the given table block, if there is one.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>gin_clean_pending_list(<parameter>index</parameter> <type>regclass</type>)</function></literal>
- </entry>
- <entry><type>bigint</type></entry>
- <entry>move GIN pending list entries into main index structure</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>gin_clean_pending_list</primary>
+ </indexterm>
+ <function>gin_clean_pending_list</function> ( <parameter>index</parameter> <type>regclass</type> )
+ <returnvalue>bigint</returnvalue>
+ </para>
+ <para>
+ Cleans up the <quote>pending</quote> list of the specified GIN index
+ by moving entries in it, in bulk, to the main GIN data structure.
+ Returns the number of pages removed from the pending list.
+ If the argument is a GIN index built with
+ the <literal>fastupdate</literal> option disabled, no cleanup happens
+ and the result is zero, because the index doesn't have a pending list.
+ See <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/>
+ for details about the pending list and <literal>fastupdate</literal>
+ option.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- <function>brin_summarize_new_values</function> accepts the OID or name of a
- BRIN index and inspects the index to find page ranges in the base table
- that are not currently summarized by the index; for any such range
- it creates a new summary index tuple by scanning the table pages.
- It returns the number of new page range summaries that were inserted
- into the index. <function>brin_summarize_range</function> does the same, except
- it only summarizes the range that covers the given block number.
- </para>
-
- <para>
- <function>gin_clean_pending_list</function> accepts the OID or name of
- a GIN index and cleans up the pending list of the specified index
- by moving entries in it to the main GIN data structure in bulk.
- It returns the number of pages removed from the pending list.
- Note that if the argument is a GIN index built with
- the <literal>fastupdate</literal> option disabled, no cleanup happens and the
- return value is 0, because the index doesn't have a pending list.
- Please see <xref linkend="gin-fast-update"/> and <xref linkend="gin-tips"/>
- for details of the pending list and <literal>fastupdate</literal> option.
- </para>
-
</sect2>
<sect2 id="functions-admin-genfile">
linkend="functions-admin-genfile-table"/> provide native access to
files on the machine hosting the server. Only files within the
database cluster directory and the <varname>log_directory</varname> can be
- accessed unless the user is granted the role
+ accessed, unless the user is a superuser or is granted the role
<literal>pg_read_server_files</literal>. Use a relative path for files in
the cluster directory, and a path matching the <varname>log_directory</varname>
configuration setting for log files.
<para>
Note that granting users the EXECUTE privilege on
<function>pg_read_file()</function>, or related functions, allows them the
- ability to read any file on the server which the database can read and
- that those reads bypass all in-database privilege checks. This means that,
- among other things, a user with this access is able to read the contents of the
- <literal>pg_authid</literal> table where authentication information is contained,
- as well as read any file in the database. Therefore, granting access to these
- functions should be carefully considered.
+ ability to read any file on the server that the database server process can
+ read; these functions bypass all in-database privilege checks. This means
+ that, for example, a user with such access is able to read the contents of
+ the <structname>pg_authid</structname> table where authentication
+ information is stored, as well as read any table data in the database.
+ Therefore, granting access to these functions should be carefully
+ considered.
+ </para>
+
+ <para>
+ Some of these functions take an optional <parameter>missing_ok</parameter>
+ parameter, which specifies the behavior when the file or directory does
+ not exist. If <literal>true</literal>, the function
+ returns <literal>NULL</literal> or an empty result set, as appropriate.
+ If <literal>false</literal>, an error is raised. The default
+ is <literal>false</literal>.
</para>
<table id="functions-admin-genfile-table">
<title>Generic File Access Functions</title>
- <tgroup cols="3">
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
</thead>
<tbody>
<row>
- <entry>
- <literal><function>pg_ls_dir(<parameter>dirname</parameter> <type>text</type> [, <parameter>missing_ok</parameter> <type>boolean</type>, <parameter>include_dot_dirs</parameter> <type>boolean</type>])</function></literal>
- </entry>
- <entry><type>setof text</type></entry>
- <entry>
- List the contents of a directory. Restricted to superusers by default, but other users can be granted EXECUTE to run the function.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ls_dir</primary>
+ </indexterm>
+ <function>pg_ls_dir</function> ( <parameter>dirname</parameter> <type>text</type> <optional>, <parameter>missing_ok</parameter> <type>boolean</type>, <parameter>include_dot_dirs</parameter> <type>boolean</type> </optional> )
+ <returnvalue>setof text</returnvalue>
+ </para>
+ <para>
+ Returns the names of all files (and directories and other special
+ files) in the specified
+ directory. The <parameter>include_dot_dirs</parameter> parameter
+ indicates whether <quote>.</quote> and <quote>..</quote> are to be
+ included in the result set; the default is to exclude them. Including
+ them can be useful when <parameter>missing_ok</parameter>
+ is <literal>true</literal>, to distinguish an empty directory from a
+ non-existent directory.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_ls_logdir()</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- List the name, size, and last modification time of files in the log
- directory. Access is granted to members of the <literal>pg_monitor</literal>
- role and may be granted to other non-superuser roles.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ls_logdir</primary>
+ </indexterm>
+ <function>pg_ls_logdir</function> ()
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>name</parameter> <type>text</type>,
+ <parameter>size</parameter> <type>bigint</type>,
+ <parameter>modification</parameter> <type>timestamp with time zone</type> )
+ </para>
+ <para>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's log directory. Filenames beginning with
+ a dot, directories, and other special files are excluded.
+ </para>
+ <para>
+ This function is restricted to superusers and members of
+ the <literal>pg_monitor</literal> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_ls_waldir()</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- List the name, size, and last modification time of files in the WAL
- directory. Access is granted to members of the <literal>pg_monitor</literal>
- role and may be granted to other non-superuser roles.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ls_waldir</primary>
+ </indexterm>
+ <function>pg_ls_waldir</function> ()
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>name</parameter> <type>text</type>,
+ <parameter>size</parameter> <type>bigint</type>,
+ <parameter>modification</parameter> <type>timestamp with time zone</type> )
+ </para>
+ <para>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's write-ahead log (WAL) directory.
+ Filenames beginning with a dot, directories, and other special files
+ are excluded.
+ </para>
+ <para>
+ This function is restricted to superusers and members of
+ the <literal>pg_monitor</literal> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_ls_archive_statusdir()</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- List the name, size, and last modification time of files in the WAL
- archive status directory. Access is granted to members of the
- <literal>pg_monitor</literal> role and may be granted to other
- non-superuser roles.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_ls_archive_statusdir</primary>
+ </indexterm>
+ <function>pg_ls_archive_statusdir</function> ()
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>name</parameter> <type>text</type>,
+ <parameter>size</parameter> <type>bigint</type>,
+ <parameter>modification</parameter> <type>timestamp with time zone</type> )
+ </para>
+ <para>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the server's WAL archive status directory
+ (<filename>pg_wal/archive_status</filename>). Filenames beginning
+ with a dot, directories, and other special files are excluded.
+ </para>
+ <para>
+ This function is restricted to superusers and members of
+ the <literal>pg_monitor</literal> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_ls_tmpdir(<optional><parameter>tablespace</parameter> <type>oid</type></optional>)</function></literal>
- </entry>
- <entry><type>setof record</type></entry>
- <entry>
- List the name, size, and last modification time of files in the
- temporary directory for <parameter>tablespace</parameter>. If
- <parameter>tablespace</parameter> is not provided, the
- <literal>pg_default</literal> tablespace is used. Access is granted
- to members of the <literal>pg_monitor</literal> role and may be
- granted to other non-superuser roles.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+
+ <indexterm>
+ <primary>pg_ls_tmpdir</primary>
+ </indexterm>
+ <function>pg_ls_tmpdir</function> ( <optional> <parameter>tablespace</parameter> <type>oid</type> </optional> )
+ <returnvalue>setof record</returnvalue>
+ ( <parameter>name</parameter> <type>text</type>,
+ <parameter>size</parameter> <type>bigint</type>,
+ <parameter>modification</parameter> <type>timestamp with time zone</type> )
+ </para>
+ <para>
+ Returns the name, size, and last modification time (mtime) of each
+ ordinary file in the temporary file directory for the
+ specified <parameter>tablespace</parameter>.
+ If <parameter>tablespace</parameter> is not provided,
+ the <literal>pg_default</literal> tablespace is examined. Filenames
+ beginning with a dot, directories, and other special files are
+ excluded.
+ </para>
+ <para>
+ This function is restricted to superusers and members of
+ the <literal>pg_monitor</literal> role by default, but other users can
+ be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_read_file(<parameter>filename</parameter> <type>text</type> [, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>bigint</type> [, <parameter>missing_ok</parameter> <type>boolean</type>] ])</function></literal>
- </entry>
- <entry><type>text</type></entry>
- <entry>
- Return the contents of a text file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_read_file</primary>
+ </indexterm>
+ <function>pg_read_file</function> ( <parameter>filename</parameter> <type>text</type> <optional>, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>bigint</type> <optional>, <parameter>missing_ok</parameter> <type>boolean</type> </optional></optional> )
+ <returnvalue>text</returnvalue>
+ </para>
+ <para>
+ Returns all or part of a text file, starting at the
+ given byte <parameter>offset</parameter>, returning at
+ most <parameter>length</parameter> bytes (less if the end of file is
+ reached first). If <parameter>offset</parameter> is negative, it is
+ relative to the end of the file. If <parameter>offset</parameter>
+ and <parameter>length</parameter> are omitted, the entire file is
+ returned. The bytes read from the file are interpreted as a string in
+ the database's encoding; an error is thrown if they are not valid in
+ that encoding.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_read_binary_file(<parameter>filename</parameter> <type>text</type> [, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>bigint</type> [, <parameter>missing_ok</parameter> <type>boolean</type>] ])</function></literal>
- </entry>
- <entry><type>bytea</type></entry>
- <entry>
- Return the contents of a file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_read_binary_file</primary>
+ </indexterm>
+ <function>pg_read_binary_file</function> ( <parameter>filename</parameter> <type>text</type> <optional>, <parameter>offset</parameter> <type>bigint</type>, <parameter>length</parameter> <type>bigint</type> <optional>, <parameter>missing_ok</parameter> <type>boolean</type> </optional></optional> )
+ <returnvalue>bytea</returnvalue>
+ </para>
+ <para>
+ Returns all or part of a file. This function is identical to
+ <function>pg_read_file</function> except that it can read arbitrary
+ binary data, returning the result as <type>bytea</type>
+ not <type>text</type>; accordingly, no encoding checks are performed.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para>
+ <para>
+ In combination with the <function>convert_from</function> function,
+ this function can be used to read a text file in a specified encoding
+ and convert to the database's encoding:
+<programlisting>
+SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
+</programlisting>
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_stat_file(<parameter>filename</parameter> <type>text</type>[, <parameter>missing_ok</parameter> <type>boolean</type>])</function></literal>
- </entry>
- <entry><type>record</type></entry>
- <entry>
- Return information about a file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function.
- </entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_file</primary>
+ </indexterm>
+ <function>pg_stat_file</function> ( <parameter>filename</parameter> <type>text</type> <optional>, <parameter>missing_ok</parameter> <type>boolean</type> </optional> )
+ <returnvalue>record</returnvalue>
+ ( <parameter>size</parameter> <type>bigint</type>,
+ <parameter>access</parameter> <type>timestamp with time zone</type>,
+ <parameter>modification</parameter> <type>timestamp with time zone</type>,
+ <parameter>change</parameter> <type>timestamp with time zone</type>,
+ <parameter>creation</parameter> <type>timestamp with time zone</type>,
+ <parameter>isdir</parameter> <type>boolean</type> )
+ </para>
+ <para>
+ Returns a record containing the file's size, last access time stamp,
+ last modification time stamp, last file status change time stamp (Unix
+ platforms only), file creation time stamp (Windows only), and a flag
+ indicating if it is a directory.
+ </para>
+ <para>
+ This function is restricted to superusers by default, but other users
+ can be granted EXECUTE to run the function.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <para>
- Some of these functions take an optional <parameter>missing_ok</parameter> parameter,
- which specifies the behavior when the file or directory does not exist.
- If <literal>true</literal>, the function returns NULL (except
- <function>pg_ls_dir</function>, which returns an empty result set). If
- <literal>false</literal>, an error is raised. The default is <literal>false</literal>.
- </para>
-
- <indexterm>
- <primary>pg_ls_dir</primary>
- </indexterm>
- <para>
- <function>pg_ls_dir</function> returns the names of all files (and directories
- and other special files) in the specified directory. The <parameter>
- include_dot_dirs</parameter> indicates whether <quote>.</quote> and <quote>..</quote> are
- included in the result set. The default is to exclude them
- (<literal>false</literal>), but including them can be useful when
- <parameter>missing_ok</parameter> is <literal>true</literal>, to distinguish an
- empty directory from an non-existent directory.
- </para>
-
- <indexterm>
- <primary>pg_ls_logdir</primary>
- </indexterm>
- <para>
- <function>pg_ls_logdir</function> returns the name, size, and last modified time
- (mtime) of each file in the log directory. By default, only superusers
- and members of the <literal>pg_monitor</literal> role can use this function.
- Access may be granted to others using <command>GRANT</command>.
- Filenames beginning with a dot, directories, and other special files are not shown.
- </para>
-
- <indexterm>
- <primary>pg_ls_waldir</primary>
- </indexterm>
- <para>
- <function>pg_ls_waldir</function> returns the name, size, and last modified time
- (mtime) of each file in the write ahead log (WAL) directory. By
- default only superusers and members of the <literal>pg_monitor</literal> role
- can use this function. Access may be granted to others using
- <command>GRANT</command>.
- Filenames beginning with a dot, directories, and other special files are not shown.
- </para>
-
- <indexterm>
- <primary>pg_ls_archive_statusdir</primary>
- </indexterm>
- <para>
- <function>pg_ls_archive_statusdir</function> returns the name, size, and
- last modified time (mtime) of each file in the WAL archive status
- directory <filename>pg_wal/archive_status</filename>. By default only
- superusers and members of the <literal>pg_monitor</literal> role can
- use this function. Access may be granted to others using
- <command>GRANT</command>.
- Filenames beginning with a dot, directories, and other special files are not shown.
- </para>
-
- <indexterm>
- <primary>pg_ls_tmpdir</primary>
- </indexterm>
- <para>
- <function>pg_ls_tmpdir</function> returns the name, size, and last modified
- time (mtime) of each file in the temporary file directory for the specified
- <parameter>tablespace</parameter>. If <parameter>tablespace</parameter> is
- not provided, the <literal>pg_default</literal> tablespace is used. By
- default only superusers and members of the <literal>pg_monitor</literal>
- role can use this function. Access may be granted to others using
- <command>GRANT</command>.
- Filenames beginning with a dot, directories, and other special files are not shown.
- </para>
-
- <indexterm>
- <primary>pg_read_file</primary>
- </indexterm>
- <para>
- <function>pg_read_file</function> returns part of a text file, starting
- at the given <parameter>offset</parameter>, returning at most <parameter>length</parameter>
- bytes (less if the end of file is reached first). If <parameter>offset</parameter>
- is negative, it is relative to the end of the file.
- If <parameter>offset</parameter> and <parameter>length</parameter> are omitted, the entire
- file is returned. The bytes read from the file are interpreted as a string
- in the server encoding; an error is thrown if they are not valid in that
- encoding.
- </para>
-
- <indexterm>
- <primary>pg_read_binary_file</primary>
- </indexterm>
- <para>
- <function>pg_read_binary_file</function> is similar to
- <function>pg_read_file</function>, except that the result is a <type>bytea</type> value;
- accordingly, no encoding checks are performed.
- In combination with the <function>convert_from</function> function, this function
- can be used to read a file in a specified encoding:
-<programlisting>
-SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
-</programlisting>
- </para>
-
- <indexterm>
- <primary>pg_stat_file</primary>
- </indexterm>
- <para>
- <function>pg_stat_file</function> returns a record containing the file
- size, last accessed time stamp, last modified time stamp,
- last file status change time stamp (Unix platforms only),
- file creation time stamp (Windows only), and a <type>boolean</type>
- indicating if it is a directory. Typical usages include:
-<programlisting>
-SELECT * FROM pg_stat_file('filename');
-SELECT (pg_stat_file('filename')).modification;
-</programlisting>
- </para>
-
</sect2>
<sect2 id="functions-advisory-locks">
see <xref linkend="advisory-locks"/>.
</para>
- <table id="functions-advisory-locks-table">
- <title>Advisory Lock Functions</title>
- <tgroup cols="3">
- <thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>
- </row>
- </thead>
+ <para>
+ All these functions are intended to be used to lock application-defined
+ resources, which can be identified either by a single 64-bit key value or
+ two 32-bit key values (note that these two key spaces do not overlap).
+ If another session already holds a conflicting lock on the same resource
+ identifier, the functions will either wait until the resource becomes
+ available, or return a <literal>false</literal> result, as appropriate for
+ the function.
+ Locks can be either shared or exclusive: a shared lock does not conflict
+ with other shared locks on the same resource, only with exclusive locks.
+ Locks can be taken at session level (so that they are held until released
+ or the session ends) or at transaction level (so that they are held until
+ the current transaction ends; there is no provision for manual release).
+ Multiple session-level lock requests stack, so that if the same resource
+ identifier is locked three times there must then be three unlock requests
+ to release the resource in advance of session end.
+ </para>
- <tbody>
- <row>
- <entry>
- <literal><function>pg_advisory_lock(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain exclusive session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_lock(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain exclusive session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_lock_shared(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain shared session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_lock_shared(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain shared session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_unlock(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Release an exclusive session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_unlock(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Release an exclusive session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_unlock_all()</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Release all session level advisory locks held by the current session</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_unlock_shared(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Release a shared session level advisory lock</entry>
- </row>
- <row>
- <entry>
- <literal><function>pg_advisory_unlock_shared(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Release a shared session level advisory lock</entry>
- </row>
+ <table id="functions-advisory-locks-table">
+ <title>Advisory Lock Functions</title>
+ <tgroup cols="1">
+ <thead>
<row>
- <entry>
- <literal><function>pg_advisory_xact_lock(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain exclusive transaction level advisory lock</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
</row>
+ </thead>
+
+ <tbody>
<row>
- <entry>
- <literal><function>pg_advisory_xact_lock(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain exclusive transaction level advisory lock</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_lock</primary>
+ </indexterm>
+ <function>pg_advisory_lock</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_lock</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Obtains an exclusive session-level advisory lock, waiting if necessary.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_advisory_xact_lock_shared(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain shared transaction level advisory lock</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_lock_shared</primary>
+ </indexterm>
+ <function>pg_advisory_lock_shared</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_lock_shared</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Obtains a shared session-level advisory lock, waiting if necessary.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_advisory_xact_lock_shared(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>void</type></entry>
- <entry>Obtain shared transaction level advisory lock</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_unlock</primary>
+ </indexterm>
+ <function>pg_advisory_unlock</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_unlock</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Releases a previously-acquired exclusive session-level advisory lock.
+ Returns <literal>true</literal> if the lock is successfully released.
+ If the lock was not held, <literal>false</literal> is returned, and in
+ addition, an SQL warning will be reported by the server.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_lock(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain exclusive session level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_unlock_all</primary>
+ </indexterm>
+ <function>pg_advisory_unlock_all</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Releases all session-level advisory locks held by the current session.
+ (This function is implicitly invoked at session end, even if the
+ client disconnects ungracefully.)
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_lock(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain exclusive session level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_unlock_shared</primary>
+ </indexterm>
+ <function>pg_advisory_unlock_shared</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_unlock_shared</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Releases a previously-acquired shared session-level advisory lock.
+ Returns <literal>true</literal> if the lock is successfully released.
+ If the lock was not held, <literal>false</literal> is returned, and in
+ addition, an SQL warning will be reported by the server.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_lock_shared(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain shared session level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_xact_lock</primary>
+ </indexterm>
+ <function>pg_advisory_xact_lock</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_xact_lock</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Obtains an exclusive transaction-level advisory lock, waiting if
+ necessary.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_lock_shared(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain shared session level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_advisory_xact_lock_shared</primary>
+ </indexterm>
+ <function>pg_advisory_xact_lock_shared</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_advisory_xact_lock_shared</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Obtains a shared transaction-level advisory lock, waiting if
+ necessary.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_xact_lock(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain exclusive transaction level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_try_advisory_lock</primary>
+ </indexterm>
+ <function>pg_try_advisory_lock</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_try_advisory_lock</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Obtains an exclusive session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <literal>true</literal>, or return <literal>false</literal>
+ without waiting if the lock cannot be acquired immediately.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_xact_lock(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain exclusive transaction level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_try_advisory_lock_shared</primary>
+ </indexterm>
+ <function>pg_try_advisory_lock_shared</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_try_advisory_lock_shared</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Obtains a shared session-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <literal>true</literal>, or return <literal>false</literal>
+ without waiting if the lock cannot be acquired immediately.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_xact_lock_shared(<parameter>key</parameter> <type>bigint</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain shared transaction level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_try_advisory_xact_lock</primary>
+ </indexterm>
+ <function>pg_try_advisory_xact_lock</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_try_advisory_xact_lock</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Obtains an exclusive transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <literal>true</literal>, or return <literal>false</literal>
+ without waiting if the lock cannot be acquired immediately.
+ </para></entry>
</row>
+
<row>
- <entry>
- <literal><function>pg_try_advisory_xact_lock_shared(<parameter>key1</parameter> <type>int</type>, <parameter>key2</parameter> <type>int</type>)</function></literal>
- </entry>
- <entry><type>boolean</type></entry>
- <entry>Obtain shared transaction level advisory lock if available</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_try_advisory_xact_lock_shared</primary>
+ </indexterm>
+ <function>pg_try_advisory_xact_lock_shared</function> ( <parameter>key</parameter> <type>bigint</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para role="func_signature">
+ <function>pg_try_advisory_xact_lock_shared</function> ( <parameter>key1</parameter> <type>integer</type>, <parameter>key2</parameter> <type>integer</type> )
+ <returnvalue>boolean</returnvalue>
+ </para>
+ <para>
+ Obtains a shared transaction-level advisory lock if available.
+ This will either obtain the lock immediately and
+ return <literal>true</literal>, or return <literal>false</literal>
+ without waiting if the lock cannot be acquired immediately.
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
- <indexterm>
- <primary>pg_advisory_lock</primary>
- </indexterm>
- <para>
- <function>pg_advisory_lock</function> locks an application-defined resource,
- which can be identified either by a single 64-bit key value or two
- 32-bit key values (note that these two key spaces do not overlap).
- If another session already holds a lock on the same resource identifier,
- this function will wait until the resource becomes available. The lock
- is exclusive. Multiple lock requests stack, so that if the same resource
- is locked three times it must then be unlocked three times to be
- released for other sessions' use.
- </para>
-
- <indexterm>
- <primary>pg_advisory_lock_shared</primary>
- </indexterm>
- <para>
- <function>pg_advisory_lock_shared</function> works the same as
- <function>pg_advisory_lock</function>,
- except the lock can be shared with other sessions requesting shared locks.
- Only would-be exclusive lockers are locked out.
- </para>
-
- <indexterm>
- <primary>pg_try_advisory_lock</primary>
- </indexterm>
- <para>
- <function>pg_try_advisory_lock</function> is similar to
- <function>pg_advisory_lock</function>, except the function will not wait for the
- lock to become available. It will either obtain the lock immediately and
- return <literal>true</literal>, or return <literal>false</literal> if the lock cannot be
- acquired immediately.
- </para>
-
- <indexterm>
- <primary>pg_try_advisory_lock_shared</primary>
- </indexterm>
- <para>
- <function>pg_try_advisory_lock_shared</function> works the same as
- <function>pg_try_advisory_lock</function>, except it attempts to acquire
- a shared rather than an exclusive lock.
- </para>
-
- <indexterm>
- <primary>pg_advisory_unlock</primary>
- </indexterm>
- <para>
- <function>pg_advisory_unlock</function> will release a previously-acquired
- exclusive session level advisory lock. It
- returns <literal>true</literal> if the lock is successfully released.
- If the lock was not held, it will return <literal>false</literal>,
- and in addition, an SQL warning will be reported by the server.
- </para>
-
- <indexterm>
- <primary>pg_advisory_unlock_shared</primary>
- </indexterm>
- <para>
- <function>pg_advisory_unlock_shared</function> works the same as
- <function>pg_advisory_unlock</function>,
- except it releases a shared session level advisory lock.
- </para>
-
- <indexterm>
- <primary>pg_advisory_unlock_all</primary>
- </indexterm>
- <para>
- <function>pg_advisory_unlock_all</function> will release all session level advisory
- locks held by the current session. (This function is implicitly invoked
- at session end, even if the client disconnects ungracefully.)
- </para>
-
- <indexterm>
- <primary>pg_advisory_xact_lock</primary>
- </indexterm>
- <para>
- <function>pg_advisory_xact_lock</function> works the same as
- <function>pg_advisory_lock</function>, except the lock is automatically released
- at the end of the current transaction and cannot be released explicitly.
- </para>
-
- <indexterm>
- <primary>pg_advisory_xact_lock_shared</primary>
- </indexterm>
- <para>
- <function>pg_advisory_xact_lock_shared</function> works the same as
- <function>pg_advisory_lock_shared</function>, except the lock is automatically released
- at the end of the current transaction and cannot be released explicitly.
- </para>
-
- <indexterm>
- <primary>pg_try_advisory_xact_lock</primary>
- </indexterm>
- <para>
- <function>pg_try_advisory_xact_lock</function> works the same as
- <function>pg_try_advisory_lock</function>, except the lock, if acquired,
- is automatically released at the end of the current transaction and
- cannot be released explicitly.
- </para>
-
- <indexterm>
- <primary>pg_try_advisory_xact_lock_shared</primary>
- </indexterm>
- <para>
- <function>pg_try_advisory_xact_lock_shared</function> works the same as
- <function>pg_try_advisory_lock_shared</function>, except the lock, if acquired,
- is automatically released at the end of the current transaction and
- cannot be released explicitly.
- </para>
-
</sect2>
</sect1>
<primary>pg_event_trigger_ddl_commands</primary>
</indexterm>
+<synopsis>
+<function>pg_event_trigger_ddl_commands</function> () <returnvalue>setof record</returnvalue>
+</synopsis>
+
<para>
<function>pg_event_trigger_ddl_commands</function> returns a list of
<acronym>DDL</acronym> commands executed by each user action,
</row>
<row>
<entry><literal>in_extension</literal></entry>
- <entry><type>bool</type></entry>
+ <entry><type>boolean</type></entry>
<entry>True if the command is part of an extension script</entry>
</row>
<row>
<primary>pg_event_trigger_dropped_objects</primary>
</indexterm>
+<synopsis>
+<function>pg_event_trigger_dropped_objects</function> () <returnvalue>setof record</returnvalue>
+</synopsis>
+
<para>
<function>pg_event_trigger_dropped_objects</function> returns a list of all objects
dropped by the command in whose <literal>sql_drop</literal> event it is called.
- If called in any other context,
- <function>pg_event_trigger_dropped_objects</function> raises an error.
- <function>pg_event_trigger_dropped_objects</function> returns the following columns:
+ If called in any other context, an error is raised.
+ This function returns the following columns:
<informaltable>
<tgroup cols="3">
</row>
<row>
<entry><literal>original</literal></entry>
- <entry><type>bool</type></entry>
+ <entry><type>boolean</type></entry>
<entry>True if this was one of the root object(s) of the deletion</entry>
</row>
<row>
<entry><literal>normal</literal></entry>
- <entry><type>bool</type></entry>
+ <entry><type>boolean</type></entry>
<entry>
True if there was a normal dependency relationship
in the dependency graph leading to this object
</row>
<row>
<entry><literal>is_temporary</literal></entry>
- <entry><type>bool</type></entry>
+ <entry><type>boolean</type></entry>
<entry>
True if this was a temporary object
</entry>
<entry>
An array that, together with <literal>object_type</literal> and
<literal>address_args</literal>, can be used by
- the <function>pg_get_object_address()</function> function to
+ the <function>pg_get_object_address</function> function to
recreate the object address in a remote server containing an
- identically named object of the same kind
+ identically named object of the same kind.
</entry>
</row>
<row>
</para>
<table id="functions-event-trigger-table-rewrite">
- <title>Table Rewrite Information</title>
- <tgroup cols="3">
+ <title>Table Rewrite Information Functions</title>
+ <tgroup cols="1">
<thead>
- <row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry></row>
+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ Function
+ </para>
+ <para>
+ Description
+ </para></entry>
+ </row>
</thead>
<tbody>
<row>
- <entry>
- <indexterm><primary>pg_event_trigger_table_rewrite_oid</primary></indexterm>
- <literal><function>pg_event_trigger_table_rewrite_oid()</function></literal>
- </entry>
- <entry><type>Oid</type></entry>
- <entry>The OID of the table about to be rewritten.</entry>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_event_trigger_table_rewrite_oid</primary>
+ </indexterm>
+ <function>pg_event_trigger_table_rewrite_oid</function> ()
+ <returnvalue>oid</returnvalue>
+ </para>
+ <para>
+ Returns the OID of the table about to be rewritten.
+ </para></entry>
</row>
<row>
- <entry>
- <indexterm><primary>pg_event_trigger_table_rewrite_reason</primary></indexterm>
- <literal><function>pg_event_trigger_table_rewrite_reason()</function></literal>
- </entry>
- <entry><type>int</type></entry>
- <entry>
- The reason code(s) explaining the reason for rewriting. The exact
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_event_trigger_table_rewrite_reason</primary>
+ </indexterm>
+ <function>pg_event_trigger_table_rewrite_reason</function> ()
+ <returnvalue>integer</returnvalue>
+ </para>
+ <para>
+ Returns a code explaining the reason(s) for rewriting. The exact
meaning of the codes is release dependent.
- </entry>
+ </para></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
- The <function>pg_event_trigger_table_rewrite_oid</function> function can be used
- in an event trigger like this:
+ These functions can be used in an event trigger like this:
<programlisting>
CREATE FUNCTION test_event_trigger_table_rewrite_oid()
RETURNS event_trigger
<title>Inspecting MCV Lists</title>
<indexterm>
- <primary>pg_mcv_list_items</primary>
- <secondary>pg_mcv_list</secondary>
+ <primary>pg_mcv_list_items</primary>
</indexterm>
+<synopsis>
+<function>pg_mcv_list_items</function> ( <type>pg_mcv_list</type> ) <returnvalue>setof record</returnvalue>
+</synopsis>
+
<para>
- <function>pg_mcv_list_items</function> returns a list of all items
- stored in a multi-column <acronym>MCV</acronym> list, and returns the
- following columns:
+ <function>pg_mcv_list_items</function> returns a set of records describing
+ all items stored in a multi-column <acronym>MCV</acronym> list. It
+ returns the following columns:
<informaltable>
<tgroup cols="3">
<tbody>
<row>
<entry><literal>index</literal></entry>
- <entry><type>int</type></entry>
+ <entry><type>integer</type></entry>
<entry>index of the item in the <acronym>MCV</acronym> list</entry>
</row>
<row>
pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts';
</programlisting>
- Values of the <type>pg_mcv_list</type> can be obtained only from the
- <literal>pg_statistic_ext_data.stxdmcv</literal> column.
+ Values of the <type>pg_mcv_list</type> type can be obtained only from the
+ <structname>pg_statistic_ext_data</structname>.<structfield>stxdmcv</structfield>
+ column.
</para>
</sect2>
projects / users / rhaas / postgres.git / commitdiff