diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 96ea57eedd4..bfaf139487b 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -12895,11 +12895,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple unnest for tsvector - unnest ( tsvector, - OUT lexeme text, - OUT positions smallint[], - OUT weights text ) + unnest ( tsvector ) setof record + ( lexeme text, + positions smallint[], + weights text ) Expands a tsvector into a set of rows, one per lexeme. @@ -12962,14 +12962,14 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_debug ( config regconfig, - document text, - OUT alias text, - OUT description text, - OUT token text, - OUT dictionaries regdictionary[], - OUT dictionary regdictionary, - OUT lexemes text[] ) + document text ) setof record + ( alias text, + description text, + token text, + dictionaries regdictionary[], + dictionary regdictionary, + lexemes text[] ) Extracts and normalizes tokens from @@ -13010,10 +13010,10 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_parse ts_parse ( parser_name text, - document text, - OUT tokid integer, - OUT token text ) + document text ) setof record + ( tokid integer, + token text ) Extracts tokens from the document using the @@ -13029,10 +13029,10 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_parse ( parser_oid oid, - document text, - OUT tokid integer, - OUT token text ) + document text ) setof record + ( tokid integer, + token text ) Extracts tokens from the document using a @@ -13050,11 +13050,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_token_type - ts_token_type ( parser_name text, - OUT tokid integer, - OUT alias text, - OUT description text ) + ts_token_type ( parser_name text ) setof record + ( tokid integer, + alias text, + description text ) Returns a table that describes each type of token the named parser can @@ -13069,11 +13069,11 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple - ts_token_type ( parser_oid oid, - OUT tokid integer, - OUT alias text, - OUT description text ) + ts_token_type ( parser_oid oid ) setof record + ( tokid integer, + alias text, + description text ) Returns a table that describes each type of token a parser specified @@ -13091,12 +13091,12 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple ts_stat - ts_stat ( sqlquery text, - weights text, - OUT word text, - OUT ndoc integer, - OUT nentry integer ) + ts_stat ( sqlquery text + , weights text ) setof record + ( word text, + ndoc integer, + nentry integer ) Executes the sqlquery, which must return a @@ -19458,218 +19458,212 @@ SELECT count(*) FROM sometable; 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 for a list of the built-in aggregates. Aggregate functions act as window functions only when an OVER - 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. - - General-Purpose Window Functions +
+ General-Purpose Window Functions + + + + + Function + + + Description + + + - - - - Function - Return Type - Description - - + + + + + row_number + + row_number () + bigint + + + Returns the number of the current row within its partition, counting + from 1. + + - - - - - row_number - - row_number() - - - bigint - - number of the current row within its partition, counting from 1 - + + + + rank + + rank () + bigint + + + Returns the rank of the current row, with gaps; that is, + the row_number of the first row in its peer + group. + + - - - - rank - - rank() - - - bigint - - rank of the current row with gaps; same as row_number of its first peer - + + + + dense_rank + + dense_rank () + bigint + + + Returns the rank of the current row, without gaps; this function + effectively counts peer groups. + + - - - - dense_rank - - dense_rank() - - - bigint - - rank of the current row without gaps; this function counts peer groups - + + + + percent_rank + + percent_rank () + double precision + + + Returns the relative rank of the current row, that is + (rank - 1) / (total partition rows - 1). + The value thus ranges from 0 to 1 inclusive. + + - - - - percent_rank - - percent_rank() - - - double precision - - relative rank of the current row: (rank - 1) / (total partition rows - 1) - + + + + cume_dist + + cume_dist () + double precision + + + 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/N to 1. + + - - - - cume_dist - - cume_dist() - - - double precision - - cumulative distribution: (number of partition rows preceding or peer with current row) / total partition rows - + + + + ntile + + ntile ( num_buckets integer ) + integer + + + Returns an integer ranging from 1 to the argument value, dividing the + partition as equally as possible. + + - - - - ntile - - ntile(num_buckets integer) - - - integer - - integer ranging from 1 to the argument value, dividing the - partition as equally as possible - + + + + lag + + lag ( value anyelement + , offset integer + , default anyelement ) + anyelement + + + Returns value evaluated at + the row that is offset + rows before the current row within the partition; if there is no such + row, instead returns default + (which must be of the same type as + value). + Both offset and + default are evaluated + with respect to the current row. If omitted, + offset defaults to 1 and + default to NULL. + + - - - - lag - - - lag(value anyelement - [, offset integer - [, default anyelement ]]) - - - - same type as value - - - returns value evaluated at - the row that is offset - rows before the current row within the partition; if there is no such - row, instead return default - (which must be of the same type as - value). - Both offset and - default are evaluated - with respect to the current row. If omitted, - offset defaults to 1 and - default to null - - + + + + lead + + lead ( value anyelement + , offset integer + , default anyelement ) + anyelement + + + Returns value evaluated at + the row that is offset + rows after the current row within the partition; if there is no such + row, instead returns default + (which must be of the same type as + value). + Both offset and + default are evaluated + with respect to the current row. If omitted, + offset defaults to 1 and + default to NULL. + + - - - - lead - - - lead(value anyelement - [, offset integer - [, default anyelement ]]) - - - - same type as value - - - returns value evaluated at - the row that is offset - rows after the current row within the partition; if there is no such - row, instead return default - (which must be of the same type as - value). - Both offset and - default are evaluated - with respect to the current row. If omitted, - offset defaults to 1 and - default to null - - + + + + first_value + + first_value ( value anyelement ) + anyelement + + + Returns value evaluated + at the row that is the first row of the window frame. + + - - - - first_value - - first_value(value any) - - - same type as value - - - returns value evaluated - at the row that is the first row of the window frame - - + + + + last_value + + last_value ( value anyelement ) + anyelement + + + Returns value evaluated + at the row that is the last row of the window frame. + + - - - - last_value - - last_value(value any) - - - same type as value - - - returns value evaluated - at the row that is the last row of the window frame - - - - - - - nth_value - - - nth_value(value any, nth integer) - - - - same type as value - - - returns value evaluated - at the row that is the nth - row of the window frame (counting from 1); null if no such row - - - - -
+ + + + nth_value + + nth_value ( value anyelement, n integer ) + anyelement + + + Returns value evaluated + at the row that is the n'th + row of the window frame (counting from 1); + returns NULL if there is no such row. + + + + + All of the functions listed in @@ -19678,7 +19672,7 @@ SELECT count(*) FROM sometable; definition. Rows that are not distinct when considering only the ORDER BY columns are said to be peers. The four ranking functions (including cume_dist) 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. @@ -19722,14 +19716,6 @@ SELECT count(*) FROM sometable; - - cume_dist computes the fraction of partition rows that - are less than or equal to the current row and its peers, while - percent_rank computes the fraction of partition rows that - are less than the current row, assuming the current row does not exist - in the partition. - - @@ -20443,10 +20429,6 @@ AND functions - - generate_series - - This section describes functions that possibly return more than one row. The most widely used functions in this class are series generating @@ -20457,59 +20439,71 @@ AND set-returning functions. - - Series Generating Functions - - - - Function - Argument Type - Return Type - Description - - +
+ Series Generating Functions + + + + + Function + + + Description + + + - - - generate_series(start, stop) - int, bigint or numeric - setof int, setof bigint, or setof numeric (same as argument type) - - Generate a series of values, from start to stop - with a step size of one - - + + + + + generate_series + + generate_series ( start integer, stop integer , step integer ) + setof integer + + + generate_series ( start bigint, stop bigint , step bigint ) + setof bigint + + + generate_series ( start numeric, stop numeric , step numeric ) + setof numeric + + + Generates a series of values from start + to stop, with a step size + of step. step + defaults to 1. + + - - generate_series(start, stop, step) - int, bigint or numeric - setof int, setof bigint or setof numeric (same as argument type) - - Generate a series of values, from start to stop - with a step size of step - - - - - generate_series(start, stop, step interval) - timestamp or timestamp with time zone - setof timestamp or setof timestamp with time zone (same as argument type) - - Generate a series of values, from start to stop - with a step size of step - - - - - -
+ + + generate_series ( start timestamp, stop timestamp, step interval ) + setof timestamp + + + generate_series ( start timestamp with time zone, stop timestamp with time zone, step interval ) + setof timestamp with time zone + + + Generates a series of values from start + to stop, with a step size + of step. + + + + + When step is positive, zero rows are returned if start is greater than stop. Conversely, when step is negative, zero rows are returned if start is less than stop. - Zero rows are also returned for NULL inputs. It is an error + Zero rows are also returned if any input is NULL. + It is an error for step to be zero. Some examples follow: SELECT * FROM generate_series(2,4); @@ -20534,14 +20528,14 @@ SELECT * FROM generate_series(4,3); (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 ------------ @@ -20552,7 +20546,7 @@ SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a); 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 @@ -20567,55 +20561,62 @@ SELECT * FROM generate_series('2008-03-01 00:00'::timestamp, - - Subscript Generating Functions - - - - Function - Return Type - Description - - +
+ Subscript Generating Functions + + + + + Function + + + Description + + + - - - generate_subscripts(array anyarray, dim int) - setof int - - Generate a series comprising the given array's subscripts. - - + + + + + generate_subscripts + + generate_subscripts ( array anyarray, dim integer ) + setof integer + + + Generates a series comprising the valid subscripts of + the dim'th dimension of the given array. + + - - generate_subscripts(array anyarray, dim int, reverse boolean) - setof int - - Generate a series comprising the given array's subscripts. When - reverse is true, the series is returned in - reverse order. - - - - - -
- - - generate_subscripts - + + + generate_subscripts ( array anyarray, dim integer, reverse boolean ) + setof integer + + + Generates a series comprising the valid subscripts of + the dim'th dimension of the given array. + When reverse is true, returns the series in + reverse order. + + + + + generate_subscripts 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 NULL. + Some examples follow: --- basic usage +-- basic usage: SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s; - s + s --- 1 2 @@ -20624,9 +20625,9 @@ SELECT generate_subscripts('{NULL,1,NULL,2}'::int[], 1) AS s; (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} @@ -20643,7 +20644,7 @@ FROM (SELECT generate_subscripts(a, 1) AS s, a FROM arrays) foo; {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] @@ -20652,7 +20653,7 @@ select $1[i][j] $$ LANGUAGE sql IMMUTABLE; CREATE FUNCTION SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]); - unnest2 + unnest2 --------- 1 2 @@ -20669,12 +20670,13 @@ SELECT * FROM unnest2(ARRAY[[1,2],[3,4]]); When a function in the FROM clause is suffixed by WITH ORDINALITY, a bigint 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 unnest(). --- set returning function WITH ORDINALITY +-- set returning function WITH ORDINALITY: SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); ls | n -----------------+---- @@ -20720,174 +20722,476 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); Session Information Functions - + - Name Return Type Description + + + Function + + + Description + + - current_catalog - name - name of current database (called catalog in the SQL standard) + + + current_catalog + + current_catalog + name + + + + current_database + + current_database () + name + + + Returns the name of the current database. (Databases are + called catalogs in the SQL standard, + so current_catalog is the standard's + spelling.) + - current_database() - name - name of current database + + + current_query + + current_query () + text + + + Returns the text of the currently executing query, as submitted + by the client (which might contain more than one statement). + - current_query() - text - text of the currently executing query, as submitted - by the client (might contain more than one statement) + + + current_role + + current_role + name + + + This is equivalent to current_user. + - current_role - name - equivalent to current_user + + + current_schema + + + schema + current + + current_schema + name + + + current_schema () + name + + + 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. + - current_schema[()] - name - name of current schema + + + current_schemas + + + search path + current + + current_schemas ( include_implicit boolean ) + name[] + + + Returns an array of the names of all schemas presently in the + effective search path, in their priority order. (Items in the current + setting that do not correspond to + existing, searchable schemas are omitted.) If the Boolean argument + is true, then implicitly-searched system schemas + such as pg_catalog are included in the result. + - current_schemas(boolean) - name[] - names of schemas in search path, optionally including implicit schemas + + + current_user + + + user + current + + current_user + name + + + Returns the user name of the current execution context. + - current_user - name - user name of current execution context + + + inet_client_addr + + inet_client_addr () + inet + + + Returns the IP address of the current client, + or NULL if the current connection is via a + Unix-domain socket. + - inet_client_addr() - inet - address of the remote connection + + + inet_client_port + + inet_client_port () + integer + + + Returns the IP port number of the current client, + or NULL if the current connection is via a + Unix-domain socket. + - inet_client_port() - int - port of the remote connection + + + inet_server_addr + + inet_server_addr () + inet + + + Returns the IP address on which the server accepted the current + connection, + or NULL if the current connection is via a + Unix-domain socket. + - inet_server_addr() - inet - address of the local connection + + + inet_server_port + + inet_server_port () + integer + + + Returns the IP port number on which the server accepted the current + connection, + or NULL if the current connection is via a + Unix-domain socket. + - inet_server_port() - int - port of the local connection + + + pg_backend_pid + + pg_backend_pid () + integer + + + Returns the process ID of the server process attached to the current + session. + - - pg_backend_pid() - int - - Process ID of the server process attached to the current session - + + + pg_blocking_pids + + pg_blocking_pids ( integer ) + integer[] + + + 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. + + + 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, pg_backend_pid 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. + + + 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. + - pg_blocking_pids(int) - int[] - Process ID(s) that are blocking specified server process ID from acquiring a lock + + + pg_conf_load_time + + pg_conf_load_time () + timestamp with time zone + + + 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. + - pg_conf_load_time() - timestamp with time zone - configuration load time + + + pg_current_logfile + + + Logging + pg_current_logfile function + + + current_logfiles + and the pg_current_logfile function + + + Logging + current_logfiles file and the pg_current_logfile + function + + pg_current_logfile ( text ) + text + + + Returns the path name of the log file currently in use by the logging + collector. The path includes the + directory and the individual log file name. The result + is NULL if the logging collector is disabled. + When multiple log files exist, each in a different + format, pg_current_logfile without an argument + returns the path of the file having the first format found in the + ordered list: stderr, + csvlog. NULL is returned + if no log file has any of these formats. + To request information about a specific log file format, supply + either csvlog or stderr as the + value of the optional parameter. The result is NULL + if the log format requested is not configured in + . + The result reflects the contents of + the current_logfiles file. + - pg_current_logfile(text) - text - Primary log file name, or log in the requested format, - currently in use by the logging collector + + + pg_my_temp_schema + + pg_my_temp_schema () + oid + + + Returns the OID of the current session's temporary schema, or zero if + it has none (because it has not created any temporary tables). + - pg_my_temp_schema() - oid - OID of session's temporary schema, or 0 if none + + + pg_is_other_temp_schema + + pg_is_other_temp_schema ( oid ) + boolean + + + 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.) + - pg_is_other_temp_schema(oid) - boolean - is schema another session's temporary schema? + + + pg_jit_available + + pg_jit_available () + boolean + + + Returns true if JIT compilation is available in + this session (see ). + Returns false if is set to false, or if the + feature was not enabled at compile time. + - pg_jit_available() - boolean - is JIT compilation available in this session - (see )? Returns false if is set to false. + + + pg_listening_channels + + pg_listening_channels () + setof text + + + Returns the set of names of asynchronous notification channels that + the current session is listening to. + - pg_listening_channels() - setof text - channel names that the session is currently listening on + + + pg_notification_queue_usage + + pg_notification_queue_usage () + double precision + + + 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 and + for more information. + - pg_notification_queue_usage() - double - fraction of the asynchronous notification queue currently occupied (0–1) + + + pg_postmaster_start_time + + pg_postmaster_start_time () + timestamp with time zone + + + Returns the time when the server started. + - pg_postmaster_start_time() - timestamp with time zone - server start time + + + pg_safe_snapshot_blocking_pids + + pg_safe_snapshot_blocking_pids ( integer ) + integer[] + + + 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. + + + A session running a SERIALIZABLE transaction blocks + a SERIALIZABLE READ ONLY DEFERRABLE transaction + from acquiring a snapshot until the latter determines that it is safe + to avoid taking any predicate locks. See + 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. + - pg_safe_snapshot_blocking_pids(int) - int[] - Process ID(s) that are blocking specified server process ID from acquiring a safe snapshot + + + pg_trigger_depth + + pg_trigger_depth () + integer + + + Returns the current nesting level + of PostgreSQL triggers (0 if not called, + directly or indirectly, from inside a trigger). + - pg_trigger_depth() - int - current nesting level of PostgreSQL triggers - (0 if not called, directly or indirectly, from inside a trigger) + + + session_user + + session_user + name + + + Returns the session user's name. + - session_user - name - session user name + + + user + + user + name + + + This is equivalent to current_user. + - user - name - equivalent to current_user - - - - version() - text - PostgreSQL version information. See also for a machine-readable version. + + + version + + version () + text + + + Returns a string describing the PostgreSQL + server's version. You can also get this information from + , or for a machine-readable + version use . Software + developers should use server_version_num (available + since 8.2) or instead of + parsing the text version. + @@ -20902,66 +21206,11 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); session_user, and user have special syntactic status in SQL: they must be called without trailing - parentheses. (In PostgreSQL, parentheses can optionally be used with - current_schema, but not with the others.) + parentheses. In PostgreSQL, parentheses can optionally be used with + current_schema, but not with the others. - - current_catalog - - - - current_database - - - - current_query - - - - current_role - - - - current_schema - - - - current_schemas - - - - current_user - - - - pg_backend_pid - - - - schema - current - - - - search path - current - - - - session_user - - - - user - current - - - - user - - The session_user is normally the user who initiated the current database connection; but superusers can change this setting @@ -20981,209 +21230,6 @@ SELECT * FROM pg_ls_dir('.') WITH ORDINALITY AS t(ls,n); does not, since it unifies users and roles into a single kind of entity.) - - current_schema 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. - current_schemas(boolean) 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 pg_catalog are included in the - returned search path. - - - - - The search path can be altered at run time. The command is: - -SET search_path TO schema , schema, ... - - - - - - inet_client_addr - - - - inet_client_port - - - - inet_server_addr - - - - inet_server_port - - - - inet_client_addr returns the IP address of the - current client, and inet_client_port returns the - port number. - inet_server_addr returns the IP address on which - the server accepted the current connection, and - inet_server_port returns the port number. - All these functions return NULL if the current connection is via a - Unix-domain socket. - - - - pg_blocking_pids - - - - pg_blocking_pids 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, pg_backend_pid 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. - - - - pg_conf_load_time - - - - pg_conf_load_time returns the - timestamp with time zone 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.) - - - - pg_current_logfile - - - - Logging - pg_current_logfile function - - - - current_logfiles - and the pg_current_logfile function - - - - Logging - current_logfiles file and the pg_current_logfile - function - - - - pg_current_logfile returns, as text, - the path of the log file(s) currently in use by the logging collector. - The path includes the directory - and the log file name. Log collection must be enabled or the return value - is NULL. When multiple log files exist, each in a - different format, pg_current_logfile called - without arguments returns the path of the file having the first format - found in the ordered list: stderr, csvlog. - NULL is returned when no log file has any of these - formats. To request a specific file format supply, as text, - either csvlog or stderr as the value of the - optional parameter. The return value is NULL when the - log format requested is not a configured - . The - pg_current_logfile reflects the contents of the - current_logfiles file. - - - - pg_my_temp_schema - - - - pg_is_other_temp_schema - - - - pg_my_temp_schema returns the OID of the current - session's temporary schema, or zero if it has none (because it has not - created any temporary tables). - pg_is_other_temp_schema 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.) - - - - pg_listening_channels - - - - pg_notification_queue_usage - - - - pg_listening_channels returns a set of names of - asynchronous notification channels that the current session is listening - to. pg_notification_queue_usage returns the - fraction of the total available space for notifications currently - occupied by notifications that are waiting to be processed, as a - double in the range 0–1. - See and - for more information. - - - - pg_postmaster_start_time - - - - pg_postmaster_start_time returns the - timestamp with time zone when the - server started. - - - - pg_safe_snapshot_blocking_pids - - - - pg_safe_snapshot_blocking_pids 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 SERIALIZABLE transaction blocks - a SERIALIZABLE READ ONLY DEFERRABLE transaction from - acquiring a snapshot until the latter determines that it is safe to avoid - taking any predicate locks. See 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. - - - - version - - - - version returns a string describing the - PostgreSQL server's version. You can also - get this information from or - for a machine-readable version, . - Software developers should use server_version_num - (available since 8.2) or instead - of parsing the text version. - - privilege querying @@ -21191,449 +21237,334 @@ SET search_path TO schema , sc lists functions that - allow the user to query object access privileges programmatically. - See for more information about - privileges. - - -
- Access Privilege Inquiry Functions - - - Name Return Type Description - - - - - has_any_column_privilege(user, - table, - privilege) - - boolean - does user have privilege for any column of table - - - has_any_column_privilege(table, - privilege) - - boolean - does current user have privilege for any column of table - - - has_column_privilege(user, - table, - column, - privilege) - - boolean - does user have privilege for column - - - has_column_privilege(table, - column, - privilege) - - boolean - does current user have privilege for column - - - has_database_privilege(user, - database, - privilege) - - boolean - does user have privilege for database - - - has_database_privilege(database, - privilege) - - boolean - does current user have privilege for database - - - has_foreign_data_wrapper_privilege(user, - fdw, - privilege) - - boolean - does user have privilege for foreign-data wrapper - - - has_foreign_data_wrapper_privilege(fdw, - privilege) - - boolean - does current user have privilege for foreign-data wrapper - - - has_function_privilege(user, - function, - privilege) - - boolean - does user have privilege for function - - - has_function_privilege(function, - privilege) - - boolean - does current user have privilege for function - - - has_language_privilege(user, - language, - privilege) - - boolean - does user have privilege for language - - - has_language_privilege(language, - privilege) - - boolean - does current user have privilege for language - - - has_schema_privilege(user, - schema, - privilege) - - boolean - does user have privilege for schema - - - has_schema_privilege(schema, - privilege) - - boolean - does current user have privilege for schema - - - has_sequence_privilege(user, - sequence, - privilege) - - boolean - does user have privilege for sequence - - - has_sequence_privilege(sequence, - privilege) - - boolean - does current user have privilege for sequence - - - has_server_privilege(user, - server, - privilege) - - boolean - does user have privilege for foreign server - - - has_server_privilege(server, - privilege) - - boolean - does current user have privilege for foreign server - - - has_table_privilege(user, - table, - privilege) - - boolean - does user have privilege for table - - - has_table_privilege(table, - privilege) - - boolean - does current user have privilege for table - - - has_tablespace_privilege(user, - tablespace, - privilege) - - boolean - does user have privilege for tablespace - - - has_tablespace_privilege(tablespace, - privilege) - - boolean - does current user have privilege for tablespace - - - has_type_privilege(user, - type, - privilege) - - boolean - does user have privilege for type - - - has_type_privilege(type, - privilege) - - boolean - does current user have privilege for type - - - pg_has_role(user, - role, - privilege) - - boolean - does user have privilege for role - - - pg_has_role(role, - privilege) - - boolean - does current user have privilege for role - - - row_security_active(table) - - boolean - does current user have row level security active for table - - - -
- - - has_any_column_privilege - - - has_column_privilege - - - has_database_privilege - - - has_function_privilege - - - has_foreign_data_wrapper_privilege - - - has_language_privilege - - - has_schema_privilege - - - has_server_privilege - - - has_sequence_privilege - - - has_table_privilege - - - has_tablespace_privilege - - - has_type_privilege - - - pg_has_role - - - row_security_active - - - - has_table_privilege checks whether a user - can access a table in a particular way. The user can be - specified by name, by OID (pg_authid.oid), - public to indicate the PUBLIC pseudo-role, or if the argument is - omitted - current_user is assumed. The table can be specified - by name or by OID. (Thus, there are actually six variants of - has_table_privilege, 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 SELECT, INSERT, - UPDATE, DELETE, TRUNCATE, - REFERENCES, or TRIGGER. Optionally, - WITH GRANT OPTION 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: + allow querying object access privileges programmatically. + (See for more information about + privileges.) + In these functions, the user whose privileges are being inquired about + can be specified by name or by OID + (pg_authid.oid), or if + the name is given as public then the privileges of the + PUBLIC pseudo-role are checked. Also, the user + argument can be omitted entirely, in which case + the current_user 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., SELECT). Optionally, WITH GRANT + OPTION 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: SELECT has_table_privilege('myschema.mytable', 'select'); SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION'); - + - - has_sequence_privilege checks whether a user - can access a sequence in a particular way. The possibilities for its - arguments are analogous to has_table_privilege. - The desired access privilege type must evaluate to one of - USAGE, - SELECT, or - UPDATE. - + + Access Privilege Inquiry Functions + + + + + Function + + + Description + + + - - has_any_column_privilege checks whether a user can - access any column of a table in a particular way. - Its argument possibilities - are analogous to has_table_privilege, - except that the desired access privilege type must evaluate to some - combination of - SELECT, - INSERT, - UPDATE, or - REFERENCES. Note that having any of these privileges - at the table level implicitly grants it for each column of the table, - so has_any_column_privilege will always return - true if has_table_privilege does for the same - arguments. But has_any_column_privilege also succeeds if - there is a column-level grant of the privilege for at least one column. - + + + + + has_any_column_privilege + + has_any_column_privilege ( + user name or oid, + table text or oid, + privilege text ) + boolean + + + 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 + SELECT, INSERT, + UPDATE, and REFERENCES. + + - - has_column_privilege checks whether a user - can access a column in a particular way. - Its argument possibilities - are analogous to has_table_privilege, - 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 - SELECT, - INSERT, - UPDATE, or - REFERENCES. Note that having any of these privileges - at the table level implicitly grants it for each column of the table. - + + + + has_column_privilege + + has_column_privilege ( + user name or oid, + table text or oid, + column text or smallint, + privilege text ) + boolean + + + 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 + (pg_attribute.attnum). + Allowable privilege types are + SELECT, INSERT, + UPDATE, and REFERENCES. + + - - has_database_privilege checks whether a user - can access a database in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to some combination of - CREATE, - CONNECT, - TEMPORARY, or - TEMP (which is equivalent to - TEMPORARY). - + + + + has_database_privilege + + has_database_privilege ( + user name or oid, + database text or oid, + privilege text ) + boolean + + + Does user have privilege for database? + Allowable privilege types are + CREATE, + CONNECT, + TEMPORARY, and + TEMP (which is equivalent to + TEMPORARY). + + - - has_function_privilege checks whether a user - can access a function in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - When specifying a function by a text string rather than by OID, - the allowed input is the same as for the regprocedure data type - (see ). - The desired access privilege type must evaluate to - EXECUTE. - An example is: + + + + has_foreign_data_wrapper_privilege + + has_foreign_data_wrapper_privilege ( + user name or oid, + fdw text or oid, + privilege text ) + boolean + + + Does user have privilege for foreign-data wrapper? + The only allowable privilege type is USAGE. + + + + + + + has_function_privilege + + has_function_privilege ( + user name or oid, + function text or oid, + privilege text ) + boolean + + + Does user have privilege for function? + The only allowable privilege type is EXECUTE. + + + When specifying a function by name rather than by OID, the allowed + input is the same as for the regprocedure data type (see + ). + An example is: SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); - + + - - has_foreign_data_wrapper_privilege checks whether a user - can access a foreign-data wrapper in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to - USAGE. - + + + + has_language_privilege + + has_language_privilege ( + user name or oid, + language text or oid, + privilege text ) + boolean + + + Does user have privilege for language? + The only allowable privilege type is USAGE. + + - - has_language_privilege checks whether a user - can access a procedural language in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to - USAGE. - + + + + has_schema_privilege + + has_schema_privilege ( + user name or oid, + schema text or oid, + privilege text ) + boolean + + + Does user have privilege for schema? + Allowable privilege types are + CREATE and + USAGE. + + - - has_schema_privilege checks whether a user - can access a schema in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to some combination of - CREATE or - USAGE. - + + + + has_sequence_privilege + + has_sequence_privilege ( + user name or oid, + sequence text or oid, + privilege text ) + boolean + + + Does user have privilege for sequence? + Allowable privilege types are + USAGE, + SELECT, and + UPDATE. + + - - has_server_privilege checks whether a user - can access a foreign server in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to - USAGE. - + + + + has_server_privilege + + has_server_privilege ( + user name or oid, + server text or oid, + privilege text ) + boolean + + + Does user have privilege for foreign server? + The only allowable privilege type is USAGE. + + - - has_tablespace_privilege checks whether a user - can access a tablespace in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - The desired access privilege type must evaluate to - CREATE. - + + + + has_table_privilege + + has_table_privilege ( + user name or oid, + table text or oid, + privilege text ) + boolean + + + Does user have privilege for table? + Allowable privilege types + are SELECT, INSERT, + UPDATE, DELETE, + TRUNCATE, REFERENCES, + and TRIGGER. + + - - has_type_privilege checks whether a user - can access a type in a particular way. - Its argument possibilities - are analogous to has_table_privilege. - When specifying a type by a text string rather than by OID, - the allowed input is the same as for the regtype data type - (see ). - The desired access privilege type must evaluate to - USAGE. - + + + + has_tablespace_privilege + + has_tablespace_privilege ( + user name or oid, + tablespace text or oid, + privilege text ) + boolean + + + Does user have privilege for tablespace? + The only allowable privilege type is CREATE. + + - - pg_has_role checks whether a user - can access a role in a particular way. - Its argument possibilities - are analogous to has_table_privilege, - except that public is not allowed as a user name. - The desired access privilege type must evaluate to some combination of - MEMBER or - USAGE. - MEMBER denotes direct or indirect membership in - the role (that is, the right to do SET ROLE), while - USAGE denotes whether the privileges of the role - are immediately available without doing SET ROLE. - + + + + has_type_privilege + + has_type_privilege ( + user name or oid, + type text or oid, + privilege text ) + boolean + + + Does user have privilege for data type? + The only allowable privilege type is USAGE. + When specifying a type by name rather than by OID, the allowed input + is the same as for the regtype data type (see + ). + + - - row_security_active checks whether row level - security is active for the specified table in the context of the - current_user and environment. The table can - be specified by name or by OID. - + + + + pg_has_role + + pg_has_role ( + user name or oid, + role text or oid, + privilege text ) + boolean + + + Does user have privilege for role? + Allowable privilege types are + MEMBER and USAGE. + MEMBER denotes direct or indirect membership in + the role (that is, the right to do SET ROLE), while + USAGE denotes whether the privileges of the role + are immediately available without doing SET ROLE. + This function does not allow the special case of + setting user to public, + because the PUBLIC pseudo-role can never be a member of real roles. + + + + + + + row_security_active + + row_security_active ( + table text or oid ) + boolean + + + Is row-level security active for the specified table in the context of + the current user and current environment? + + + + +
shows the operators @@ -21642,56 +21573,76 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); for information about how to read access privilege values. - - acldefault - - - aclitemeq - - - aclcontains - - - aclexplode - - - makeaclitem - - <type>aclitem</type> Operators - + - Operator - Description - Example - Result + + Operator + + + Description + + + Example(s) + + - - = - equal - 'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem - f + + + aclitemeq + + aclitem = aclitem + boolean + + + Are aclitems equal? (Notice that + type aclitem lacks the usual set of comparison + operators; it has only equality. In turn, aclitem + arrays can only be compared for equality.) + + + 'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitem + f + - @> - contains element - '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*w/hobbes'::aclitem - t + + + aclcontains + + aclitem[] @> aclitem + boolean + + + Does array contain the specified privileges? (This is true if there + is an array entry that matches the aclitem's grantee and + grantor, and has at least the specified set of privileges.) + + + '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitem + t + - ~ - contains element - '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*w/hobbes'::aclitem - t + + aclitem[] ~ aclitem + boolean + + + This is a deprecated alias for @>. + + + '{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitem + t + -
@@ -21703,62 +21654,96 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); <type>aclitem</type> Functions - + - Name Return Type Description + + + Function + + + Description + + + - acldefault(type, - ownerId) - aclitem[] - get the default access privileges for an object belonging to ownerId + + + acldefault + + acldefault ( + type "char", + ownerId oid ) + aclitem[] + + + Constructs an aclitem array holding the default access + privileges for an object of type type belonging + to the role with OID ownerId. This represents + the access privileges that will be assumed when an object's ACL entry + is null. (The default access privileges are described in + .) + The type parameter must be one of + 'c' for COLUMN, + 'r' for TABLE and table-like objects, + 's' for SEQUENCE, + 'd' for DATABASE, + 'f' for FUNCTION or PROCEDURE, + 'l' for LANGUAGE, + 'L' for LARGE OBJECT, + 'n' for SCHEMA, + 't' for TABLESPACE, + 'F' for FOREIGN DATA WRAPPER, + 'S' for FOREIGN SERVER, + or + 'T' for TYPE or DOMAIN. + + - aclexplode(aclitem[]) - setof record - get aclitem array as tuples + + + aclexplode + + aclexplode ( aclitem[] ) + setof record + ( grantor oid, + grantee oid, + privilege_type text, + is_grantable boolean ) + + + Returns the aclitem array as a set of rows. + If the grantee is the pseudo-role PUBLIC, it is represented by zero in + the grantee column. Each granted privilege is + represented as SELECT, INSERT, + etc. Note that each privilege is broken out as a separate row, so + only one keyword appears in the privilege_type + column. + + - makeaclitem(grantee, grantor, privilege, grantable) - aclitem - build an aclitem from input + + + makeaclitem + + makeaclitem ( + grantee oid, + grantor oid, + privileges text, + is_grantable boolean ) + aclitem + + + Constructs an aclitem with the given properties. +
- - acldefault returns the built-in default access - privileges for an object of type type belonging to - role ownerId. These represent the access - privileges that will be assumed when an object's ACL entry is null. - (The default access privileges are described in .) - The type parameter is a CHAR: write - 'c' for COLUMN, - 'r' for TABLE and table-like objects, - 's' for SEQUENCE, - 'd' for DATABASE, - 'f' for FUNCTION or PROCEDURE, - 'l' for LANGUAGE, - 'L' for LARGE OBJECT, - 'n' for SCHEMA, - 't' for TABLESPACE, - 'F' for FOREIGN DATA WRAPPER, - 'S' for FOREIGN SERVER, - or - 'T' for TYPE or DOMAIN. - - - - aclexplode returns an aclitem array - as a set of rows. Output columns are grantor oid, - grantee oid (0 for PUBLIC), - granted privilege as text (SELECT, ...) - and whether the privilege is grantable as boolean. - makeaclitem performs the inverse operation. - - shows functions that determine whether a certain object is visible in the @@ -21767,10 +21752,14 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); 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: SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); + For functions and operators, an object in the search path is said to be + visible if there is no object of the same name and argument data + type(s) earlier in the path. For operator classes and families, + both the name and the associated index access method are considered. @@ -21780,147 +21769,194 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); Schema Visibility Inquiry Functions - + - Name Return Type Description + + + Function + + + Description + + - pg_collation_is_visible(collation_oid) - - boolean - is collation visible in search path + + + pg_collation_is_visible + + pg_collation_is_visible ( collation oid ) + boolean + + + Is collation visible in search path? + + - pg_conversion_is_visible(conversion_oid) - - boolean - is conversion visible in search path + + + pg_conversion_is_visible + + pg_conversion_is_visible ( conversion oid ) + boolean + + + Is conversion visible in search path? + + - pg_function_is_visible(function_oid) - - boolean - is function visible in search path + + + pg_function_is_visible + + pg_function_is_visible ( function oid ) + boolean + + + Is function visible in search path? + (This also works for procedures and aggregates.) + + - pg_opclass_is_visible(opclass_oid) - - boolean - is operator class visible in search path + + + pg_opclass_is_visible + + pg_opclass_is_visible ( opclass oid ) + boolean + + + Is operator class visible in search path? + + - pg_operator_is_visible(operator_oid) - - boolean - is operator visible in search path + + + pg_operator_is_visible + + pg_operator_is_visible ( operator oid ) + boolean + + + Is operator visible in search path? + + - pg_opfamily_is_visible(opclass_oid) - - boolean - is operator family visible in search path + + + pg_opfamily_is_visible + + pg_opfamily_is_visible ( opclass oid ) + boolean + + + Is operator family visible in search path? + + - pg_statistics_obj_is_visible(stat_oid) - - boolean - is statistics object visible in search path + + + pg_statistics_obj_is_visible + + pg_statistics_obj_is_visible ( stat oid ) + boolean + + + Is statistics object visible in search path? + + - pg_table_is_visible(table_oid) - - boolean - is table visible in search path + + + pg_table_is_visible + + pg_table_is_visible ( table oid ) + boolean + + + Is table visible in search path? + (This works for all types of relations, including views, materialized + views, indexes, sequences and foreign tables.) + + - pg_ts_config_is_visible(config_oid) - - boolean - is text search configuration visible in search path + + + pg_ts_config_is_visible + + pg_ts_config_is_visible ( config oid ) + boolean + + + Is text search configuration visible in search path? + + - pg_ts_dict_is_visible(dict_oid) - - boolean - is text search dictionary visible in search path + + + pg_ts_dict_is_visible + + pg_ts_dict_is_visible ( dict oid ) + boolean + + + Is text search dictionary visible in search path? + + - pg_ts_parser_is_visible(parser_oid) - - boolean - is text search parser visible in search path + + + pg_ts_parser_is_visible + + pg_ts_parser_is_visible ( parser oid ) + boolean + + + Is text search parser visible in search path? + + - pg_ts_template_is_visible(template_oid) - - boolean - is text search template visible in search path + + + pg_ts_template_is_visible + + pg_ts_template_is_visible ( template oid ) + boolean + + + Is text search template visible in search path? + + - pg_type_is_visible(type_oid) - - boolean - is type (or domain) visible in search path + + + pg_type_is_visible + + pg_type_is_visible ( type oid ) + boolean + + + Is type (or domain) visible in search path? +
- - pg_collation_is_visible - - - pg_conversion_is_visible - - - pg_function_is_visible - - - pg_opclass_is_visible - - - pg_operator_is_visible - - - pg_opfamily_is_visible - - - pg_statistics_obj_is_visible - - - pg_table_is_visible - - - pg_ts_config_is_visible - - - pg_ts_dict_is_visible - - - pg_ts_parser_is_visible - - - pg_ts_template_is_visible - - - pg_type_is_visible - - - - Each function performs the visibility check for one type of database - object. Note that pg_table_is_visible can also be used - with views, materialized views, indexes, sequences and foreign tables; - pg_function_is_visible can also be used with - procedures and aggregates; - pg_type_is_visible 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 - and argument data type(s) earlier in the path. For operator - classes, both name and associated index access method are considered. - - 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 @@ -21935,134 +21971,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); type name in this way — if the name can be recognized at all, it must be visible. - - format_type - - - - pg_get_constraintdef - - - - pg_get_expr - - - - pg_get_functiondef - - - - pg_get_function_arguments - - - - pg_get_function_identity_arguments - - - - pg_get_function_result - - - - pg_get_indexdef - - - - pg_get_keywords - - - - pg_get_ruledef - - - - pg_get_serial_sequence - - - - pg_get_statisticsobjdef - - - - pg_get_triggerdef - - - - pg_get_userbyid - - - - pg_get_viewdef - - - - pg_index_column_has_property - - - - pg_index_has_property - - - - pg_indexam_has_property - - - - pg_options_to_table - - - - pg_tablespace_databases - - - - pg_tablespace_location - - - - pg_typeof - - - - collation for - - - - to_regclass - - - - to_regcollation - - - - to_regnamespace - - - - to_regrole - - - - to_regoper - - - - to_regoperator - - - - to_regproc - - - - to_regprocedure - - - - to_regtype - - lists functions that extract information from the system catalogs. @@ -22070,323 +21978,653 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); System Catalog Information Functions - + - Name Return Type Description + + + Function + + + Description + + - format_type(type_oid, typemod) - text - get SQL name of a data type + + + format_type + + format_type ( type oid, typemod integer ) + text + + + 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. + + - pg_get_constraintdef(constraint_oid) - text - get definition of a constraint + + + pg_get_constraintdef + + pg_get_constraintdef ( constraint oid , pretty boolean ) + text + + + Reconstructs the creating command for a constraint. + (This is a decompiled reconstruction, not the original text + of the command.) + + - pg_get_constraintdef(constraint_oid, pretty_bool) - text - get definition of a constraint + + + pg_get_expr + + pg_get_expr ( expr pg_node_tree, relation oid , pretty boolean ) + text + + + 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. + + - pg_get_expr(pg_node_tree, relation_oid) - text - decompile internal form of an expression, assuming that any Vars - in it refer to the relation indicated by the second parameter + + + pg_get_functiondef + + pg_get_functiondef ( func oid ) + text + + + 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 CREATE OR REPLACE FUNCTION + or CREATE OR REPLACE PROCEDURE statement. + + - pg_get_expr(pg_node_tree, relation_oid, pretty_bool) - text - decompile internal form of an expression, assuming that any Vars - in it refer to the relation indicated by the second parameter + + + pg_get_function_arguments + + pg_get_function_arguments ( func oid ) + text + + + Reconstructs the argument list of a function or procedure, in the form + it would need to appear in within CREATE FUNCTION + (including default values). + + - pg_get_functiondef(func_oid) - text - get definition of a function or procedure + + + pg_get_function_identity_arguments + + pg_get_function_identity_arguments ( func oid ) + text + + + Reconstructs the argument list necessary to identify a function or + procedure, in the form it would need to appear in within commands such + as ALTER FUNCTION. This form omits default values. + + - pg_get_function_arguments(func_oid) - text - get argument list of function's or procedure's definition (with default values) + + + pg_get_function_result + + pg_get_function_result ( func oid ) + text + + + Reconstructs the RETURNS clause of a function, in + the form it would need to appear in within CREATE + FUNCTION. Returns NULL for a procedure. + + - pg_get_function_identity_arguments(func_oid) - text - get argument list to identify a function or procedure (without default values) + + + pg_get_indexdef + + pg_get_indexdef ( index oid , column integer, pretty boolean ) + text + + + Reconstructs the creating command for an index. + (This is a decompiled reconstruction, not the original text + of the command.) If column is supplied and is + not zero, only the definition of that column is reconstructed. + + - pg_get_function_result(func_oid) - text - get RETURNS clause for function (returns null for a procedure) + + + pg_get_keywords + + pg_get_keywords () + setof record + ( word text, + catcode "char", + catdesc text ) + + + Returns a set of records describing the SQL keywords recognized by the + server. The word column contains the + keyword. The catcode column contains a + category code: U for an unreserved + keyword, C for a keyword that can be a column + name, T for a keyword that can be a type or + function name, or R for a fully reserved keyword. + The catdesc column contains a + possibly-localized string describing the category. + + - pg_get_indexdef(index_oid) - text - get CREATE INDEX command for index + + + pg_get_ruledef + + pg_get_ruledef ( rule oid , pretty boolean ) + text + + + Reconstructs the creating command for a rule. + (This is a decompiled reconstruction, not the original text + of the command.) + + - pg_get_indexdef(index_oid, column_no, pretty_bool) - text - get CREATE INDEX command for index, - or definition of just one index column when - column_no is not zero + + + pg_get_serial_sequence + + pg_get_serial_sequence ( table text, column text ) + text + + + 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 + (serial, smallserial, bigserial), + it is the sequence created for that serial column definition. + In the latter case, the association can be modified or removed + with ALTER SEQUENCE OWNED BY. + (This function probably should have been + called pg_get_owned_sequence; 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 + ). + + + A typical use is in reading the current value of the sequence for an + identity or serial column, for example: + +SELECT currval(pg_get_serial_sequence('sometable', 'id')); + + + - pg_get_keywords() - setof record - get list of SQL keywords and their categories + + + pg_get_statisticsobjdef + + pg_get_statisticsobjdef ( statobj oid ) + text + + + Reconstructs the creating command for an extended statistics object. + (This is a decompiled reconstruction, not the original text + of the command.) + + - pg_get_ruledef(rule_oid) - text - get CREATE RULE command for rule + + + pg_get_triggerdef + +pg_get_triggerdef ( trigger oid , pretty boolean ) + text + + + Reconstructs the creating command for a trigger. + (This is a decompiled reconstruction, not the original text + of the command.) + + - pg_get_ruledef(rule_oid, pretty_bool) - text - get CREATE RULE command for rule + + + pg_get_userbyid + + pg_get_userbyid ( role oid ) + name + + + Returns a role's name given its OID. + + - pg_get_serial_sequence(table_name, column_name) - text - get name of the sequence that a serial or identity column uses + + + pg_get_viewdef + + pg_get_viewdef ( view oid , pretty boolean ) + text + + + Reconstructs the underlying SELECT command for a + view or materialized view. (This is a decompiled reconstruction, not + the original text of the command.) + + - pg_get_statisticsobjdef(statobj_oid) - text - get CREATE STATISTICS command for extended statistics object + + pg_get_viewdef ( view oid, wrap_column integer ) + text + + + Reconstructs the underlying SELECT 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. + + - pg_get_triggerdef(trigger_oid) - text - get CREATE [ CONSTRAINT ] TRIGGER command for trigger + + pg_get_viewdef ( view text , pretty boolean ) + text + + + Reconstructs the underlying SELECT 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.) + + - pg_get_triggerdef(trigger_oid, pretty_bool) - text - get CREATE [ CONSTRAINT ] TRIGGER command for trigger + + + pg_index_column_has_property + + pg_index_column_has_property ( index regclass, column integer, property text ) + boolean + + + Tests whether an index column has the named property. + Common index column properties are listed in + . + (Note that extension access methods can define additional property + names for their indexes.) + NULL 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. + + - pg_get_userbyid(role_oid) - name - get role name with given OID + + + pg_index_has_property + + pg_index_has_property ( index regclass, property text ) + boolean + + + Tests whether an index has the named property. + Common index properties are listed in + . + (Note that extension access methods can define additional property + names for their indexes.) + NULL 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. + + - pg_get_viewdef(view_name) - text - get underlying SELECT command for view or materialized view (deprecated) + + + pg_indexam_has_property + + pg_indexam_has_property ( am oid, property text ) + boolean + + + Tests whether an index access method has the named property. + Access method properties are listed in + . + NULL 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. + + - pg_get_viewdef(view_name, pretty_bool) - text - get underlying SELECT command for view or materialized view (deprecated) + + + pg_options_to_table + + pg_options_to_table ( reloptions text[] ) + setof record + ( option_name text, + option_value text ) + + + Returns the set of storage options represented by a value from + pg_class.reloptions or + pg_attribute.attoptions. + + - pg_get_viewdef(view_oid) - text - get underlying SELECT command for view or materialized view + + + pg_tablespace_databases + + pg_tablespace_databases ( tablespace oid ) + setof oid + + + 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 pg_tablespace_databases + and query their pg_class catalogs. + + - pg_get_viewdef(view_oid, pretty_bool) - text - get underlying SELECT command for view or materialized view + + + pg_tablespace_location + + pg_tablespace_location ( tablespace oid ) + text + + + Returns the file system path that this tablespace is located in. + + - pg_get_viewdef(view_oid, wrap_column_int) - text - get underlying SELECT command for view or - materialized view; lines with fields are wrapped to specified - number of columns, pretty-printing is implied + + + pg_typeof + + pg_typeof ( "any" ) + regtype + + + 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 regtype, which is an OID alias type (see + ); this means that it is the same as an + OID for comparison purposes but displays as a type name. + + + For example: + +SELECT pg_typeof(33); + pg_typeof +----------- + integer + +SELECT typlen FROM pg_type WHERE oid = pg_typeof(33); + typlen +-------- + 4 + + + - pg_index_column_has_property(index_oid, column_no, prop_name) - boolean - test whether an index column has a specified property + + + COLLATION FOR + + COLLATION FOR ( "any" ) + text + + + 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 NULL is returned. If the argument is not of a + collatable data type, then an error is raised. + + + For example: + +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" + + + - pg_index_has_property(index_oid, prop_name) - boolean - test whether an index has a specified property + + + to_regclass + + to_regclass ( text ) + regclass + + + Translates a textual relation name to its OID. A similar result is + obtained by casting the string to type regclass (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - pg_indexam_has_property(am_oid, prop_name) - boolean - test whether an index access method has a specified property + + + to_regcollation + + to_regcollation ( text ) + regcollation + + + Translates a textual collation name to its OID. A similar result is + obtained by casting the string to type regcollation (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - pg_options_to_table(reloptions) - setof record - get the set of storage option name/value pairs + + + to_regnamespace + + to_regnamespace ( text ) + regnamespace + + + Translates a textual schema name to its OID. A similar result is + obtained by casting the string to type regnamespace (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - pg_tablespace_databases(tablespace_oid) - setof oid - get the set of database OIDs that have objects in the tablespace + + + to_regoper + + to_regoper ( text ) + regoper + + + Translates a textual operator name to its OID. A similar result is + obtained by casting the string to type regoper (see + ); however, this function will return + NULL 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. + + - pg_tablespace_location(tablespace_oid) - text - get the path in the file system that this tablespace is located in + + + to_regoperator + + to_regoperator ( text ) + regoperator + + + Translates a textual operator name (with parameter types) to its OID. A similar result is + obtained by casting the string to type regoperator (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - pg_typeof(any) - regtype - get the data type of any value + + + to_regproc + + to_regproc ( text ) + regproc + + + Translates a textual function or procedure name to its OID. A similar result is + obtained by casting the string to type regproc (see + ); however, this function will return + NULL 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. + + - collation for (any) - text - get the collation of the argument + + + to_regprocedure + + to_regprocedure ( text ) + regprocedure + + + Translates a textual function or procedure name (with argument types) to its OID. A similar result is + obtained by casting the string to type regprocedure (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - to_regclass(rel_name) - regclass - get the OID of the named relation + + + to_regrole + + to_regrole ( text ) + regrole + + + Translates a textual role name to its OID. A similar result is + obtained by casting the string to type regrole (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. + + - to_regcollation(coll_name) - regcollation - get the OID of the named collation - - - to_regnamespace(schema_name) - regnamespace - get the OID of the named schema - - - to_regoper(operator_name) - regoper - get the OID of the named operator - - - to_regoperator(operator_name) - regoperator - get the OID of the named operator - - - to_regrole(role_name) - regrole - get the OID of the named role - - - to_regproc(func_name) - regproc - get the OID of the named function - - - to_regprocedure(func_name) - regprocedure - get the OID of the named function - - - to_regtype(type_name) - regtype - get the OID of the named type + + + to_regtype + + to_regtype ( text ) + regtype + + + Translates a textual type name to its OID. A similar result is + obtained by casting the string to type regtype (see + ); however, this function will return + NULL rather than throwing an error if the name is + not found. Also unlike the cast, this does not accept + a numeric OID as input. +
- format_type 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. - - - - pg_get_keywords returns a set of records describing - the SQL keywords recognized by the server. The word column - contains the keyword. The catcode column contains a - category code: U for unreserved, C for column name, - T for type or function name, or R for reserved. - The catdesc column contains a possibly-localized string - describing the category. - - - - pg_get_constraintdef, - pg_get_indexdef, pg_get_ruledef, - pg_get_statisticsobjdef, and - pg_get_triggerdef, 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.) pg_get_expr 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. pg_get_viewdef reconstructs the - SELECT query that defines a view. Most of these functions come - in two variants, one of which can optionally pretty-print 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 pretty flag, which + if true causes the result to + be pretty-printed. 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 - PostgreSQL; avoid using pretty-printed output for dump - purposes. Passing false for the pretty-print parameter yields - the same result as the variant that does not have the parameter at all. - - - - pg_get_functiondef returns a complete - CREATE OR REPLACE FUNCTION statement for a function. - pg_get_function_arguments returns the argument list - of a function, in the form it would need to appear in within - CREATE FUNCTION. - pg_get_function_result similarly returns the - appropriate RETURNS clause for the function. - pg_get_function_identity_arguments returns the - argument list necessary to identify a function, in the form it - would need to appear in within ALTER FUNCTION, for - instance. This form omits default values. - - - - pg_get_serial_sequence 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 - (serial, smallserial, bigserial), it - is the sequence created for that serial column definition. In the latter - case, this association can be modified or removed with ALTER - SEQUENCE OWNED BY. (The function probably should have been called - pg_get_owned_sequence; its current name reflects the - fact that it has typically been used with serial - or bigserial 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 ). A typical use is in reading the - current value of a sequence for an identity or serial column, for example: - -SELECT currval(pg_get_serial_sequence('sometable', 'id')); - - - - - pg_get_userbyid extracts a role's name given - its OID. - - - - pg_index_column_has_property, - pg_index_has_property, and - pg_indexam_has_property return whether the - specified index column, index, or index access method possesses the named - property. NULL 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 - for column properties, - for index properties, and - for access method properties. - (Note that extension access methods can define additional property names - for their indexes.) + PostgreSQL; so avoid using pretty-printed output + for dump purposes. Passing false for + the pretty parameter yields the same result as + omitting the parameter. @@ -22520,99 +22758,6 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id'));
- - pg_options_to_table returns the set of storage - option name/value pairs - (option_name/option_value) when passed - pg_class.reloptions or - pg_attribute.attoptions. - - - - pg_tablespace_databases 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 - pg_tablespace_databases and query their - pg_class catalogs. - - - - pg_typeof 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 regtype, which is an OID alias type (see - ); this means that it is the same as an - OID for comparison purposes but displays as a type name. For example: - -SELECT pg_typeof(33); - - pg_typeof ------------ - integer -(1 row) - -SELECT typlen FROM pg_type WHERE oid = pg_typeof(33); - typlen --------- - 4 -(1 row) - - - - - The expression collation for returns the collation of the - value that is passed to it. Example: - -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) - - 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. - - - - The functions to_regclass, to_regcollation, - to_regnamespace, to_regoper, - to_regoperator, to_regrole, - to_regproc, to_regprocedure and - to_regtype translate relation, collation, schema, - operator, role, function, and type names (given as text) to - objects of the corresponding reg* type (see 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 - to_regproc and to_regoper, if the - given name matches multiple objects). - - - - pg_describe_object - - - - pg_identify_object - - - - pg_identify_object_as_address - - - - pg_get_object_address - - lists functions related to database object identification and addressing. @@ -22620,104 +22765,129 @@ SELECT collation for ('foo' COLLATE "de_DE"); Object Information and Addressing Functions - + - Name Return Type Description + + + Function + + + Description + + - pg_describe_object(classid oid, objid oid, objsubid integer) - text - get description of a database object + + + pg_describe_object + + pg_describe_object ( classid oid, objid oid, objsubid integer ) + text + + + 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 + pg_depend catalog. + + - pg_identify_object(classid oid, objid oid, objsubid integer) - type text, schema text, name text, identity text - get identity of a database object + + + pg_identify_object + + pg_identify_object ( classid oid, objid oid, objsubid integer ) + record + ( type text, + schema text, + name text, + identity text ) + + + 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. + type identifies the type of database object; + schema is the schema name that the object + belongs in, or NULL for object types that do not + belong to schemas; + name 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 NULL; + identity 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. + + - pg_identify_object_as_address(classid oid, objid oid, objsubid integer) - type text, object_names text[], object_args text[] - get external representation of a database object's address + + + pg_identify_object_as_address + + pg_identify_object_as_address ( classid oid, objid oid, objsubid integer ) + record + ( type text, + object_names text[], + object_args text[] ) + + + 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. + type identifies the type of database object; + object_names and + object_args + are text arrays that together form a reference to the object. + These three values can be passed + to pg_get_object_address to obtain the internal + address of the object. + + - pg_get_object_address(type text, object_names text[], object_args text[]) - classid oid, objid oid, objsubid integer - get address of a database object from its external representation + + + pg_get_object_address + + pg_get_object_address ( type text, object_names text[], object_args text[] ) + record + ( classid oid, + objid oid, + objsubid integer ) + + + 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 pg_depend; they can be passed to + other system functions such as pg_describe_object + or pg_identify_object. + classid is the OID of the system catalog + containing the object; + objid is the OID of the object itself, and + objsubid is the sub-object ID, or zero if none. + This function is the inverse + of pg_identify_object_as_address. +
- - pg_describe_object 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 - pg_depend catalog. - - - - pg_identify_object 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. - type identifies the type of database object; - schema is the schema name that the object belongs in, or - NULL for object types that do not belong to schemas; - name 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 NULL; - identity 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. - - - - pg_identify_object_as_address 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. - type identifies the type of database object; - object_names and object_args - are text arrays that together form a reference to the object. - These three values can be passed to - pg_get_object_address to obtain the internal address - of the object. - This function is the inverse of pg_get_object_address. - - - - pg_get_object_address 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 pg_depend - and can be passed to other system functions such as - pg_identify_object or pg_describe_object. - classid is the OID of the system catalog containing the - object; - objid is the OID of the object itself, and - objsubid is the sub-object ID, or zero if none. - This function is the inverse of pg_identify_object_as_address. - - - - col_description - - - - obj_description - - - - shobj_description - - comment about database objects @@ -22732,127 +22902,86 @@ SELECT collation for ('foo' COLLATE "de_DE"); Comment Information Functions - + - Name Return Type Description + + + Function + + + Description + + - col_description(table_oid, column_number) - text - get comment for a table column + + + col_description + + col_description ( table oid, column integer ) + text + + + Returns the comment for a table column, which is specified by the OID + of its table and its column number. + (obj_description cannot be used for table + columns, since columns do not have OIDs of their own.) + + - obj_description(object_oid, catalog_name) - text - get comment for a database object + + + obj_description + + obj_description ( object oid, catalog name ) + text + + + Returns the comment for a database object specified by its OID and the + name of the containing system catalog. For + example, obj_description(123456, 'pg_class') would + retrieve the comment for the table with OID 123456. + + - obj_description(object_oid) - text - get comment for a database object (deprecated) + + obj_description ( object oid ) + text + + + Returns the comment for a database object specified by its OID alone. + This is deprecated since there is no guarantee + that OIDs are unique across different system catalogs; therefore, the + wrong comment might be returned. + + - shobj_description(object_oid, catalog_name) - text - get comment for a shared database object + + + shobj_description + + shobj_description ( object oid, catalog name ) + text + + + Returns the comment for a shared database object specified by its OID + and the name of the containing system catalog. This is just + like obj_description 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. +
- - col_description returns the comment for a table - column, which is specified by the OID of its table and its column number. - (obj_description cannot be used for table columns - since columns do not have OIDs of their own.) - - - - The two-parameter form of obj_description returns the - comment for a database object specified by its OID and the name of the - containing system catalog. For example, - obj_description(123456,'pg_class') - would retrieve the comment for the table with OID 123456. - The one-parameter form of obj_description 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. - - - - shobj_description is used just like - obj_description 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. - - - - pg_current_xact_id - - - - pg_current_xact_id_if_assigned - - - - pg_current_snapshot - - - - pg_snapshot_xip - - - - pg_snapshot_xmax - - - - pg_snapshot_xmin - - - - pg_visible_in_snapshot - - - - pg_xact_status - - - - txid_current - - - - txid_current_if_assigned - - - - txid_current_snapshot - - - - txid_snapshot_xip - - - - txid_snapshot_xmax - - - - txid_snapshot_xmin - - - - txid_visible_in_snapshot - - - - txid_status - - The functions shown in provide server transaction information in an exportable form. The main @@ -22861,52 +22990,147 @@ SELECT collation for ('foo' COLLATE "de_DE"); - Transaction IDs and Snapshots - + Transaction ID and Snapshot Information Functions + - Name Return Type Description + + + Function + + + Description + + - pg_current_xact_id() - xid8 - get current transaction ID, assigning a new one if the current transaction does not have one + + + pg_current_xact_id + + pg_current_xact_id () + xid8 + + + 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). + + - pg_current_xact_id_if_assigned() - xid8 - same as pg_current_xact_id() but returns null instead of assigning a new transaction ID if none is already assigned + + + pg_current_xact_id_if_assigned + + pg_current_xact_id_if_assigned () + xid8 + + + Returns the current transaction's ID, or NULL 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.) + + - pg_xact_status(xid8) - text - report the status of the given transaction: committed, aborted, in progress, or null if the transaction ID is too old + + + pg_xact_status + + pg_xact_status ( xid8 ) + text + + + Reports the commit status of a recent transaction. + The result is one of in progress, + committed, or aborted, + 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 NULL. + 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 COMMIT is in progress. + Note that prepared transactions are reported as in + progress; applications must check pg_prepared_xacts + if they need to determine whether a transaction ID belongs to a + prepared transaction. + + - pg_current_snapshot() - pg_snapshot - get current snapshot + + + pg_current_snapshot + + pg_current_snapshot () + pg_snapshot + + + Returns a current snapshot, a data structure + showing which transaction IDs are now in-progress. + + - pg_snapshot_xip(pg_snapshot) - setof xid8 - get in-progress transaction IDs in snapshot + + + pg_snapshot_xip + + pg_snapshot_xip ( pg_snapshot ) + setof xid8 + + + Returns the set of in-progress transaction IDs contained in a snapshot. + + - pg_snapshot_xmax(pg_snapshot) - xid8 - get xmax of snapshot + + + pg_snapshot_xmax + + pg_snapshot_xmax ( pg_snapshot ) + xid8 + + + Returns the xmax of a snapshot. + + - pg_snapshot_xmin(pg_snapshot) - xid8 - get xmin of snapshot + + + pg_snapshot_xmin + + pg_snapshot_xmin ( pg_snapshot ) + xid8 + + + Returns the xmin of a snapshot. + + - pg_visible_in_snapshot(xid8, pg_snapshot) - boolean - is transaction ID visible in snapshot? (do not use with subtransaction IDs) + + + pg_visible_in_snapshot + + pg_visible_in_snapshot ( xid8, pg_snapshot ) + boolean + + + Is the given transaction ID visible 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. + @@ -22914,75 +23138,19 @@ SELECT collation for ('foo' COLLATE "de_DE"); The internal transaction ID type xid is 32 bits wide and - wraps around every 4 billion transactions. However, these functions use a - 64-bit variant xid8 that does not wrap around during the life + wraps around every 4 billion transactions. However, + the functions shown in use a + 64-bit type xid8 that does not wrap around during the life of an installation, and can be converted to xid by casting if required. The data type pg_snapshot stores information about transaction ID visibility at a particular moment in time. Its components are described in . + pg_snapshot's textual representation is + xmin:xmax:xip_list. + For example 10:20:10,14,15 means + xmin=10, xmax=20, xip_list=10, 14, 15. - - In releases of PostgreSQL before 13 there was - no xid8 type, so variants of these functions were provided - that used bigint. These older functions with - txid in their names are still supported for backward - compatibility, but may be removed from a future - release. See . - - -
- Transaction IDs and Snapshots (Deprecated Functions) - - - Name Return Type Description - - - - - txid_current() - bigint - see pg_current_xact_id() - - - txid_current_if_assigned() - bigint - see pg_current_xact_id_if_assigned() - - - txid_current_snapshot() - txid_snapshot - see pg_current_snapshot() - - - txid_snapshot_xip(txid_snapshot) - setof bigint - see pg_snapshot_xip() - - - txid_snapshot_xmax(txid_snapshot) - bigint - see pg_snapshot_xmax() - - - txid_snapshot_xmin(txid_snapshot) - bigint - see pg_snapshot_xmin() - - - txid_visible_in_snapshot(bigint, txid_snapshot) - boolean - see pg_visible_in_snapshot() - - - txid_status(bigint) - text - see pg_xact_status() - - - -
- Snapshot Components @@ -22994,98 +23162,222 @@ SELECT collation for ('foo' COLLATE "de_DE"); - - xmin + xmin Lowest transaction ID that was still active. All transaction IDs - less than xmin are either committed and visible, + less than xmin are either committed and visible, or rolled back and dead. - xmax + xmax One past the highest completed transaction ID. All transaction IDs - greater than or equal to xmax had not yet + greater than or equal to xmax had not yet completed as of the time of the snapshot, and thus are invisible. - xip_list + xip_list Transactions in progress at the time of the snapshot. A transaction - ID that is xmin <= X < xmax 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 xmin <= X < + xmax 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. -
- pg_snapshot's textual representation is - xmin:xmax:xip_list. - For example 10:20:10,14,15 means - xmin=10, xmax=20, xip_list=10, 14, 15. + In releases of PostgreSQL before 13 there was + no xid8 type, so variants of these functions were provided + that used bigint to represent a 64-bit XID, with a + correspondingly distinct snapshot data type txid_snapshot. + These older functions have txid in their names. They + are still supported for backward compatibility, but may be removed from a + future release. See . - - pg_xact_status(xid8) 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 COMMIT is in progress. - The status of a transaction will be reported as either - in progress, - committed, or aborted, 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 in progress; applications must - check pg_prepared_xacts if they - need to determine whether the transaction ID belongs to a prepared transaction. - - - - The functions shown in - 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 - configuration option is enabled - and only for transactions that were committed after it was enabled. - - - - Committed Transaction Information - +
+ Deprecated Transaction ID and Snapshot Information Functions + - Name Return Type Description + + + Function + + + Description + + - - pg_xact_commit_timestamp - pg_xact_commit_timestamp(xid) - - timestamp with time zone - get commit timestamp of a transaction + + + txid_current + + txid_current () + bigint + + + See pg_current_xact_id(). + - - pg_last_committed_xact - pg_last_committed_xact() - - xid xid, timestamp timestamp with time zone - get transaction ID and commit timestamp of latest committed transaction + + + txid_current_if_assigned + + txid_current_if_assigned () + bigint + + + See pg_current_xact_id_if_assigned(). + + + + + + + txid_current_snapshot + + txid_current_snapshot () + txid_snapshot + + + See pg_current_snapshot(). + + + + + + + txid_snapshot_xip + + txid_snapshot_xip ( txid_snapshot ) + setof bigint + + + See pg_snapshot_xip(). + + + + + + + txid_snapshot_xmax + + txid_snapshot_xmax ( txid_snapshot ) + bigint + + + See pg_snapshot_xmax(). + + + + + + + txid_snapshot_xmin + + txid_snapshot_xmin ( txid_snapshot ) + bigint + + + See pg_snapshot_xmin(). + + + + + + + txid_visible_in_snapshot + + txid_visible_in_snapshot ( bigint, txid_snapshot ) + boolean + + + See pg_visible_in_snapshot(). + + + + + + + txid_status + + txid_status ( bigint ) + text + + + See pg_xact_status(). + + + + +
+ + + The functions shown in + provide information about when past transactions were committed. + They only provide useful data when the + configuration option is + enabled, and only for transactions that were committed after it was + enabled. + + + + Committed Transaction Information Functions + + + + + Function + + + Description + + + + + + + + + pg_xact_commit_timestamp + + pg_xact_commit_timestamp ( xid ) + timestamp with time zone + + + Returns the commit timestamp of a transaction. + + + + + + + pg_last_committed_xact + + pg_last_committed_xact () + record + ( xid xid, + timestamp timestamp with time zone ) + + + Returns the transaction ID and commit timestamp of the latest + committed transaction. + @@ -23096,75 +23388,87 @@ SELECT collation for ('foo' COLLATE "de_DE"); print information initialized during initdb, 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 - , although in a form better suited - to SQL functions. + not specific to any one database. These functions provide most of the same + information, from the same source, as the + application.
Control Data Functions - + - Name Return Type Description + + + Function + + + Description + + - - pg_control_checkpoint - pg_control_checkpoint() - - record - - Returns information about current checkpoint state. - + + + pg_control_checkpoint + + pg_control_checkpoint () + record + + + Returns information about current checkpoint state, as shown in + . + - - pg_control_system - pg_control_system() - - record - - Returns information about current control file state. - + + + pg_control_system + + pg_control_system () + record + + + Returns information about current control file state, as shown in + . + - - pg_control_init - pg_control_init() - - record - - Returns information about cluster initialization state. - + + + pg_control_init + + pg_control_init () + record + + + Returns information about cluster initialization state, as shown in + . + - - pg_control_recovery - pg_control_recovery() - - record - - Returns information about recovery state. - + + + pg_control_recovery + + pg_control_recovery () + record + + + Returns information about recovery state, as shown in + . + -
- - pg_control_checkpoint returns a record, shown in - - - - <function>pg_control_checkpoint</function> Columns + <function>pg_control_checkpoint</function> Output Columns @@ -23176,92 +23480,92 @@ SELECT collation for ('foo' COLLATE "de_DE"); - checkpoint_lsn + checkpoint_lsn pg_lsn - redo_lsn + redo_lsn pg_lsn - redo_wal_file + redo_wal_file text - timeline_id + timeline_id integer - prev_timeline_id + prev_timeline_id integer - full_page_writes + full_page_writes boolean - next_xid + next_xid text - next_oid + next_oid oid - next_multixact_id + next_multixact_id xid - next_multi_offset + next_multi_offset xid - oldest_xid + oldest_xid xid - oldest_xid_dbid + oldest_xid_dbid oid - oldest_active_xid + oldest_active_xid xid - oldest_multi_xid + oldest_multi_xid xid - oldest_multi_dbid + oldest_multi_dbid oid - oldest_commit_ts_xid + oldest_commit_ts_xid xid - newest_commit_ts_xid + newest_commit_ts_xid xid - checkpoint_time + checkpoint_time timestamp with time zone @@ -23269,13 +23573,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
- - pg_control_system returns a record, shown in - - - - <function>pg_control_system</function> Columns + <function>pg_control_system</function> Output Columns @@ -23287,22 +23586,22 @@ SELECT collation for ('foo' COLLATE "de_DE"); - pg_control_version + pg_control_version integer - catalog_version_no + catalog_version_no integer - system_identifier + system_identifier bigint - pg_control_last_modified + pg_control_last_modified timestamp with time zone @@ -23310,13 +23609,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
- - pg_control_init returns a record, shown in - - - - <function>pg_control_init</function> Columns + <function>pg_control_init</function> Output Columns @@ -23328,57 +23622,57 @@ SELECT collation for ('foo' COLLATE "de_DE"); - max_data_alignment + max_data_alignment integer - database_block_size + database_block_size integer - blocks_per_segment + blocks_per_segment integer - wal_block_size + wal_block_size integer - bytes_per_wal_segment + bytes_per_wal_segment integer - max_identifier_length + max_identifier_length integer - max_index_columns + max_index_columns integer - max_toast_chunk_size + max_toast_chunk_size integer - large_object_chunk_size + large_object_chunk_size integer - float8_pass_by_value + float8_pass_by_value boolean - data_page_checksum_version + data_page_checksum_version integer @@ -23386,13 +23680,8 @@ SELECT collation for ('foo' COLLATE "de_DE");
- - pg_control_recovery returns a record, shown in - - - - <function>pg_control_recovery</function> Columns + <function>pg_control_recovery</function> Output Columns @@ -23404,27 +23693,27 @@ SELECT collation for ('foo' COLLATE "de_DE"); - min_recovery_end_lsn + min_recovery_end_lsn pg_lsn - min_recovery_end_timeline + min_recovery_end_timeline integer - backup_start_lsn + backup_start_lsn pg_lsn - backup_end_lsn + backup_end_lsn pg_lsn - end_of_backup_record_required + end_of_backup_record_required boolean @@ -23445,45 +23734,6 @@ SELECT collation for ('foo' COLLATE "de_DE"); Configuration Settings Functions - - shows the functions - available to query and alter run-time configuration parameters. - - -
- Configuration Settings Functions - - - Name Return Type Description - - - - - - - current_setting - - current_setting(setting_name [, missing_ok ]) - - text - get current value of setting - - - - - set_config - - set_config(setting_name, - new_value, - is_local) - - text - set parameter and return new value - - - -
- SET @@ -23499,62 +23749,84 @@ SELECT collation for ('foo' COLLATE "de_DE"); - The function current_setting yields the - current value of the setting setting_name. - It corresponds to the SQL command - SHOW. An example: - -SELECT current_setting('datestyle'); - - current_setting ------------------ - ISO, MDY -(1 row) - - - If there is no setting named setting_name, - current_setting throws an error - unless missing_ok is supplied and is - true. + shows the functions + available to query and alter run-time configuration parameters. - - set_config sets the parameter - setting_name to - new_value. If - is_local is true, the - new value will only apply to the current transaction. If you want - the new value to apply for the current session, use - false instead. The function corresponds to the - SQL command SET. An example: - -SELECT set_config('log_statement_stats', 'off', false); + + Configuration Settings Functions + + + + + Function + + + Description + + + Example(s) + + + - set_config ------------- - off -(1 row) - - + + + + + current_setting + + current_setting ( setting_name text , missing_ok boolean ) + text + + + Returns the current value of the + setting setting_name. If there is no such + setting, current_setting throws an error + unless missing_ok is supplied and + is true. This function corresponds to + the SQL command SHOW. + + + current_setting('datestyle') + ISO, MDY + + + + + + + set_config + + set_config ( + setting_name text, + new_value text, + is_local boolean ) + text + + + Sets the parameter setting_name + to new_value, and returns that value. + If is_local is true, the new + value will only apply for the current transaction. If you want the new + value to apply for the current session, use false + instead. This function corresponds to the SQL + command SET. + + + set_config('log_statement_stats', 'off', false) + off + + + + +
Server Signaling Functions - - pg_cancel_backend - - - pg_reload_conf - - - pg_rotate_logfile - - - pg_terminate_backend - - signal backend processes @@ -23568,60 +23840,95 @@ SELECT set_config('log_statement_stats', 'off', false); GRANT, with noted exceptions. + + Each of these functions returns true if + successful and false otherwise. + + Server Signaling Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_cancel_backend(pid int) - - boolean - Cancel a backend's current query. This is also allowed if the + + + pg_cancel_backend + + pg_cancel_backend ( pid integer ) + boolean + + + 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 pg_signal_backend, however only superusers can cancel superuser backends. - + + - - pg_reload_conf() - - boolean - Cause server processes to reload their configuration files + + + pg_reload_conf + + pg_reload_conf () + boolean + + + Causes all processes of the PostgreSQL + server to reload their configuration files. (This is initiated by + sending a SIGHUP signal to the postmaster + process, which in turn sends SIGHUP to each + of its children.) + + - - pg_rotate_logfile() - - boolean - Rotate server's log file + + + pg_rotate_logfile + + pg_rotate_logfile () + boolean + + + 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. + + - - pg_terminate_backend(pid int) - - boolean - Terminate a backend. This is also allowed if the calling role + + + pg_terminate_backend + + pg_terminate_backend ( pid integer ) + boolean + + + 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 pg_signal_backend, however only superusers can terminate superuser backends. - +
- - Each of these functions returns true if - successful and false otherwise. - - pg_cancel_backend and pg_terminate_backend send signals (SIGINT or SIGTERM @@ -23637,19 +23944,6 @@ SELECT set_config('log_statement_stats', 'off', false); pg_stat_activity view. - - pg_reload_conf sends a SIGHUP signal - to the server, causing configuration files - to be reloaded by all server processes. - - - - pg_rotate_logfile 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. - - @@ -23658,42 +23952,6 @@ SELECT set_config('log_statement_stats', 'off', false); backup - - pg_create_restore_point - - - pg_current_wal_flush_lsn - - - pg_current_wal_insert_lsn - - - pg_current_wal_lsn - - - pg_start_backup - - - pg_stop_backup - - - pg_is_in_backup - - - pg_backup_start_time - - - pg_switch_wal - - - pg_walfile_name - - - pg_walfile_name_offset - - - pg_wal_lsn_diff - The functions shown in pg_wal_lsn_diff). + + For details about proper usage of these functions, see + . + + Backup Control Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_create_restore_point(name text) - - pg_lsn - Create a named point for performing restore (restricted to superusers by default, but other users can be granted EXECUTE to run the function) + + + pg_create_restore_point + + pg_create_restore_point ( name text ) + pg_lsn + + + 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 + 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. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_current_wal_flush_lsn() - - pg_lsn - Get current write-ahead log flush location + + + pg_current_wal_flush_lsn + + pg_current_wal_flush_lsn () + pg_lsn + + + Returns the current write-ahead log flush location (see notes below). + + - - pg_current_wal_insert_lsn() - - pg_lsn - Get current write-ahead log insert location + + + pg_current_wal_insert_lsn + + pg_current_wal_insert_lsn () + pg_lsn + + + Returns the current write-ahead log insert location (see notes below). + + - - pg_current_wal_lsn() - - pg_lsn - Get current write-ahead log write location + + + pg_current_wal_lsn + + pg_current_wal_lsn () + pg_lsn + + + Returns the current write-ahead log write location (see notes below). + + - - pg_start_backup(label text , fast boolean , exclusive boolean ) - - pg_lsn - Prepare for performing on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function) + + + pg_start_backup + + pg_start_backup ( + label text + , fast boolean + , exclusive boolean + ) + pg_lsn + + + 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 true, + it specifies executing pg_start_backup 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). + + + When used in exclusive mode, this function writes a backup label file + (backup_label) and, if there are any links in + the pg_tblspc/ directory, a tablespace map file + (tablespace_map) 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 pg_stop_backup function, and should be + copied to the backup area by the user. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stop_backup() - - pg_lsn - Finish performing exclusive on-line backup (restricted to superusers by default, but other users can be granted EXECUTE to run the function) + + + pg_stop_backup + + pg_stop_backup ( + exclusive boolean + , wait_for_archive boolean + ) + setof record + ( lsn pg_lsn, + labelfile text, + spcmapfile text ) + + + Finishes performing an exclusive or non-exclusive on-line backup. + The exclusive parameter must match the + previous pg_start_backup call. + In an exclusive backup, pg_stop_backup removes + the backup label file and, if it exists, the tablespace map file + created by pg_start_backup. 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). + + + There is an optional second parameter of type boolean. + 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, pg_stop_backup will wait for + WAL to be archived when archiving is enabled. (On a standby, this + means that it will wait only when archive_mode = + always. If write activity on the primary is low, + it may be useful to run pg_switch_wal on the + primary in order to trigger an immediate segment switch.) + + + 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 pg_start_backup, 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. + + + The result of the function is a single record. + The lsn column holds the backup's ending + write-ahead log location (which again can be ignored). The second and + third columns are NULL when ending an exclusive + backup; after a non-exclusive backup they hold the desired contents of + the label and tablespace map files. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stop_backup(exclusive boolean , wait_for_archive boolean ) - - setof record - 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) + + pg_stop_backup () + pg_lsn + + + Finishes performing an exclusive on-line backup. This simplified + version is equivalent to pg_stop_backup(true, + true), except that it only returns the pg_lsn + result. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_is_in_backup() - - bool - True if an on-line exclusive backup is still in progress. + + + pg_is_in_backup + + pg_is_in_backup () + boolean + + + Returns true if an on-line exclusive backup is in progress. + + - - pg_backup_start_time() - - timestamp with time zone - Get start time of an on-line exclusive backup in progress. + + + pg_backup_start_time + + pg_backup_start_time () + timestamp with time zone + + + Returns the start time of the current on-line exclusive backup if one + is in progress, otherwise NULL. + + - - pg_switch_wal() - - pg_lsn - 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) + + + pg_switch_wal + + pg_switch_wal () + pg_lsn + + + 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, pg_switch_wal does nothing and + returns the start location of the write-ahead log file currently in + use. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_walfile_name(lsn pg_lsn) - - text - Convert write-ahead log location to file name + + + pg_walfile_name + + pg_walfile_name ( lsn pg_lsn ) + text + + + Converts a write-ahead log location to the name of the WAL file + holding that location. + + - - pg_walfile_name_offset(lsn pg_lsn) - - text, integer - Convert write-ahead log location to file name and decimal byte offset within file + + + pg_walfile_name_offset + + pg_walfile_name_offset ( lsn pg_lsn ) + record + ( file_name text, + file_offset integer ) + + + Converts a write-ahead log location to a WAL file name and byte offset + within that file. + + - - pg_wal_lsn_diff(lsn pg_lsn, lsn pg_lsn) - - numeric - Calculate the difference between two write-ahead log locations + + + pg_wal_lsn_diff + + pg_wal_lsn_diff ( lsn pg_lsn, lsn pg_lsn ) + numeric + + + Calculates the difference in bytes between two write-ahead log + locations. This can be used + with pg_stat_replication or some of the + functions shown in to + get the replication lag. +
- pg_start_backup 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 (backup_label) and, if there are any links - in the pg_tblspc/ directory, a tablespace map file - (tablespace_map) 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 - pg_stop_backup function, and should be written to the backup - by the caller. - - -postgres=# select pg_start_backup('label_goes_here'); - pg_start_backup ------------------ - 0/D4445B8 -(1 row) - - There is an optional second parameter of type boolean. If true, - it specifies executing pg_start_backup as quickly as - possible. This forces an immediate checkpoint which will cause a - spike in I/O operations, slowing any concurrently executing queries. - - - - In an exclusive backup, pg_stop_backup removes the label file - and, if it exists, the tablespace_map file created by - pg_start_backup. In a non-exclusive backup, the contents of - the backup_label and tablespace_map 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 boolean. If false, the pg_stop_backup - 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, pg_stop_backup - will wait for WAL to be archived when archiving is enabled; on the standby, - this means that it will wait only when archive_mode = always. - If write activity on the primary is low, it may be useful to run - pg_switch_wal on the primary in order to trigger - an immediate segment switch. - - - - 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 - pg_start_backup, 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. - - - - pg_switch_wal 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, - pg_switch_wal does nothing and returns the start location - of the write-ahead log file currently in use. - - - - pg_create_restore_point 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 - 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. - - - - pg_current_wal_lsn displays the current write-ahead log write - location in the same format used by the above functions. Similarly, - pg_current_wal_insert_lsn displays the current write-ahead log - insertion location and pg_current_wal_flush_lsn displays the - current write-ahead log flush location. The insertion location is the logical - 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. + pg_current_wal_lsn displays the current write-ahead + log write location in the same format used by the above functions. + Similarly, pg_current_wal_insert_lsn displays the + current write-ahead log insertion location + and pg_current_wal_flush_lsn displays the current + write-ahead log flush location. The insertion location is + the logical 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. You can use pg_walfile_name_offset 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 pg_lsn value. For example: postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - file_name | file_offset + file_name | file_offset --------------------------+------------- 00000001000000000000000D | 4039624 (1 row) @@ -23923,120 +24306,107 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); needs to be archived. - - pg_wal_lsn_diff calculates the difference in bytes - between two write-ahead log locations. It can be used with - pg_stat_replication or some functions shown in - to get the replication lag. - - - - For details about proper usage of these functions, see - . - - Recovery Control Functions - - pg_is_in_recovery - - - pg_last_wal_receive_lsn - - - pg_last_wal_replay_lsn - - - pg_last_xact_replay_timestamp - - The functions shown in 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. Recovery Information Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_is_in_recovery() - - bool - True if recovery is still in progress. - + + + pg_is_in_recovery + + pg_is_in_recovery () + boolean + + + Returns true if recovery is still in progress. + + - - pg_last_wal_receive_lsn() - - pg_lsn - 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. - + + + pg_last_wal_receive_lsn + + pg_last_wal_receive_lsn () + pg_lsn + + + 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 NULL. + + - - pg_last_wal_replay_lsn() - - pg_lsn - 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. - + + + pg_last_wal_replay_lsn + + pg_last_wal_replay_lsn () + pg_lsn + + + 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 NULL. + + - - pg_last_xact_replay_timestamp() - - timestamp with time zone - 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. - + + + pg_last_xact_replay_timestamp + + pg_last_xact_replay_timestamp () + timestamp with time zone + + + 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 NULL. 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 NULL. +
- - pg_is_wal_replay_paused - - - pg_promote - - - pg_wal_replay_pause - - - pg_wal_replay_resume - - The functions shown in control the progress of recovery. @@ -24045,77 +24415,109 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Recovery Control Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_is_wal_replay_paused() - - bool - True if recovery is paused. - + + + pg_is_wal_replay_paused + + pg_is_wal_replay_paused () + boolean + + + Returns true if recovery is paused. + + - - pg_promote(wait boolean DEFAULT true, wait_seconds integer DEFAULT 60) - - boolean - - Promotes a physical standby server. With wait - set to true (the default), the function waits until - promotion is completed or wait_seconds seconds - have passed, and returns true if promotion is - successful and false otherwise. + + + pg_promote + + pg_promote ( wait boolean DEFAULT true, wait_seconds integer DEFAULT 60 ) + boolean + + + Promotes a standby server to primary status. + With wait set to true (the + default), the function waits until promotion is completed + or wait_seconds seconds have passed, and + returns true if promotion is successful + and false otherwise. If wait is set to false, the - function returns true immediately after sending - SIGUSR1 to the postmaster to trigger the promotion. + function returns true immediately after sending a + SIGUSR1 signal to the postmaster to trigger + promotion. + + This function is restricted to superusers by default, but other users can be granted EXECUTE to run the function. - + + - - pg_wal_replay_pause() - - void - Pauses recovery immediately (restricted to superusers by default, but other users can be granted EXECUTE to run the function). - + + + pg_wal_replay_pause + + pg_wal_replay_pause () + void + + + 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. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_wal_replay_resume() - - void - Restarts recovery if it was paused (restricted to superusers by default, but other users can be granted EXECUTE to run the function). - + + + pg_wal_replay_resume + + pg_wal_replay_resume () + void + + + Restarts recovery if it was paused. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. +
- - 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. - - pg_wal_replay_pause and pg_wal_replay_resume 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. 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. @@ -24125,10 +24527,6 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Snapshot Synchronization Functions - - pg_export_snapshot - - PostgreSQL allows database sessions to synchronize their snapshots. A snapshot determines which data is visible to the @@ -24161,45 +24559,51 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Snapshot Synchronization Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_export_snapshot() - - text - Save the current snapshot and return its identifier + + + pg_export_snapshot + + pg_export_snapshot () + text + + + Saves the transaction's current snapshot and returns + a text 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 READ COMMITTED + transactions, since in REPEATABLE READ and higher + isolation levels, transactions use the same snapshot throughout their + lifetime. Once a transaction has exported any snapshots, it cannot be + prepared with . +
- - The function pg_export_snapshot saves the current snapshot - and returns a text 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 READ - COMMITTED transactions, since in REPEATABLE READ and - higher isolation levels, transactions use the same snapshot throughout - their lifetime. Once a transaction has exported any snapshots, it cannot - be prepared with . - - - - See for details of how to use an - exported snapshot. - - Replication Functions + Replication Management Functions The functions shown @@ -24210,7 +24614,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); 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 REPLICATION privilege. @@ -24228,27 +24632,31 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); - Replication <acronym>SQL</acronym> Functions - + Replication Management Functions + - Function - Return Type - Description + + Function + + + Description + + - + pg_create_physical_replication_slot - pg_create_physical_replication_slot(slot_name name , immediately_reserve boolean, temporary boolean) - - - (slot_name name, lsn pg_lsn) - - + pg_create_physical_replication_slot ( slot_name name , immediately_reserve boolean, temporary boolean ) + record + ( slot_name name, + lsn pg_lsn ) + + Creates a new physical replication slot named slot_name. The optional second parameter, when true, specifies that the LSN for this @@ -24259,108 +24667,109 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); see . The optional third parameter, temporary, 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 CREATE_REPLICATION_SLOT ... PHYSICAL. - - - - - - pg_drop_replication_slot - - pg_drop_replication_slot(slot_name name) - - - void - - - Drops the physical or logical replication slot - named slot_name. Same as replication protocol - command DROP_REPLICATION_SLOT. For logical slots, this must - be called when connected to the same database the slot was created on. - + - + + + pg_drop_replication_slot + + pg_drop_replication_slot ( slot_name name ) + void + + + Drops the physical or logical replication slot + named slot_name. Same as replication protocol + command DROP_REPLICATION_SLOT. For logical slots, this must + be called while connected to the same database the slot was created on. + + + + + pg_create_logical_replication_slot - pg_create_logical_replication_slot(slot_name name, plugin name , temporary boolean) - - - (slot_name name, lsn pg_lsn) - - + pg_create_logical_replication_slot ( slot_name name, plugin name , temporary boolean ) + record + ( slot_name name, + lsn pg_lsn ) + + Creates a new logical (decoding) replication slot named slot_name using the output plugin plugin. The optional third parameter, temporary, 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 CREATE_REPLICATION_SLOT ... LOGICAL. - + - + pg_copy_physical_replication_slot - pg_copy_physical_replication_slot(src_slot_name name, dst_slot_name name , temporary boolean) - - - (slot_name name, lsn pg_lsn) - - + pg_copy_physical_replication_slot ( src_slot_name name, dst_slot_name name , temporary boolean ) + record + ( slot_name name, + lsn pg_lsn ) + + Copies an existing physical replication slot named src_slot_name to a physical replication slot named dst_slot_name. The copied physical slot starts to reserve WAL from the same LSN as the source slot. temporary is optional. If temporary is omitted, the same value as the source slot is used. - + - + pg_copy_logical_replication_slot - pg_copy_logical_replication_slot(src_slot_name name, dst_slot_name name , temporary boolean , plugin name) - - - (slot_name name, lsn pg_lsn) - - - Copies an existing logical replication slot named src_slot_name - to a logical replication slot named dst_slot_name - while changing the output plugin and persistence. The copied logical slot starts - from the same LSN as the source logical slot. Both - temporary and plugin are optional. - If temporary or plugin are omitted, - the same values as the source logical slot are used. - + pg_copy_logical_replication_slot ( src_slot_name name, dst_slot_name name , temporary boolean , plugin name ) + record + ( slot_name name, + lsn pg_lsn ) + + + Copies an existing logical replication slot + named src_slot_name to a logical replication + slot named dst_slot_name, optionally changing + the output plugin and persistence. The copied logical slot starts + from the same LSN as the source logical slot. Both + temporary and plugin are + optional; if they are omitted, the values of the source slot are used. + - + pg_logical_slot_get_changes - pg_logical_slot_get_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - - - (lsn pg_lsn, xid xid, data text) - - + pg_logical_slot_get_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) + setof record + ( lsn pg_lsn, + xid xid, + data text ) + + Returns changes in the slot slot_name, starting - from the point at which since changes have been consumed last. If - upto_lsn and upto_nchanges are NULL, + from the point from which changes have been consumed last. If + upto_lsn + and upto_nchanges are NULL, logical decoding will continue until end of WAL. If upto_lsn is non-NULL, decoding will include only those transactions which commit prior to the specified LSN. If @@ -24369,314 +24778,275 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); 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. - + - + pg_logical_slot_peek_changes - pg_logical_slot_peek_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - - - (lsn pg_lsn, xid xid, data text) - - + pg_logical_slot_peek_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) + setof record + ( lsn pg_lsn, + xid xid, + data text ) + + Behaves just like the pg_logical_slot_get_changes() function, except that changes are not consumed; that is, they will be returned again on future calls. - + - + pg_logical_slot_get_binary_changes - pg_logical_slot_get_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - - - (lsn pg_lsn, xid xid, data bytea) - - + pg_logical_slot_get_binary_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) + setof record + ( lsn pg_lsn, + xid xid, + data bytea ) + + Behaves just like the pg_logical_slot_get_changes() function, except that changes are returned as bytea. - + - + pg_logical_slot_peek_binary_changes - pg_logical_slot_peek_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) - - - (lsn pg_lsn, xid xid, data bytea) - - + pg_logical_slot_peek_binary_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) + setof record + ( lsn pg_lsn, + xid xid, + data bytea ) + + Behaves just like - the pg_logical_slot_get_changes() function, - except that changes are returned as bytea and that - changes are not consumed; that is, they will be returned again - on future calls. - + the pg_logical_slot_peek_changes() function, + except that changes are returned as bytea. + - + pg_replication_slot_advance - pg_replication_slot_advance(slot_name name, upto_lsn pg_lsn) - - - (slot_name name, end_lsn pg_lsn) - bool - - + pg_replication_slot_advance ( slot_name name, upto_lsn pg_lsn ) + record + ( slot_name name, + end_lsn pg_lsn ) + + Advances the current confirmed position of a replication slot named slot_name. 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. - + - + pg_replication_origin_create - pg_replication_origin_create(node_name text) - - - oid - - - Create a replication origin with the given external - name, and return the internal id assigned to it. - + pg_replication_origin_create ( node_name text ) + oid + + + Creates a replication origin with the given external + name, and returns the internal ID assigned to it. + - + pg_replication_origin_drop - pg_replication_origin_drop(node_name text) - - - void - - - Delete a previously created replication origin, including any + pg_replication_origin_drop ( node_name text ) + void + + + Deletes a previously-created replication origin, including any associated replay progress. - + - + pg_replication_origin_oid - pg_replication_origin_oid(node_name text) - - - oid - - - Lookup a replication origin by name and return the internal id. If no - corresponding replication origin is found an error is thrown. - + pg_replication_origin_oid ( node_name text ) + oid + + + Looks up a replication origin by name and returns the internal ID. If + no such replication origin is found an error is thrown. + - + pg_replication_origin_session_setup - pg_replication_origin_session_setup(node_name text) - - - void - - - Mark the current session as replaying from the given - origin, allowing replay progress to be tracked. Use - pg_replication_origin_session_reset to revert. - Can only be used if no previous origin is configured. - + pg_replication_origin_session_setup ( node_name text ) + void + + + 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 pg_replication_origin_session_reset to undo. + - + pg_replication_origin_session_reset - pg_replication_origin_session_reset() - - - void - - - Cancel the effects + pg_replication_origin_session_reset () + void + + + Cancels the effects of pg_replication_origin_session_setup(). - + - + pg_replication_origin_session_is_setup - pg_replication_origin_session_is_setup() - - - bool - - - Has a replication origin been configured in the current session? - + pg_replication_origin_session_is_setup () + boolean + + + Returns true if a replication origin has been selected in the + current session. + - + pg_replication_origin_session_progress - pg_replication_origin_session_progress(flush bool) - - - pg_lsn - - - Return the replay location for the replication origin configured in + pg_replication_origin_session_progress ( flush boolean ) + pg_lsn + + + Returns the replay location for the replication origin selected in the current session. The parameter flush determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. - + - + pg_replication_origin_xact_setup - pg_replication_origin_xact_setup(origin_lsn pg_lsn, origin_timestamp timestamptz) - - - void - - - Mark the current transaction as replaying a transaction that has + pg_replication_origin_xact_setup ( origin_lsn pg_lsn, origin_timestamp timestamp with time zone ) + void + + + Marks the current transaction as replaying a transaction that has committed at the given LSN and timestamp. Can - only be called when a replication origin has previously been - configured using - pg_replication_origin_session_setup(). - + only be called when a replication origin has been selected + using pg_replication_origin_session_setup. + - + pg_replication_origin_xact_reset - pg_replication_origin_xact_reset() - - - void - - - Cancel the effects of + pg_replication_origin_xact_reset () + void + + + Cancels the effects of pg_replication_origin_xact_setup(). - + - + pg_replication_origin_advance - pg_replication_origin_advance(node_name text, lsn pg_lsn) - - - void - - - 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. - + pg_replication_origin_advance ( node_name text, lsn pg_lsn ) + void + + + 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. + - + pg_replication_origin_progress - pg_replication_origin_progress(node_name text, flush bool) - - - pg_lsn - - - Return the replay location for the given replication origin. The + pg_replication_origin_progress ( node_name text, flush boolean ) + pg_lsn + + + Returns the replay location for the given replication origin. The parameter flush determines whether the corresponding local transaction will be guaranteed to have been flushed to disk or not. - + - + pg_logical_emit_message - pg_logical_emit_message(transactional bool, prefix text, content text) - - - pg_lsn - - - Emit text logical decoding message. This can be used to pass generic - messages to logical decoding plugins through WAL. The parameter - transactional 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 - prefix is textual prefix used by the logical - decoding plugins to easily recognize interesting messages for them. - The content is the text of the message. - + pg_logical_emit_message ( transactional boolean, prefix text, content text ) + pg_lsn + + + pg_logical_emit_message ( transactional boolean, prefix text, content bytea ) + pg_lsn + + + Emits a logical decoding message. This can be used to pass generic + messages to logical decoding plugins through + WAL. The transactional 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 prefix parameter is a + textual prefix that can be used by logical decoding plugins to easily + recognize messages that are interesting for them. + The content parameter is the content of the + message, given either in text or binary form. + - - - - pg_logical_emit_message(transactional bool, prefix text, content bytea) - - - pg_lsn - - - Emit binary logical decoding message. This can be used to pass generic - messages to logical decoding plugins through WAL. The parameter - transactional 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 - prefix is textual prefix used by the logical - decoding plugins to easily recognize interesting messages for them. - The content is the binary content of the - message. - - -
@@ -24688,257 +25058,213 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); The functions shown in 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, NULL is returned. - - pg_column_size - - - pg_database_size - - - pg_indexes_size - - - pg_relation_size - - - pg_size_bytes - - - pg_size_pretty - - - pg_table_size - - - pg_tablespace_size - - - pg_total_relation_size - - Database Object Size Functions - + - Name Return Type Description + + + Function + + + Description + - pg_column_size(any) - int - Number of bytes used to store a particular value (possibly compressed) + + + pg_column_size + + pg_column_size ( "any" ) + integer + + + 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. + + - - pg_database_size(oid) - - bigint - Disk space used by the database with the specified OID + + + pg_database_size + + pg_database_size ( name ) + bigint + + + pg_database_size ( oid ) + bigint + + + Computes the total disk space used by the database with the specified + name or OID. To use this function, you must + have CONNECT privilege on the specified database + (which is granted by default) or be a member of + the pg_read_all_stats role. + + - - pg_database_size(name) - - bigint - Disk space used by the database with the specified name + + + pg_indexes_size + + pg_indexes_size ( regclass ) + bigint + + + Computes the total disk space used by indexes attached to the + specified table. + + - - pg_indexes_size(regclass) - - bigint - - Total disk space used by indexes attached to the specified table - + + + pg_relation_size + + pg_relation_size ( relation regclass , fork text ) + bigint + + + Computes the disk space used by one fork of the + specified relation. (Note that for most purposes it is more + convenient to use the higher-level + functions pg_total_relation_size + or pg_table_size, 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: + + + + main returns the size of the main + data fork of the relation. + + + + + fsm returns the size of the Free Space Map + (see ) associated with the relation. + + + + + vm returns the size of the Visibility Map + (see ) associated with the relation. + + + + + init returns the size of the initialization + fork, if any, associated with the relation. + + + + + - - pg_relation_size(relation regclass, fork text) - - bigint - - Disk space used by the specified fork ('main', - 'fsm', 'vm', or 'init') - of the specified table or index - + + + pg_size_bytes + + pg_size_bytes ( text ) + bigint + + + Converts a size in human-readable format (as returned + by pg_size_pretty) into bytes. + + - - pg_relation_size(relation regclass) - - bigint - - Shorthand for pg_relation_size(..., 'main') - + + + pg_size_pretty + + pg_size_pretty ( bigint ) + text + + + pg_size_pretty ( numeric ) + text + + + 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 10242 = 1048576 bytes, and so on. + + - - pg_size_bytes(text) - - bigint - - Converts a size in human-readable format with size units into bytes - + + + pg_table_size + + pg_table_size ( regclass ) + bigint + + + Computes the disk space used by the specified table, excluding indexes + (but including its TOAST table if any, free space map, and visibility + map). + + - - pg_size_pretty(bigint) - - text - - Converts a size in bytes expressed as a 64-bit integer into a - human-readable format with size units - + + + pg_tablespace_size + + pg_tablespace_size ( name ) + bigint + + + pg_tablespace_size ( oid ) + bigint + + + Computes the total disk space used in the tablespace with the + specified name or OID. To use this function, you must + have CREATE privilege on the specified tablespace + or be a member of the pg_read_all_stats role, + unless it is the default tablespace for the current database. + + - - pg_size_pretty(numeric) - - text - - Converts a size in bytes expressed as a numeric value into a - human-readable format with size units - - - - - pg_table_size(regclass) - - bigint - - Disk space used by the specified table, excluding indexes - (but including TOAST, free space map, and visibility map) - - - - - pg_tablespace_size(oid) - - bigint - Disk space used by the tablespace with the specified OID - - - - pg_tablespace_size(name) - - bigint - Disk space used by the tablespace with the specified name - - - - pg_total_relation_size(regclass) - - bigint - - Total disk space used by the specified table, - including all indexes and TOAST data - + + + pg_total_relation_size + + pg_total_relation_size ( regclass ) + bigint + + + Computes the total disk space used by the specified table, including + all indexes and TOAST data. The result is + equivalent to pg_table_size + + pg_indexes_size. +
- - pg_column_size shows the space used to store any individual - data value. - - - - pg_total_relation_size 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 pg_table_size - + pg_indexes_size. - - - - pg_table_size 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.) - - - - pg_indexes_size accepts the OID or name of a table and - returns the total disk space used by all the indexes attached to that - table. - - - - pg_database_size and pg_tablespace_size - accept the OID or name of a database or tablespace, and return the total - disk space used therein. To use pg_database_size, - you must have CONNECT permission on the specified database - (which is granted by default), or be a member of the pg_read_all_stats - role. To use pg_tablespace_size, you must have - CREATE permission on the specified tablespace, or be a member - of the pg_read_all_stats role unless it is the default tablespace for - the current database. - - - - pg_relation_size 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 pg_total_relation_size - or pg_table_size, 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: - - - - 'main' returns the size of the main - data fork of the relation. - - - - - 'fsm' returns the size of the Free Space Map - (see ) associated with the relation. - - - - - 'vm' returns the size of the Visibility Map - (see ) associated with the relation. - - - - - 'init' returns the size of the initialization - fork, if any, associated with the relation. - - - - - - - pg_size_pretty 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. - - - - pg_size_bytes 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. - - - - - The units kB, MB, GB and TB used by the functions - pg_size_pretty and pg_size_bytes are defined - using powers of 2 rather than powers of 10, so 1kB is 1024 bytes, 1MB is - 10242 = 1048576 bytes, and so on. - - - The functions above that operate on tables or indexes accept a regclass argument, which is simply the OID of the table or index @@ -24951,92 +25277,83 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); the table name. - - If an OID that does not represent an existing object is passed as - argument to one of the above functions, NULL is returned. - - The functions shown in assist in identifying the specific disk files associated with database objects. - - pg_relation_filenode - - - pg_relation_filepath - - - pg_filenode_relation - - Database Object Location Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_relation_filenode(relation regclass) - - oid - - Filenode number of the specified relation - + + + pg_relation_filenode + + pg_relation_filenode ( relation regclass ) + oid + + + Returns the filenode number currently assigned to the + specified relation. The filenode is the base component of the file + name(s) used for the relation (see + for more information). + For most relations the result is the same as + pg_class.relfilenode, + but for certain system catalogs relfilenode + 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. + + - - pg_relation_filepath(relation regclass) - - text - - File path name of the specified relation - + + + pg_relation_filepath + + pg_relation_filepath ( relation regclass ) + text + + + Returns the entire file path name (relative to the database cluster's + data directory, PGDATA) of the relation. + + - - pg_filenode_relation(tablespace oid, filenode oid) - - regclass - - Find the relation associated with a given tablespace and filenode - + + + pg_filenode_relation + + pg_filenode_relation ( tablespace oid, filenode oid ) + regclass + + + Returns a relation's OID given the tablespace OID and filenode it is + stored under. This is essentially the inverse mapping of + pg_relation_filepath. For a relation in the + database's default tablespace, the tablespace can be specified as zero. + Returns NULL if no relation in the current database + is associated with the given values. +
- - pg_relation_filenode accepts the OID or name of a table, - index, sequence, or toast table, and returns the filenode number - currently assigned to it. The filenode is the base component of the file - name(s) used for the relation (see - for more information). For most tables the result is the same as - pg_class.relfilenode, but for certain - system catalogs relfilenode 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. - - - - pg_relation_filepath is similar to - pg_relation_filenode, but it returns the entire file path name - (relative to the database cluster's data directory PGDATA) of - the relation. - - - - pg_filenode_relation is the reverse of - pg_relation_filenode. Given a tablespace OID and - a filenode, it returns the associated relation's OID. For a table - in the database's default tablespace, the tablespace can be specified as 0. - - lists functions used to manage collations. @@ -25044,150 +25361,165 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Collation Management Functions - + - Name Return Type Description + + + Function + + + Description + + - - pg_collation_actual_version - pg_collation_actual_version(oid) - - text - Return actual version of collation from operating system + + + pg_collation_actual_version + + pg_collation_actual_version ( oid ) + text + + + 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 + pg_collation.collversion, + then objects depending on the collation might need to be rebuilt. See + also . + + - - pg_import_system_collations - pg_import_system_collations(schema regnamespace) - - integer - Import operating system collations + + + pg_import_system_collations + + pg_import_system_collations ( schema regnamespace ) + integer + + + Adds collations to the system + catalog pg_collation based on all the locales + it finds in the operating system. This is + what initdb uses; see + 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 pg_collation 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 schema parameter would typically + be pg_catalog, 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. +
- pg_collation_actual_version 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 pg_collation.collversion, then objects depending on - the collation might need to be rebuilt. See also - . - - - - pg_import_system_collations adds collations to the system - catalog pg_collation based on all the - locales it finds in the operating system. This is - what initdb uses; - see 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 pg_collation 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 schema parameter would typically - be pg_catalog, 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. + lists functions that provide + information about the structure of partitioned tables. Partitioning Information Functions - + - Name Return Type Description + + + Function + + + Description + + - - pg_partition_tree - pg_partition_tree(regclass) - - setof record - - List information about tables or indexes in a partition tree for a + + + pg_partition_tree + + pg_partition_tree ( regclass ) + setof record + ( relid regclass, + parentrelid regclass, + isleaf boolean, + level integer ) + + + 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 0 for the input table - or index in its role as the root of the partition tree, - 1 for its partitions, 2 for - their partitions, and so on. - + 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. + + - - pg_partition_ancestors - pg_partition_ancestors(regclass) - - setof regclass - - List the ancestor relations of the given partition, - including the partition itself. - + + + pg_partition_ancestors + + pg_partition_ancestors ( regclass ) + setof regclass + + + 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. + + - - pg_partition_root - pg_partition_root(regclass) - - regclass - - Return the top-most parent of a partition tree to which the given - relation belongs. - + + + pg_partition_root + + pg_partition_root ( regclass ) + regclass + + + Returns the top-most parent of the partition tree to which the given + relation belongs. Returns NULL if the relation + does not exist or is not a partition or partitioned table. +
- To check the total size of the data contained in - measurement table described in - , one could use the + For example, to check the total size of the data contained in a + partitioned table measurement, one could use the following query: - - -=# 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'); + Index Maintenance Functions - - brin_summarize_new_values - - - - gin_clean_pending_list - - - - brin_summarize_range - - - - brin_desummarize_range - - 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. @@ -25195,66 +25527,90 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Index Maintenance Functions - + - Name Return Type Description + + + Function + + + Description + + - - brin_summarize_new_values(index regclass) - - integer - summarize page ranges not already summarized + + + brin_summarize_new_values + + brin_summarize_new_values ( index regclass ) + integer + + + 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. + + - - brin_summarize_range(index regclass, blockNumber bigint) - - integer - summarize the page range covering the given block, if not already summarized + + + brin_summarize_range + + brin_summarize_range ( index regclass, blockNumber bigint ) + integer + + + Summarizes the page range covering the given block, if not already + summarized. This is + like brin_summarize_new_values except that it + only processes the page range that covers the given table block number. + + - - brin_desummarize_range(index regclass, blockNumber bigint) - - integer - de-summarize the page range covering the given block, if summarized + + + brin_desummarize_range + + brin_desummarize_range ( index regclass, blockNumber bigint ) + void + + + Removes the BRIN index tuple that summarizes the page range covering + the given table block, if there is one. + + - - gin_clean_pending_list(index regclass) - - bigint - move GIN pending list entries into main index structure + + + gin_clean_pending_list + + gin_clean_pending_list ( index regclass ) + bigint + + + Cleans up the pending 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 fastupdate option disabled, no cleanup happens + and the result is zero, because the index doesn't have a pending list. + See and + for details about the pending list and fastupdate + option. +
- - brin_summarize_new_values 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. brin_summarize_range does the same, except - it only summarizes the range that covers the given block number. - - - - gin_clean_pending_list 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 fastupdate option disabled, no cleanup happens and the - return value is 0, because the index doesn't have a pending list. - Please see and - for details of the pending list and fastupdate option. - - @@ -25265,7 +25621,7 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); 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 log_directory can be - accessed unless the user is granted the role + accessed, unless the user is a superuser or is granted the role pg_read_server_files. Use a relative path for files in the cluster directory, and a path matching the log_directory configuration setting for log files. @@ -25274,225 +25630,244 @@ postgres=# SELECT * FROM pg_walfile_name_offset(pg_stop_backup()); Note that granting users the EXECUTE privilege on pg_read_file(), 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 - pg_authid 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 pg_authid 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. + + + + Some of these functions take an optional missing_ok + parameter, which specifies the behavior when the file or directory does + not exist. If true, the function + returns NULL or an empty result set, as appropriate. + If false, an error is raised. The default + is false. Generic File Access Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_ls_dir(dirname text [, missing_ok boolean, include_dot_dirs boolean]) - - setof text - - List the contents of a directory. Restricted to superusers by default, but other users can be granted EXECUTE to run the function. - + + + pg_ls_dir + + pg_ls_dir ( dirname text , missing_ok boolean, include_dot_dirs boolean ) + setof text + + + Returns the names of all files (and directories and other special + files) in the specified + directory. The include_dot_dirs parameter + indicates whether . and .. are to be + included in the result set; the default is to exclude them. Including + them can be useful when missing_ok + is true, to distinguish an empty directory from a + non-existent directory. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_ls_logdir() - - setof record - - List the name, size, and last modification time of files in the log - directory. Access is granted to members of the pg_monitor - role and may be granted to other non-superuser roles. - + + + pg_ls_logdir + + pg_ls_logdir () + setof record + ( name text, + size bigint, + modification timestamp with time zone ) + + + 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. + + + This function is restricted to superusers and members of + the pg_monitor role by default, but other users can + be granted EXECUTE to run the function. + + - - pg_ls_waldir() - - setof record - - List the name, size, and last modification time of files in the WAL - directory. Access is granted to members of the pg_monitor - role and may be granted to other non-superuser roles. - + + + pg_ls_waldir + + pg_ls_waldir () + setof record + ( name text, + size bigint, + modification timestamp with time zone ) + + + 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. + + + This function is restricted to superusers and members of + the pg_monitor role by default, but other users can + be granted EXECUTE to run the function. + + - - pg_ls_archive_statusdir() - - setof record - - List the name, size, and last modification time of files in the WAL - archive status directory. Access is granted to members of the - pg_monitor role and may be granted to other - non-superuser roles. - + + + pg_ls_archive_statusdir + + pg_ls_archive_statusdir () + setof record + ( name text, + size bigint, + modification timestamp with time zone ) + + + Returns the name, size, and last modification time (mtime) of each + ordinary file in the server's WAL archive status directory + (pg_wal/archive_status). Filenames beginning + with a dot, directories, and other special files are excluded. + + + This function is restricted to superusers and members of + the pg_monitor role by default, but other users can + be granted EXECUTE to run the function. + + - - pg_ls_tmpdir(tablespace oid) - - setof record - - List the name, size, and last modification time of files in the - temporary directory for tablespace. If - tablespace is not provided, the - pg_default tablespace is used. Access is granted - to members of the pg_monitor role and may be - granted to other non-superuser roles. - + + + + pg_ls_tmpdir + + pg_ls_tmpdir ( tablespace oid ) + setof record + ( name text, + size bigint, + modification timestamp with time zone ) + + + Returns the name, size, and last modification time (mtime) of each + ordinary file in the temporary file directory for the + specified tablespace. + If tablespace is not provided, + the pg_default tablespace is examined. Filenames + beginning with a dot, directories, and other special files are + excluded. + + + This function is restricted to superusers and members of + the pg_monitor role by default, but other users can + be granted EXECUTE to run the function. + + - - pg_read_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ]) - - text - - Return the contents of a text file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function. - + + + pg_read_file + + pg_read_file ( filename text , offset bigint, length bigint , missing_ok boolean ) + text + + + Returns all or part of a text file, starting at the + given byte offset, returning at + most length bytes (less if the end of file is + reached first). If offset is negative, it is + relative to the end of the file. If offset + and length 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. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_read_binary_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ]) - - bytea - - Return the contents of a file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function. - + + + pg_read_binary_file + + pg_read_binary_file ( filename text , offset bigint, length bigint , missing_ok boolean ) + bytea + + + Returns all or part of a file. This function is identical to + pg_read_file except that it can read arbitrary + binary data, returning the result as bytea + not text; accordingly, no encoding checks are performed. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + + In combination with the convert_from function, + this function can be used to read a text file in a specified encoding + and convert to the database's encoding: + +SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); + + + - - pg_stat_file(filename text[, missing_ok boolean]) - - record - - Return information about a file. Restricted to superusers by default, but other users can be granted EXECUTE to run the function. - + + + pg_stat_file + + pg_stat_file ( filename text , missing_ok boolean ) + record + ( size bigint, + access timestamp with time zone, + modification timestamp with time zone, + change timestamp with time zone, + creation timestamp with time zone, + isdir boolean ) + + + 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. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. +
- - Some of these functions take an optional missing_ok parameter, - which specifies the behavior when the file or directory does not exist. - If true, the function returns NULL (except - pg_ls_dir, which returns an empty result set). If - false, an error is raised. The default is false. - - - - pg_ls_dir - - - pg_ls_dir returns the names of all files (and directories - and other special files) in the specified directory. The - include_dot_dirs indicates whether . and .. are - included in the result set. The default is to exclude them - (false), but including them can be useful when - missing_ok is true, to distinguish an - empty directory from an non-existent directory. - - - - pg_ls_logdir - - - pg_ls_logdir returns the name, size, and last modified time - (mtime) of each file in the log directory. By default, only superusers - and members of the pg_monitor role can use this function. - Access may be granted to others using GRANT. - Filenames beginning with a dot, directories, and other special files are not shown. - - - - pg_ls_waldir - - - pg_ls_waldir 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 pg_monitor role - can use this function. Access may be granted to others using - GRANT. - Filenames beginning with a dot, directories, and other special files are not shown. - - - - pg_ls_archive_statusdir - - - pg_ls_archive_statusdir returns the name, size, and - last modified time (mtime) of each file in the WAL archive status - directory pg_wal/archive_status. By default only - superusers and members of the pg_monitor role can - use this function. Access may be granted to others using - GRANT. - Filenames beginning with a dot, directories, and other special files are not shown. - - - - pg_ls_tmpdir - - - pg_ls_tmpdir returns the name, size, and last modified - time (mtime) of each file in the temporary file directory for the specified - tablespace. If tablespace is - not provided, the pg_default tablespace is used. By - default only superusers and members of the pg_monitor - role can use this function. Access may be granted to others using - GRANT. - Filenames beginning with a dot, directories, and other special files are not shown. - - - - pg_read_file - - - pg_read_file returns part of a text file, starting - at the given offset, returning at most length - bytes (less if the end of file is reached first). If offset - is negative, it is relative to the end of the file. - If offset and length 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. - - - - pg_read_binary_file - - - pg_read_binary_file is similar to - pg_read_file, except that the result is a bytea value; - accordingly, no encoding checks are performed. - In combination with the convert_from function, this function - can be used to read a file in a specified encoding: - -SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8'); - - - - - pg_stat_file - - - pg_stat_file 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 boolean - indicating if it is a directory. Typical usages include: - -SELECT * FROM pg_stat_file('filename'); -SELECT (pg_stat_file('filename')).modification; - - - @@ -25504,277 +25879,247 @@ SELECT (pg_stat_file('filename')).modification; see . + + 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 false 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. + + Advisory Lock Functions - + - Name Return Type Description + + + Function + + + Description + - - pg_advisory_lock(key bigint) - - void - Obtain exclusive session level advisory lock + + + pg_advisory_lock + + pg_advisory_lock ( key bigint ) + void + + + pg_advisory_lock ( key1 integer, key2 integer ) + void + + + Obtains an exclusive session-level advisory lock, waiting if necessary. + + - - pg_advisory_lock(key1 int, key2 int) - - void - Obtain exclusive session level advisory lock + + + pg_advisory_lock_shared + + pg_advisory_lock_shared ( key bigint ) + void + + + pg_advisory_lock_shared ( key1 integer, key2 integer ) + void + + + Obtains a shared session-level advisory lock, waiting if necessary. + + - - pg_advisory_lock_shared(key bigint) - - void - Obtain shared session level advisory lock + + + pg_advisory_unlock + + pg_advisory_unlock ( key bigint ) + boolean + + + pg_advisory_unlock ( key1 integer, key2 integer ) + boolean + + + Releases a previously-acquired exclusive session-level advisory lock. + Returns true if the lock is successfully released. + If the lock was not held, false is returned, and in + addition, an SQL warning will be reported by the server. + + - - pg_advisory_lock_shared(key1 int, key2 int) - - void - Obtain shared session level advisory lock + + + pg_advisory_unlock_all + + pg_advisory_unlock_all () + void + + + 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.) + + - - pg_advisory_unlock(key bigint) - - boolean - Release an exclusive session level advisory lock + + + pg_advisory_unlock_shared + + pg_advisory_unlock_shared ( key bigint ) + boolean + + + pg_advisory_unlock_shared ( key1 integer, key2 integer ) + boolean + + + Releases a previously-acquired shared session-level advisory lock. + Returns true if the lock is successfully released. + If the lock was not held, false is returned, and in + addition, an SQL warning will be reported by the server. + + - - pg_advisory_unlock(key1 int, key2 int) - - boolean - Release an exclusive session level advisory lock + + + pg_advisory_xact_lock + + pg_advisory_xact_lock ( key bigint ) + void + + + pg_advisory_xact_lock ( key1 integer, key2 integer ) + void + + + Obtains an exclusive transaction-level advisory lock, waiting if + necessary. + + - - pg_advisory_unlock_all() - - void - Release all session level advisory locks held by the current session + + + pg_advisory_xact_lock_shared + + pg_advisory_xact_lock_shared ( key bigint ) + void + + + pg_advisory_xact_lock_shared ( key1 integer, key2 integer ) + void + + + Obtains a shared transaction-level advisory lock, waiting if + necessary. + + - - pg_advisory_unlock_shared(key bigint) - - boolean - Release a shared session level advisory lock + + + pg_try_advisory_lock + + pg_try_advisory_lock ( key bigint ) + boolean + + + pg_try_advisory_lock ( key1 integer, key2 integer ) + boolean + + + Obtains an exclusive session-level advisory lock if available. + This will either obtain the lock immediately and + return true, or return false + without waiting if the lock cannot be acquired immediately. + + - - pg_advisory_unlock_shared(key1 int, key2 int) - - boolean - Release a shared session level advisory lock + + + pg_try_advisory_lock_shared + + pg_try_advisory_lock_shared ( key bigint ) + boolean + + + pg_try_advisory_lock_shared ( key1 integer, key2 integer ) + boolean + + + Obtains a shared session-level advisory lock if available. + This will either obtain the lock immediately and + return true, or return false + without waiting if the lock cannot be acquired immediately. + + - - pg_advisory_xact_lock(key bigint) - - void - Obtain exclusive transaction level advisory lock + + + pg_try_advisory_xact_lock + + pg_try_advisory_xact_lock ( key bigint ) + boolean + + + pg_try_advisory_xact_lock ( key1 integer, key2 integer ) + boolean + + + Obtains an exclusive transaction-level advisory lock if available. + This will either obtain the lock immediately and + return true, or return false + without waiting if the lock cannot be acquired immediately. + + - - pg_advisory_xact_lock(key1 int, key2 int) - - void - Obtain exclusive transaction level advisory lock - - - - pg_advisory_xact_lock_shared(key bigint) - - void - Obtain shared transaction level advisory lock - - - - pg_advisory_xact_lock_shared(key1 int, key2 int) - - void - Obtain shared transaction level advisory lock - - - - pg_try_advisory_lock(key bigint) - - boolean - Obtain exclusive session level advisory lock if available - - - - pg_try_advisory_lock(key1 int, key2 int) - - boolean - Obtain exclusive session level advisory lock if available - - - - pg_try_advisory_lock_shared(key bigint) - - boolean - Obtain shared session level advisory lock if available - - - - pg_try_advisory_lock_shared(key1 int, key2 int) - - boolean - Obtain shared session level advisory lock if available - - - - pg_try_advisory_xact_lock(key bigint) - - boolean - Obtain exclusive transaction level advisory lock if available - - - - pg_try_advisory_xact_lock(key1 int, key2 int) - - boolean - Obtain exclusive transaction level advisory lock if available - - - - pg_try_advisory_xact_lock_shared(key bigint) - - boolean - Obtain shared transaction level advisory lock if available - - - - pg_try_advisory_xact_lock_shared(key1 int, key2 int) - - boolean - Obtain shared transaction level advisory lock if available + + + pg_try_advisory_xact_lock_shared + + pg_try_advisory_xact_lock_shared ( key bigint ) + boolean + + + pg_try_advisory_xact_lock_shared ( key1 integer, key2 integer ) + boolean + + + Obtains a shared transaction-level advisory lock if available. + This will either obtain the lock immediately and + return true, or return false + without waiting if the lock cannot be acquired immediately. +
- - pg_advisory_lock - - - pg_advisory_lock 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. - - - - pg_advisory_lock_shared - - - pg_advisory_lock_shared works the same as - pg_advisory_lock, - except the lock can be shared with other sessions requesting shared locks. - Only would-be exclusive lockers are locked out. - - - - pg_try_advisory_lock - - - pg_try_advisory_lock is similar to - pg_advisory_lock, except the function will not wait for the - lock to become available. It will either obtain the lock immediately and - return true, or return false if the lock cannot be - acquired immediately. - - - - pg_try_advisory_lock_shared - - - pg_try_advisory_lock_shared works the same as - pg_try_advisory_lock, except it attempts to acquire - a shared rather than an exclusive lock. - - - - pg_advisory_unlock - - - pg_advisory_unlock will release a previously-acquired - exclusive session level advisory lock. It - returns true if the lock is successfully released. - If the lock was not held, it will return false, - and in addition, an SQL warning will be reported by the server. - - - - pg_advisory_unlock_shared - - - pg_advisory_unlock_shared works the same as - pg_advisory_unlock, - except it releases a shared session level advisory lock. - - - - pg_advisory_unlock_all - - - pg_advisory_unlock_all 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.) - - - - pg_advisory_xact_lock - - - pg_advisory_xact_lock works the same as - pg_advisory_lock, except the lock is automatically released - at the end of the current transaction and cannot be released explicitly. - - - - pg_advisory_xact_lock_shared - - - pg_advisory_xact_lock_shared works the same as - pg_advisory_lock_shared, except the lock is automatically released - at the end of the current transaction and cannot be released explicitly. - - - - pg_try_advisory_xact_lock - - - pg_try_advisory_xact_lock works the same as - pg_try_advisory_lock, except the lock, if acquired, - is automatically released at the end of the current transaction and - cannot be released explicitly. - - - - pg_try_advisory_xact_lock_shared - - - pg_try_advisory_xact_lock_shared works the same as - pg_try_advisory_lock_shared, except the lock, if acquired, - is automatically released at the end of the current transaction and - cannot be released explicitly. - - @@ -25935,6 +26280,10 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); pg_event_trigger_ddl_commands + +pg_event_trigger_ddl_commands () setof record + + pg_event_trigger_ddl_commands returns a list of DDL commands executed by each user action, @@ -26000,7 +26349,7 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); in_extension - bool + boolean True if the command is part of an extension script @@ -26026,12 +26375,15 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); pg_event_trigger_dropped_objects + +pg_event_trigger_dropped_objects () setof record + + pg_event_trigger_dropped_objects returns a list of all objects dropped by the command in whose sql_drop event it is called. - If called in any other context, - pg_event_trigger_dropped_objects raises an error. - pg_event_trigger_dropped_objects returns the following columns: + If called in any other context, an error is raised. + This function returns the following columns: @@ -26061,12 +26413,12 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); original - bool + boolean True if this was one of the root object(s) of the deletion normal - bool + boolean True if there was a normal dependency relationship in the dependency graph leading to this object @@ -26074,7 +26426,7 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); is_temporary - bool + boolean True if this was a temporary object @@ -26115,9 +26467,9 @@ FOR EACH ROW EXECUTE FUNCTION suppress_redundant_updates_trigger(); An array that, together with object_type and address_args, can be used by - the pg_get_object_address() function to + the pg_get_object_address 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. @@ -26171,40 +26523,52 @@ CREATE EVENT TRIGGER test_event_trigger_for_drops - Table Rewrite Information - + Table Rewrite Information Functions + - Name Return Type Description + + + Function + + + Description + + - - pg_event_trigger_table_rewrite_oid - pg_event_trigger_table_rewrite_oid() - - Oid - The OID of the table about to be rewritten. + + + pg_event_trigger_table_rewrite_oid + + pg_event_trigger_table_rewrite_oid () + oid + + + Returns the OID of the table about to be rewritten. + - - pg_event_trigger_table_rewrite_reason - pg_event_trigger_table_rewrite_reason() - - int - - The reason code(s) explaining the reason for rewriting. The exact + + + pg_event_trigger_table_rewrite_reason + + pg_event_trigger_table_rewrite_reason () + integer + + + Returns a code explaining the reason(s) for rewriting. The exact meaning of the codes is release dependent. - +
- The pg_event_trigger_table_rewrite_oid function can be used - in an event trigger like this: + These functions can be used in an event trigger like this: CREATE FUNCTION test_event_trigger_table_rewrite_oid() RETURNS event_trigger @@ -26242,14 +26606,17 @@ CREATE EVENT TRIGGER test_table_rewrite_oid Inspecting MCV Lists - pg_mcv_list_items - pg_mcv_list + pg_mcv_list_items + +pg_mcv_list_items ( pg_mcv_list ) setof record + + - pg_mcv_list_items returns a list of all items - stored in a multi-column MCV list, and returns the - following columns: + pg_mcv_list_items returns a set of records describing + all items stored in a multi-column MCV list. It + returns the following columns: @@ -26264,7 +26631,7 @@ CREATE EVENT TRIGGER test_table_rewrite_oid index - int + integer index of the item in the MCV list @@ -26300,8 +26667,9 @@ SELECT m.* FROM pg_statistic_ext join pg_statistic_ext_data on (oid = stxoid), pg_mcv_list_items(stxdmcv) m WHERE stxname = 'stts'; - Values of the pg_mcv_list can be obtained only from the - pg_statistic_ext_data.stxdmcv column. + Values of the pg_mcv_list type can be obtained only from the + pg_statistic_ext_data.stxdmcv + column.