1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>9.28. System Administration Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="functions-info.html" title="9.27. System Information Functions and Operators" /><link rel="next" href="functions-trigger.html" title="9.29. Trigger Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">9.28. System Administration Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="functions-info.html" title="9.27. System Information Functions and Operators">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><th width="60%" align="center">Chapter 9. Functions and Operators</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="functions-trigger.html" title="9.29. Trigger Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="FUNCTIONS-ADMIN"><div class="titlepage"><div><div><h2 class="title" style="clear: both">9.28. System Administration Functions <a href="#FUNCTIONS-ADMIN" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SET">9.28.1. Configuration Settings Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL">9.28.2. Server Signaling Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP">9.28.3. Backup Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL">9.28.4. Recovery Control Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION">9.28.5. Snapshot Synchronization Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-REPLICATION">9.28.6. Replication Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-DBOBJECT">9.28.7. Database Object Management Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-INDEX">9.28.8. Index Maintenance Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE">9.28.9. Generic File Access Functions</a></span></dt><dt><span class="sect2"><a href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS">9.28.10. Advisory Lock Functions</a></span></dt></dl></div><p>
3 The functions described in this section are used to control and
4 monitor a <span class="productname">PostgreSQL</span> installation.
5 </p><div class="sect2" id="FUNCTIONS-ADMIN-SET"><div class="titlepage"><div><div><h3 class="title">9.28.1. Configuration Settings Functions <a href="#FUNCTIONS-ADMIN-SET" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.34.3.2" class="indexterm"></a><a id="id-1.5.8.34.3.3" class="indexterm"></a><a id="id-1.5.8.34.3.4" class="indexterm"></a><p>
6 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET-TABLE" title="Table 9.95. Configuration Settings Functions">Table 9.95</a> shows the functions
7 available to query and alter run-time configuration parameters.
8 </p><div class="table" id="FUNCTIONS-ADMIN-SET-TABLE"><p class="title"><strong>Table 9.95. Configuration Settings Functions</strong></p><div class="table-contents"><table class="table" summary="Configuration Settings Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
16 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
17 <a id="id-1.5.8.34.3.6.2.2.1.1.1.1" class="indexterm"></a>
18 <code class="function">current_setting</code> ( <em class="parameter"><code>setting_name</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
19 → <code class="returnvalue">text</code>
22 Returns the current value of the
23 setting <em class="parameter"><code>setting_name</code></em>. If there is no such
24 setting, <code class="function">current_setting</code> throws an error
25 unless <em class="parameter"><code>missing_ok</code></em> is supplied and
26 is <code class="literal">true</code> (in which case NULL is returned).
27 This function corresponds to
28 the <acronym class="acronym">SQL</acronym> command <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a>.
31 <code class="literal">current_setting('datestyle')</code>
32 → <code class="returnvalue">ISO, MDY</code>
33 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
34 <a id="id-1.5.8.34.3.6.2.2.2.1.1.1" class="indexterm"></a>
35 <code class="function">set_config</code> (
36 <em class="parameter"><code>setting_name</code></em> <code class="type">text</code>,
37 <em class="parameter"><code>new_value</code></em> <code class="type">text</code>,
38 <em class="parameter"><code>is_local</code></em> <code class="type">boolean</code> )
39 → <code class="returnvalue">text</code>
42 Sets the parameter <em class="parameter"><code>setting_name</code></em>
43 to <em class="parameter"><code>new_value</code></em>, and returns that value.
44 If <em class="parameter"><code>is_local</code></em> is <code class="literal">true</code>, the new
45 value will only apply during the current transaction. If you want the
46 new value to apply for the rest of the current session,
47 use <code class="literal">false</code> instead. This function corresponds to
48 the SQL command <a class="xref" href="sql-set.html" title="SET"><span class="refentrytitle">SET</span></a>.
51 <code class="function">set_config</code> accepts the NULL value for
52 <em class="parameter"><code>new_value</code></em>, but as settings cannot be null, it
53 is interpreted as a request to reset the setting to its default value.
56 <code class="literal">set_config('log_statement_stats', 'off', false)</code>
57 → <code class="returnvalue">off</code>
58 </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-SIGNAL"><div class="titlepage"><div><div><h3 class="title">9.28.2. Server Signaling Functions <a href="#FUNCTIONS-ADMIN-SIGNAL" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.34.4.2" class="indexterm"></a><p>
59 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SIGNAL-TABLE" title="Table 9.96. Server Signaling Functions">Table 9.96</a> send control signals to
60 other server processes. Use of these functions is restricted to
61 superusers by default but access may be granted to others using
62 <code class="command">GRANT</code>, with noted exceptions.
64 Each of these functions returns <code class="literal">true</code> if
65 the signal was successfully sent and <code class="literal">false</code>
66 if sending the signal failed.
67 </p><div class="table" id="FUNCTIONS-ADMIN-SIGNAL-TABLE"><p class="title"><strong>Table 9.96. Server Signaling Functions</strong></p><div class="table-contents"><table class="table" summary="Server Signaling Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
72 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
73 <a id="id-1.5.8.34.4.5.2.2.1.1.1.1" class="indexterm"></a>
74 <code class="function">pg_cancel_backend</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code> )
75 → <code class="returnvalue">boolean</code>
78 Cancels the current query of the session whose backend process has the
79 specified process ID. This is also allowed if the
80 calling role is a member of the role whose backend is being canceled or
81 the calling role has privileges of <code class="literal">pg_signal_backend</code>,
82 however only superusers can cancel superuser backends.
83 As an exception, roles with privileges of
84 <code class="literal">pg_signal_autovacuum_worker</code> are permitted to
85 cancel autovacuum worker processes, which are otherwise considered
87 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
88 <a id="id-1.5.8.34.4.5.2.2.2.1.1.1" class="indexterm"></a>
89 <code class="function">pg_log_backend_memory_contexts</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code> )
90 → <code class="returnvalue">boolean</code>
93 Requests to log the memory contexts of the backend with the
94 specified process ID. This function can send the request to
95 backends and auxiliary processes except logger. These memory contexts
97 <code class="literal">LOG</code> message level. They will appear in
98 the server log based on the log configuration set
99 (see <a class="xref" href="runtime-config-logging.html" title="19.8. Error Reporting and Logging">Section 19.8</a> for more information),
100 but will not be sent to the client regardless of
101 <a class="xref" href="runtime-config-client.html#GUC-CLIENT-MIN-MESSAGES">client_min_messages</a>.
102 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
103 <a id="id-1.5.8.34.4.5.2.2.3.1.1.1" class="indexterm"></a>
104 <code class="function">pg_reload_conf</code> ()
105 → <code class="returnvalue">boolean</code>
108 Causes all processes of the <span class="productname">PostgreSQL</span>
109 server to reload their configuration files. (This is initiated by
110 sending a <span class="systemitem">SIGHUP</span> signal to the postmaster
111 process, which in turn sends <span class="systemitem">SIGHUP</span> to each
112 of its children.) You can use the
113 <a class="link" href="view-pg-file-settings.html" title="53.8. pg_file_settings"><code class="structname">pg_file_settings</code></a>,
114 <a class="link" href="view-pg-hba-file-rules.html" title="53.10. pg_hba_file_rules"><code class="structname">pg_hba_file_rules</code></a> and
115 <a class="link" href="view-pg-ident-file-mappings.html" title="53.11. pg_ident_file_mappings"><code class="structname">pg_ident_file_mappings</code></a> views
116 to check the configuration files for possible errors, before reloading.
117 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
118 <a id="id-1.5.8.34.4.5.2.2.4.1.1.1" class="indexterm"></a>
119 <code class="function">pg_rotate_logfile</code> ()
120 → <code class="returnvalue">boolean</code>
123 Signals the log-file manager to switch to a new output file
124 immediately. This works only when the built-in log collector is
125 running, since otherwise there is no log-file manager subprocess.
126 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
127 <a id="id-1.5.8.34.4.5.2.2.5.1.1.1" class="indexterm"></a>
128 <code class="function">pg_terminate_backend</code> ( <em class="parameter"><code>pid</code></em> <code class="type">integer</code>, <em class="parameter"><code>timeout</code></em> <code class="type">bigint</code> <code class="literal">DEFAULT</code> <code class="literal">0</code> )
129 → <code class="returnvalue">boolean</code>
132 Terminates the session whose backend process has the
133 specified process ID. This is also allowed if the calling role
134 is a member of the role whose backend is being terminated or the
135 calling role has privileges of <code class="literal">pg_signal_backend</code>,
136 however only superusers can terminate superuser backends.
137 As an exception, roles with privileges of
138 <code class="literal">pg_signal_autovacuum_worker</code> are permitted to
139 terminate autovacuum worker processes, which are otherwise considered
143 If <em class="parameter"><code>timeout</code></em> is not specified or zero, this
144 function returns <code class="literal">true</code> whether the process actually
145 terminates or not, indicating only that the sending of the signal was
146 successful. If the <em class="parameter"><code>timeout</code></em> is specified (in
147 milliseconds) and greater than zero, the function waits until the
148 process is actually terminated or until the given time has passed. If
149 the process is terminated, the function
150 returns <code class="literal">true</code>. On timeout, a warning is emitted and
151 <code class="literal">false</code> is returned.
152 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
153 <code class="function">pg_cancel_backend</code> and <code class="function">pg_terminate_backend</code>
154 send signals (<span class="systemitem">SIGINT</span> or <span class="systemitem">SIGTERM</span>
155 respectively) to backend processes identified by process ID.
156 The process ID of an active backend can be found from
157 the <code class="structfield">pid</code> column of the
158 <code class="structname">pg_stat_activity</code> view, or by listing the
159 <code class="command">postgres</code> processes on the server (using
160 <span class="application">ps</span> on Unix or the <span class="application">Task
161 Manager</span> on <span class="productname">Windows</span>).
162 The role of an active backend can be found from the
163 <code class="structfield">usename</code> column of the
164 <code class="structname">pg_stat_activity</code> view.
166 <code class="function">pg_log_backend_memory_contexts</code> can be used
167 to log the memory contexts of a backend process. For example:
168 </p><pre class="programlisting">
169 postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid());
170 pg_log_backend_memory_contexts
171 --------------------------------
175 One message for each memory context will be logged. For example:
176 </p><pre class="screen">
177 LOG: logging memory contexts of PID 10377
178 STATEMENT: SELECT pg_log_backend_memory_contexts(pg_backend_pid());
179 LOG: level: 1; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used
180 LOG: level: 2; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used
181 LOG: level: 2; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used
182 LOG: level: 2; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used
183 LOG: level: 2; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used
184 LOG: level: 2; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used
185 LOG: level: 2; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used
186 LOG: level: 2; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used
188 LOG: level: 2; ErrorContext: 8192 total in 1 blocks; 7928 free (3 chunks); 264 used
189 LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 used
191 If there are more than 100 child contexts under the same parent, the first
192 100 child contexts are logged, along with a summary of the remaining contexts.
193 Note that frequent calls to this function could incur significant overhead,
194 because it may generate a large number of log messages.
195 </p></div><div class="sect2" id="FUNCTIONS-ADMIN-BACKUP"><div class="titlepage"><div><div><h3 class="title">9.28.3. Backup Control Functions <a href="#FUNCTIONS-ADMIN-BACKUP" class="id_link">#</a></h3></div></div></div><a id="id-1.5.8.34.5.2" class="indexterm"></a><p>
196 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.97. Backup Control Functions">Table 9.97</a> assist in making on-line backups.
197 These functions cannot be executed during recovery (except
198 <code class="function">pg_backup_start</code>,
199 <code class="function">pg_backup_stop</code>,
200 and <code class="function">pg_wal_lsn_diff</code>).
202 For details about proper usage of these functions, see
203 <a class="xref" href="continuous-archiving.html" title="25.3. Continuous Archiving and Point-in-Time Recovery (PITR)">Section 25.3</a>.
204 </p><div class="table" id="FUNCTIONS-ADMIN-BACKUP-TABLE"><p class="title"><strong>Table 9.97. Backup Control Functions</strong></p><div class="table-contents"><table class="table" summary="Backup Control Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
209 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
210 <a id="id-1.5.8.34.5.5.2.2.1.1.1.1" class="indexterm"></a>
211 <code class="function">pg_create_restore_point</code> ( <em class="parameter"><code>name</code></em> <code class="type">text</code> )
212 → <code class="returnvalue">pg_lsn</code>
215 Creates a named marker record in the write-ahead log that can later be
216 used as a recovery target, and returns the corresponding write-ahead
217 log location. The given name can then be used with
218 <a class="xref" href="runtime-config-wal.html#GUC-RECOVERY-TARGET-NAME">recovery_target_name</a> to specify the point up to
219 which recovery will proceed. Avoid creating multiple restore points
220 with the same name, since recovery will stop at the first one whose
221 name matches the recovery target.
224 This function is restricted to superusers by default, but other users
225 can be granted EXECUTE to run the function.
226 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
227 <a id="id-1.5.8.34.5.5.2.2.2.1.1.1" class="indexterm"></a>
228 <code class="function">pg_current_wal_flush_lsn</code> ()
229 → <code class="returnvalue">pg_lsn</code>
232 Returns the current write-ahead log flush location (see notes below).
233 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
234 <a id="id-1.5.8.34.5.5.2.2.3.1.1.1" class="indexterm"></a>
235 <code class="function">pg_current_wal_insert_lsn</code> ()
236 → <code class="returnvalue">pg_lsn</code>
239 Returns the current write-ahead log insert location (see notes below).
240 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
241 <a id="id-1.5.8.34.5.5.2.2.4.1.1.1" class="indexterm"></a>
242 <code class="function">pg_current_wal_lsn</code> ()
243 → <code class="returnvalue">pg_lsn</code>
246 Returns the current write-ahead log write location (see notes below).
247 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
248 <a id="id-1.5.8.34.5.5.2.2.5.1.1.1" class="indexterm"></a>
249 <code class="function">pg_backup_start</code> (
250 <em class="parameter"><code>label</code></em> <code class="type">text</code>
251 [<span class="optional">, <em class="parameter"><code>fast</code></em> <code class="type">boolean</code>
253 → <code class="returnvalue">pg_lsn</code>
256 Prepares the server to begin an on-line backup. The only required
257 parameter is an arbitrary user-defined label for the backup.
258 (Typically this would be the name under which the backup dump file
260 If the optional second parameter is given as <code class="literal">true</code>,
261 it specifies executing <code class="function">pg_backup_start</code> as quickly
262 as possible. This forces an immediate checkpoint which will cause a
263 spike in I/O operations, slowing any concurrently executing queries.
266 This function is restricted to superusers by default, but other users
267 can be granted EXECUTE to run the function.
268 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
269 <a id="id-1.5.8.34.5.5.2.2.6.1.1.1" class="indexterm"></a>
270 <code class="function">pg_backup_stop</code> (
271 [<span class="optional"><em class="parameter"><code>wait_for_archive</code></em> <code class="type">boolean</code>
273 → <code class="returnvalue">record</code>
274 ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
275 <em class="parameter"><code>labelfile</code></em> <code class="type">text</code>,
276 <em class="parameter"><code>spcmapfile</code></em> <code class="type">text</code> )
279 Finishes performing an on-line backup. The desired contents of the
280 backup label file and the tablespace map file are returned as part of
281 the result of the function and must be written to files in the
282 backup area. These files must not be written to the live data directory
283 (doing so will cause PostgreSQL to fail to restart in the event of a
287 There is an optional parameter of type <code class="type">boolean</code>.
288 If false, the function will return immediately after the backup is
289 completed, without waiting for WAL to be archived. This behavior is
290 only useful with backup software that independently monitors WAL
291 archiving. Otherwise, WAL required to make the backup consistent might
292 be missing and make the backup useless. By default or when this
293 parameter is true, <code class="function">pg_backup_stop</code> will wait for
294 WAL to be archived when archiving is enabled. (On a standby, this
295 means that it will wait only when <code class="varname">archive_mode</code> =
296 <code class="literal">always</code>. If write activity on the primary is low,
297 it may be useful to run <code class="function">pg_switch_wal</code> on the
298 primary in order to trigger an immediate segment switch.)
301 When executed on a primary, this function also creates a backup
302 history file in the write-ahead log archive area. The history file
303 includes the label given to <code class="function">pg_backup_start</code>, the
304 starting and ending write-ahead log locations for the backup, and the
305 starting and ending times of the backup. After recording the ending
306 location, the current write-ahead log insertion point is automatically
307 advanced to the next write-ahead log file, so that the ending
308 write-ahead log file can be archived immediately to complete the
312 The result of the function is a single record.
313 The <em class="parameter"><code>lsn</code></em> column holds the backup's ending
314 write-ahead log location (which again can be ignored). The second
315 column returns the contents of the backup label file, and the third
316 column returns the contents of the tablespace map file. These must be
317 stored as part of the backup and are required as part of the restore
321 This function is restricted to superusers by default, but other users
322 can be granted EXECUTE to run the function.
323 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
324 <a id="id-1.5.8.34.5.5.2.2.7.1.1.1" class="indexterm"></a>
325 <code class="function">pg_switch_wal</code> ()
326 → <code class="returnvalue">pg_lsn</code>
329 Forces the server to switch to a new write-ahead log file, which
330 allows the current file to be archived (assuming you are using
331 continuous archiving). The result is the ending write-ahead log
332 location plus 1 within the just-completed write-ahead log file. If
333 there has been no write-ahead log activity since the last write-ahead
334 log switch, <code class="function">pg_switch_wal</code> does nothing and
335 returns the start location of the write-ahead log file currently in
339 This function is restricted to superusers by default, but other users
340 can be granted EXECUTE to run the function.
341 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
342 <a id="id-1.5.8.34.5.5.2.2.8.1.1.1" class="indexterm"></a>
343 <code class="function">pg_walfile_name</code> ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
344 → <code class="returnvalue">text</code>
347 Converts a write-ahead log location to the name of the WAL file
348 holding that location.
349 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
350 <a id="id-1.5.8.34.5.5.2.2.9.1.1.1" class="indexterm"></a>
351 <code class="function">pg_walfile_name_offset</code> ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
352 → <code class="returnvalue">record</code>
353 ( <em class="parameter"><code>file_name</code></em> <code class="type">text</code>,
354 <em class="parameter"><code>file_offset</code></em> <code class="type">integer</code> )
357 Converts a write-ahead log location to a WAL file name and byte offset
359 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
360 <a id="id-1.5.8.34.5.5.2.2.10.1.1.1" class="indexterm"></a>
361 <code class="function">pg_split_walfile_name</code> ( <em class="parameter"><code>file_name</code></em> <code class="type">text</code> )
362 → <code class="returnvalue">record</code>
363 ( <em class="parameter"><code>segment_number</code></em> <code class="type">numeric</code>,
364 <em class="parameter"><code>timeline_id</code></em> <code class="type">bigint</code> )
367 Extracts the sequence number and timeline ID from a WAL file
369 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
370 <a id="id-1.5.8.34.5.5.2.2.11.1.1.1" class="indexterm"></a>
371 <code class="function">pg_wal_lsn_diff</code> ( <em class="parameter"><code>lsn1</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>lsn2</code></em> <code class="type">pg_lsn</code> )
372 → <code class="returnvalue">numeric</code>
375 Calculates the difference in bytes (<em class="parameter"><code>lsn1</code></em> - <em class="parameter"><code>lsn2</code></em>) between two write-ahead log
376 locations. This can be used
377 with <code class="structname">pg_stat_replication</code> or some of the
378 functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP-TABLE" title="Table 9.97. Backup Control Functions">Table 9.97</a> to
379 get the replication lag.
380 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
381 <code class="function">pg_current_wal_lsn</code> displays the current write-ahead
382 log write location in the same format used by the above functions.
383 Similarly, <code class="function">pg_current_wal_insert_lsn</code> displays the
384 current write-ahead log insertion location
385 and <code class="function">pg_current_wal_flush_lsn</code> displays the current
386 write-ahead log flush location. The insertion location is
387 the <span class="quote">“<span class="quote">logical</span>”</span> end of the write-ahead log at any instant,
388 while the write location is the end of what has actually been written out
389 from the server's internal buffers, and the flush location is the last
390 location known to be written to durable storage. The write location is the
391 end of what can be examined from outside the server, and is usually what
392 you want if you are interested in archiving partially-complete write-ahead
393 log files. The insertion and flush locations are made available primarily
394 for server debugging purposes. These are all read-only operations and do
395 not require superuser permissions.
397 You can use <code class="function">pg_walfile_name_offset</code> to extract the
398 corresponding write-ahead log file name and byte offset from
399 a <code class="type">pg_lsn</code> value. For example:
400 </p><pre class="programlisting">
401 postgres=# SELECT * FROM pg_walfile_name_offset((pg_backup_stop()).lsn);
402 file_name | file_offset
403 --------------------------+-------------
404 00000001000000000000000D | 4039624
407 Similarly, <code class="function">pg_walfile_name</code> extracts just the write-ahead log file name.
409 <code class="function">pg_split_walfile_name</code> is useful to compute a
410 <acronym class="acronym">LSN</acronym> from a file offset and WAL file name, for example:
411 </p><pre class="programlisting">
412 postgres=# \set file_name '000000010000000100C000AB'
413 postgres=# \set offset 256
414 postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset AS lsn
415 FROM pg_split_walfile_name(:'file_name') pd,
416 pg_show_all_settings() ps
417 WHERE ps.name = 'wal_segment_size';
423 </p></div><div class="sect2" id="FUNCTIONS-RECOVERY-CONTROL"><div class="titlepage"><div><div><h3 class="title">9.28.4. Recovery Control Functions <a href="#FUNCTIONS-RECOVERY-CONTROL" class="id_link">#</a></h3></div></div></div><p>
424 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-INFO-TABLE" title="Table 9.98. Recovery Information Functions">Table 9.98</a> provide information
425 about the current status of a standby server.
426 These functions may be executed both during recovery and in normal running.
427 </p><div class="table" id="FUNCTIONS-RECOVERY-INFO-TABLE"><p class="title"><strong>Table 9.98. Recovery Information Functions</strong></p><div class="table-contents"><table class="table" summary="Recovery Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
432 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
433 <a id="id-1.5.8.34.6.3.2.2.1.1.1.1" class="indexterm"></a>
434 <code class="function">pg_is_in_recovery</code> ()
435 → <code class="returnvalue">boolean</code>
438 Returns true if recovery is still in progress.
439 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
440 <a id="id-1.5.8.34.6.3.2.2.2.1.1.1" class="indexterm"></a>
441 <code class="function">pg_last_wal_receive_lsn</code> ()
442 → <code class="returnvalue">pg_lsn</code>
445 Returns the last write-ahead log location that has been received and
446 synced to disk by streaming replication. While streaming replication
447 is in progress this will increase monotonically. If recovery has
448 completed then this will remain static at the location of the last WAL
449 record received and synced to disk during recovery. If streaming
450 replication is disabled, or if it has not yet started, the function
451 returns <code class="literal">NULL</code>.
452 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
453 <a id="id-1.5.8.34.6.3.2.2.3.1.1.1" class="indexterm"></a>
454 <code class="function">pg_last_wal_replay_lsn</code> ()
455 → <code class="returnvalue">pg_lsn</code>
458 Returns the last write-ahead log location that has been replayed
459 during recovery. If recovery is still in progress this will increase
460 monotonically. If recovery has completed then this will remain
461 static at the location of the last WAL record applied during recovery.
462 When the server has been started normally without recovery, the
463 function returns <code class="literal">NULL</code>.
464 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
465 <a id="id-1.5.8.34.6.3.2.2.4.1.1.1" class="indexterm"></a>
466 <code class="function">pg_last_xact_replay_timestamp</code> ()
467 → <code class="returnvalue">timestamp with time zone</code>
470 Returns the time stamp of the last transaction replayed during
471 recovery. This is the time at which the commit or abort WAL record
472 for that transaction was generated on the primary. If no transactions
473 have been replayed during recovery, the function
474 returns <code class="literal">NULL</code>. Otherwise, if recovery is still in
475 progress this will increase monotonically. If recovery has completed
476 then this will remain static at the time of the last transaction
477 applied during recovery. When the server has been started normally
478 without recovery, the function returns <code class="literal">NULL</code>.
479 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
480 <a id="id-1.5.8.34.6.3.2.2.5.1.1.1" class="indexterm"></a>
481 <code class="function">pg_get_wal_resource_managers</code> ()
482 → <code class="returnvalue">setof record</code>
483 ( <em class="parameter"><code>rm_id</code></em> <code class="type">integer</code>,
484 <em class="parameter"><code>rm_name</code></em> <code class="type">text</code>,
485 <em class="parameter"><code>rm_builtin</code></em> <code class="type">boolean</code> )
488 Returns the currently-loaded WAL resource managers in the system. The
489 column <em class="parameter"><code>rm_builtin</code></em> indicates whether it's a
490 built-in resource manager, or a custom resource manager loaded by an
492 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
493 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL-TABLE" title="Table 9.99. Recovery Control Functions">Table 9.99</a> control the progress of recovery.
494 These functions may be executed only during recovery.
495 </p><div class="table" id="FUNCTIONS-RECOVERY-CONTROL-TABLE"><p class="title"><strong>Table 9.99. Recovery Control Functions</strong></p><div class="table-contents"><table class="table" summary="Recovery Control Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
500 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
501 <a id="id-1.5.8.34.6.5.2.2.1.1.1.1" class="indexterm"></a>
502 <code class="function">pg_is_wal_replay_paused</code> ()
503 → <code class="returnvalue">boolean</code>
506 Returns true if recovery pause is requested.
507 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
508 <a id="id-1.5.8.34.6.5.2.2.2.1.1.1" class="indexterm"></a>
509 <code class="function">pg_get_wal_replay_pause_state</code> ()
510 → <code class="returnvalue">text</code>
513 Returns recovery pause state. The return values are <code class="literal">
514 not paused</code> if pause is not requested, <code class="literal">
515 pause requested</code> if pause is requested but recovery is
516 not yet paused, and <code class="literal">paused</code> if the recovery is
518 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
519 <a id="id-1.5.8.34.6.5.2.2.3.1.1.1" class="indexterm"></a>
520 <code class="function">pg_promote</code> ( <em class="parameter"><code>wait</code></em> <code class="type">boolean</code> <code class="literal">DEFAULT</code> <code class="literal">true</code>, <em class="parameter"><code>wait_seconds</code></em> <code class="type">integer</code> <code class="literal">DEFAULT</code> <code class="literal">60</code> )
521 → <code class="returnvalue">boolean</code>
524 Promotes a standby server to primary status.
525 With <em class="parameter"><code>wait</code></em> set to <code class="literal">true</code> (the
526 default), the function waits until promotion is completed
527 or <em class="parameter"><code>wait_seconds</code></em> seconds have passed, and
528 returns <code class="literal">true</code> if promotion is successful
529 and <code class="literal">false</code> otherwise.
530 If <em class="parameter"><code>wait</code></em> is set to <code class="literal">false</code>, the
531 function returns <code class="literal">true</code> immediately after sending a
532 <code class="literal">SIGUSR1</code> signal to the postmaster to trigger
536 This function is restricted to superusers by default, but other users
537 can be granted EXECUTE to run the function.
538 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
539 <a id="id-1.5.8.34.6.5.2.2.4.1.1.1" class="indexterm"></a>
540 <code class="function">pg_wal_replay_pause</code> ()
541 → <code class="returnvalue">void</code>
544 Request to pause recovery. A request doesn't mean that recovery stops
545 right away. If you want a guarantee that recovery is actually paused,
546 you need to check for the recovery pause state returned by
547 <code class="function">pg_get_wal_replay_pause_state()</code>. Note that
548 <code class="function">pg_is_wal_replay_paused()</code> returns whether a request
549 is made. While recovery is paused, no further database changes are applied.
550 If hot standby is active, all new queries will see the same consistent
551 snapshot of the database, and no further query conflicts will be generated
552 until recovery is resumed.
555 This function is restricted to superusers by default, but other users
556 can be granted EXECUTE to run the function.
557 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
558 <a id="id-1.5.8.34.6.5.2.2.5.1.1.1" class="indexterm"></a>
559 <code class="function">pg_wal_replay_resume</code> ()
560 → <code class="returnvalue">void</code>
563 Restarts recovery if it was paused.
566 This function is restricted to superusers by default, but other users
567 can be granted EXECUTE to run the function.
568 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
569 <code class="function">pg_wal_replay_pause</code> and
570 <code class="function">pg_wal_replay_resume</code> cannot be executed while
571 a promotion is ongoing. If a promotion is triggered while recovery
572 is paused, the paused state ends and promotion continues.
574 If streaming replication is disabled, the paused state may continue
575 indefinitely without a problem. If streaming replication is in
576 progress then WAL records will continue to be received, which will
577 eventually fill available disk space, depending upon the duration of
578 the pause, the rate of WAL generation and available disk space.
579 </p></div><div class="sect2" id="FUNCTIONS-SNAPSHOT-SYNCHRONIZATION"><div class="titlepage"><div><div><h3 class="title">9.28.5. Snapshot Synchronization Functions <a href="#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" class="id_link">#</a></h3></div></div></div><p>
580 <span class="productname">PostgreSQL</span> allows database sessions to synchronize their
581 snapshots. A <em class="firstterm">snapshot</em> determines which data is visible to the
582 transaction that is using the snapshot. Synchronized snapshots are
583 necessary when two or more sessions need to see identical content in the
584 database. If two sessions just start their transactions independently,
585 there is always a possibility that some third transaction commits
586 between the executions of the two <code class="command">START TRANSACTION</code> commands,
587 so that one session sees the effects of that transaction and the other
590 To solve this problem, <span class="productname">PostgreSQL</span> allows a transaction to
591 <em class="firstterm">export</em> the snapshot it is using. As long as the exporting
592 transaction remains open, other transactions can <em class="firstterm">import</em> its
593 snapshot, and thereby be guaranteed that they see exactly the same view
594 of the database that the first transaction sees. But note that any
595 database changes made by any one of these transactions remain invisible
596 to the other transactions, as is usual for changes made by uncommitted
597 transactions. So the transactions are synchronized with respect to
598 pre-existing data, but act normally for changes they make themselves.
600 Snapshots are exported with the <code class="function">pg_export_snapshot</code> function,
601 shown in <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE" title="Table 9.100. Snapshot Synchronization Functions">Table 9.100</a>, and
602 imported with the <a class="xref" href="sql-set-transaction.html" title="SET TRANSACTION"><span class="refentrytitle">SET TRANSACTION</span></a> command.
603 </p><div class="table" id="FUNCTIONS-SNAPSHOT-SYNCHRONIZATION-TABLE"><p class="title"><strong>Table 9.100. Snapshot Synchronization Functions</strong></p><div class="table-contents"><table class="table" summary="Snapshot Synchronization Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
608 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
609 <a id="id-1.5.8.34.7.5.2.2.1.1.1.1" class="indexterm"></a>
610 <code class="function">pg_export_snapshot</code> ()
611 → <code class="returnvalue">text</code>
614 Saves the transaction's current snapshot and returns
615 a <code class="type">text</code> string identifying the snapshot. This string must
616 be passed (outside the database) to clients that want to import the
617 snapshot. The snapshot is available for import only until the end of
618 the transaction that exported it.
621 A transaction can export more than one snapshot, if needed. Note that
622 doing so is only useful in <code class="literal">READ COMMITTED</code>
623 transactions, since in <code class="literal">REPEATABLE READ</code> and higher
624 isolation levels, transactions use the same snapshot throughout their
625 lifetime. Once a transaction has exported any snapshots, it cannot be
626 prepared with <a class="xref" href="sql-prepare-transaction.html" title="PREPARE TRANSACTION"><span class="refentrytitle">PREPARE TRANSACTION</span></a>.
627 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
628 <a id="id-1.5.8.34.7.5.2.2.2.1.1.1" class="indexterm"></a>
629 <code class="function">pg_log_standby_snapshot</code> ()
630 → <code class="returnvalue">pg_lsn</code>
633 Take a snapshot of running transactions and write it to WAL, without
634 having to wait for bgwriter or checkpointer to log one. This is useful
635 for logical decoding on standby, as logical slot creation has to wait
636 until such a record is replayed on the standby.
637 </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-REPLICATION"><div class="titlepage"><div><div><h3 class="title">9.28.6. Replication Management Functions <a href="#FUNCTIONS-REPLICATION" class="id_link">#</a></h3></div></div></div><p>
639 in <a class="xref" href="functions-admin.html#FUNCTIONS-REPLICATION-TABLE" title="Table 9.101. Replication Management Functions">Table 9.101</a> are for
640 controlling and interacting with replication features.
641 See <a class="xref" href="warm-standby.html#STREAMING-REPLICATION" title="26.2.5. Streaming Replication">Section 26.2.5</a>,
642 <a class="xref" href="warm-standby.html#STREAMING-REPLICATION-SLOTS" title="26.2.6. Replication Slots">Section 26.2.6</a>, and
643 <a class="xref" href="replication-origins.html" title="Chapter 48. Replication Progress Tracking">Chapter 48</a>
644 for information about the underlying features.
645 Use of functions for replication origin is only allowed to the
646 superuser by default, but may be allowed to other users by using the
647 <code class="literal">GRANT</code> command.
648 Use of functions for replication slots is restricted to superusers
649 and users having <code class="literal">REPLICATION</code> privilege.
651 Many of these functions have equivalent commands in the replication
652 protocol; see <a class="xref" href="protocol-replication.html" title="54.4. Streaming Replication Protocol">Section 54.4</a>.
654 The functions described in
655 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-BACKUP" title="9.28.3. Backup Control Functions">Section 9.28.3</a>,
656 <a class="xref" href="functions-admin.html#FUNCTIONS-RECOVERY-CONTROL" title="9.28.4. Recovery Control Functions">Section 9.28.4</a>, and
657 <a class="xref" href="functions-admin.html#FUNCTIONS-SNAPSHOT-SYNCHRONIZATION" title="9.28.5. Snapshot Synchronization Functions">Section 9.28.5</a>
658 are also relevant for replication.
659 </p><div class="table" id="FUNCTIONS-REPLICATION-TABLE"><p class="title"><strong>Table 9.101. Replication Management Functions</strong></p><div class="table-contents"><table class="table" summary="Replication Management Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
664 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
665 <a id="id-1.5.8.34.8.5.2.2.1.1.1.1" class="indexterm"></a>
666 <code class="function">pg_create_physical_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>immediately_reserve</code></em> <code class="type">boolean</code>, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> </span>] )
667 → <code class="returnvalue">record</code>
668 ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
669 <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
672 Creates a new physical replication slot named
673 <em class="parameter"><code>slot_name</code></em>. The optional second parameter,
674 when <code class="literal">true</code>, specifies that the <acronym class="acronym">LSN</acronym> for this
675 replication slot be reserved immediately; otherwise
676 the <acronym class="acronym">LSN</acronym> is reserved on first connection from a streaming
677 replication client. Streaming changes from a physical slot is only
678 possible with the streaming-replication protocol —
679 see <a class="xref" href="protocol-replication.html" title="54.4. Streaming Replication Protocol">Section 54.4</a>. The optional third
680 parameter, <em class="parameter"><code>temporary</code></em>, when set to true, specifies that
681 the slot should not be permanently stored to disk and is only meant
682 for use by the current session. Temporary slots are also
683 released upon any error. This function corresponds
684 to the replication protocol command <code class="literal">CREATE_REPLICATION_SLOT
686 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
687 <a id="id-1.5.8.34.8.5.2.2.2.1.1.1" class="indexterm"></a>
688 <code class="function">pg_drop_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code> )
689 → <code class="returnvalue">void</code>
692 Drops the physical or logical replication slot
693 named <em class="parameter"><code>slot_name</code></em>. Same as replication protocol
694 command <code class="literal">DROP_REPLICATION_SLOT</code>.
695 </p></td></tr><tr><td id="PG-CREATE-LOGICAL-REPLICATION-SLOT" class="func_table_entry"><p class="func_signature">
696 <a id="id-1.5.8.34.8.5.2.2.3.1.1.1" class="indexterm"></a>
697 <code class="function">pg_create_logical_replication_slot</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>plugin</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code>, <em class="parameter"><code>twophase</code></em> <code class="type">boolean</code>, <em class="parameter"><code>failover</code></em> <code class="type">boolean</code> </span>] )
698 → <code class="returnvalue">record</code>
699 ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
700 <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
703 Creates a new logical (decoding) replication slot named
704 <em class="parameter"><code>slot_name</code></em> using the output plugin
705 <em class="parameter"><code>plugin</code></em>. The optional third
706 parameter, <em class="parameter"><code>temporary</code></em>, when set to true, specifies that
707 the slot should not be permanently stored to disk and is only meant
708 for use by the current session. Temporary slots are also
709 released upon any error. The optional fourth parameter,
710 <em class="parameter"><code>twophase</code></em>, when set to true, specifies
711 that the decoding of prepared transactions is enabled for this
712 slot. The optional fifth parameter,
713 <em class="parameter"><code>failover</code></em>, when set to true,
714 specifies that this slot is enabled to be synced to the
715 standbys so that logical replication can be resumed after
716 failover. A call to this function has the same effect as
717 the replication protocol command
718 <code class="literal">CREATE_REPLICATION_SLOT ... LOGICAL</code>.
719 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
720 <a id="id-1.5.8.34.8.5.2.2.4.1.1.1" class="indexterm"></a>
721 <code class="function">pg_copy_physical_replication_slot</code> ( <em class="parameter"><code>src_slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>dst_slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> </span>] )
722 → <code class="returnvalue">record</code>
723 ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
724 <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
727 Copies an existing physical replication slot named <em class="parameter"><code>src_slot_name</code></em>
728 to a physical replication slot named <em class="parameter"><code>dst_slot_name</code></em>.
729 The copied physical slot starts to reserve WAL from the same <acronym class="acronym">LSN</acronym> as the
731 <em class="parameter"><code>temporary</code></em> is optional. If <em class="parameter"><code>temporary</code></em>
732 is omitted, the same value as the source slot is used. Copy of an
733 invalidated slot is not allowed.
734 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
735 <a id="id-1.5.8.34.8.5.2.2.5.1.1.1" class="indexterm"></a>
736 <code class="function">pg_copy_logical_replication_slot</code> ( <em class="parameter"><code>src_slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>dst_slot_name</code></em> <code class="type">name</code> [<span class="optional">, <em class="parameter"><code>temporary</code></em> <code class="type">boolean</code> [<span class="optional">, <em class="parameter"><code>plugin</code></em> <code class="type">name</code> </span>]</span>] )
737 → <code class="returnvalue">record</code>
738 ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
739 <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
742 Copies an existing logical replication slot
743 named <em class="parameter"><code>src_slot_name</code></em> to a logical replication
744 slot named <em class="parameter"><code>dst_slot_name</code></em>, optionally changing
745 the output plugin and persistence. The copied logical slot starts
746 from the same <acronym class="acronym">LSN</acronym> as the source logical slot. Both
747 <em class="parameter"><code>temporary</code></em> and <em class="parameter"><code>plugin</code></em> are
748 optional; if they are omitted, the values of the source slot are used.
749 The <code class="literal">failover</code> option of the source logical slot
750 is not copied and is set to <code class="literal">false</code> by default. This
751 is to avoid the risk of being unable to continue logical replication
752 after failover to standby where the slot is being synchronized. Copy of
753 an invalidated slot is not allowed.
754 </p></td></tr><tr><td id="PG-LOGICAL-SLOT-GET-CHANGES" class="func_table_entry"><p class="func_signature">
755 <a id="id-1.5.8.34.8.5.2.2.6.1.1.1" class="indexterm"></a>
756 <code class="function">pg_logical_slot_get_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
757 → <code class="returnvalue">setof record</code>
758 ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
759 <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
760 <em class="parameter"><code>data</code></em> <code class="type">text</code> )
763 Returns changes in the slot <em class="parameter"><code>slot_name</code></em>, starting
764 from the point from which changes have been consumed last. If
765 <em class="parameter"><code>upto_lsn</code></em>
766 and <em class="parameter"><code>upto_nchanges</code></em> are NULL,
767 logical decoding will continue until end of WAL. If
768 <em class="parameter"><code>upto_lsn</code></em> is non-NULL, decoding will include only
769 those transactions which commit prior to the specified LSN. If
770 <em class="parameter"><code>upto_nchanges</code></em> is non-NULL, decoding will
771 stop when the number of rows produced by decoding exceeds
772 the specified value. Note, however, that the actual number of
773 rows returned may be larger, since this limit is only checked after
774 adding the rows produced when decoding each new transaction commit.
775 If the specified slot is a logical failover slot then the function will
776 not return until all physical slots specified in
777 <a class="link" href="runtime-config-replication.html#GUC-SYNCHRONIZED-STANDBY-SLOTS"><code class="varname">synchronized_standby_slots</code></a>
778 have confirmed WAL receipt.
779 </p></td></tr><tr><td id="PG-LOGICAL-SLOT-PEEK-CHANGES" class="func_table_entry"><p class="func_signature">
780 <a id="id-1.5.8.34.8.5.2.2.7.1.1.1" class="indexterm"></a>
781 <code class="function">pg_logical_slot_peek_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
782 → <code class="returnvalue">setof record</code>
783 ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
784 <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
785 <em class="parameter"><code>data</code></em> <code class="type">text</code> )
789 the <code class="function">pg_logical_slot_get_changes()</code> function,
790 except that changes are not consumed; that is, they will be returned
791 again on future calls.
792 </p></td></tr><tr><td id="PG-LOGICAL-SLOT-GET-BINARY-CHANGES" class="func_table_entry"><p class="func_signature">
793 <a id="id-1.5.8.34.8.5.2.2.8.1.1.1" class="indexterm"></a>
794 <code class="function">pg_logical_slot_get_binary_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
795 → <code class="returnvalue">setof record</code>
796 ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
797 <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
798 <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
802 the <code class="function">pg_logical_slot_get_changes()</code> function,
803 except that changes are returned as <code class="type">bytea</code>.
804 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
805 <a id="id-1.5.8.34.8.5.2.2.9.1.1.1" class="indexterm"></a>
806 <code class="function">pg_logical_slot_peek_binary_changes</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>upto_nchanges</code></em> <code class="type">integer</code>, <code class="literal">VARIADIC</code> <em class="parameter"><code>options</code></em> <code class="type">text[]</code> )
807 → <code class="returnvalue">setof record</code>
808 ( <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code>,
809 <em class="parameter"><code>xid</code></em> <code class="type">xid</code>,
810 <em class="parameter"><code>data</code></em> <code class="type">bytea</code> )
814 the <code class="function">pg_logical_slot_peek_changes()</code> function,
815 except that changes are returned as <code class="type">bytea</code>.
816 </p></td></tr><tr><td id="PG-REPLICATION-SLOT-ADVANCE" class="func_table_entry"><p class="func_signature">
817 <a id="id-1.5.8.34.8.5.2.2.10.1.1.1" class="indexterm"></a>
818 <code class="function">pg_replication_slot_advance</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>, <em class="parameter"><code>upto_lsn</code></em> <code class="type">pg_lsn</code> )
819 → <code class="returnvalue">record</code>
820 ( <em class="parameter"><code>slot_name</code></em> <code class="type">name</code>,
821 <em class="parameter"><code>end_lsn</code></em> <code class="type">pg_lsn</code> )
824 Advances the current confirmed position of a replication slot named
825 <em class="parameter"><code>slot_name</code></em>. The slot will not be moved backwards,
826 and it will not be moved beyond the current insert location. Returns
827 the name of the slot and the actual position that it was advanced to.
828 The updated slot position information is written out at the next
829 checkpoint if any advancing is done. So in the event of a crash, the
830 slot may return to an earlier position. If the specified slot is a
831 logical failover slot then the function will not return until all
832 physical slots specified in
833 <a class="link" href="runtime-config-replication.html#GUC-SYNCHRONIZED-STANDBY-SLOTS"><code class="varname">synchronized_standby_slots</code></a>
834 have confirmed WAL receipt.
835 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-CREATE" class="func_table_entry"><p class="func_signature">
836 <a id="id-1.5.8.34.8.5.2.2.11.1.1.1" class="indexterm"></a>
837 <code class="function">pg_replication_origin_create</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
838 → <code class="returnvalue">oid</code>
841 Creates a replication origin with the given external
842 name, and returns the internal ID assigned to it.
843 The name must be no longer than 512 bytes.
844 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-DROP" class="func_table_entry"><p class="func_signature">
845 <a id="id-1.5.8.34.8.5.2.2.12.1.1.1" class="indexterm"></a>
846 <code class="function">pg_replication_origin_drop</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
847 → <code class="returnvalue">void</code>
850 Deletes a previously-created replication origin, including any
851 associated replay progress.
852 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
853 <a id="id-1.5.8.34.8.5.2.2.13.1.1.1" class="indexterm"></a>
854 <code class="function">pg_replication_origin_oid</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
855 → <code class="returnvalue">oid</code>
858 Looks up a replication origin by name and returns the internal ID. If
859 no such replication origin is found, <code class="literal">NULL</code> is
861 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-SESSION-SETUP" class="func_table_entry"><p class="func_signature">
862 <a id="id-1.5.8.34.8.5.2.2.14.1.1.1" class="indexterm"></a>
863 <code class="function">pg_replication_origin_session_setup</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code> )
864 → <code class="returnvalue">void</code>
867 Marks the current session as replaying from the given
868 origin, allowing replay progress to be tracked.
869 Can only be used if no origin is currently selected.
870 Use <code class="function">pg_replication_origin_session_reset</code> to undo.
871 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
872 <a id="id-1.5.8.34.8.5.2.2.15.1.1.1" class="indexterm"></a>
873 <code class="function">pg_replication_origin_session_reset</code> ()
874 → <code class="returnvalue">void</code>
878 of <code class="function">pg_replication_origin_session_setup()</code>.
879 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
880 <a id="id-1.5.8.34.8.5.2.2.16.1.1.1" class="indexterm"></a>
881 <code class="function">pg_replication_origin_session_is_setup</code> ()
882 → <code class="returnvalue">boolean</code>
885 Returns true if a replication origin has been selected in the
887 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-SESSION-PROGRESS" class="func_table_entry"><p class="func_signature">
888 <a id="id-1.5.8.34.8.5.2.2.17.1.1.1" class="indexterm"></a>
889 <code class="function">pg_replication_origin_session_progress</code> ( <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> )
890 → <code class="returnvalue">pg_lsn</code>
893 Returns the replay location for the replication origin selected in
894 the current session. The parameter <em class="parameter"><code>flush</code></em>
895 determines whether the corresponding local transaction will be
896 guaranteed to have been flushed to disk or not.
897 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-XACT-SETUP" class="func_table_entry"><p class="func_signature">
898 <a id="id-1.5.8.34.8.5.2.2.18.1.1.1" class="indexterm"></a>
899 <code class="function">pg_replication_origin_xact_setup</code> ( <em class="parameter"><code>origin_lsn</code></em> <code class="type">pg_lsn</code>, <em class="parameter"><code>origin_timestamp</code></em> <code class="type">timestamp with time zone</code> )
900 → <code class="returnvalue">void</code>
903 Marks the current transaction as replaying a transaction that has
904 committed at the given <acronym class="acronym">LSN</acronym> and timestamp. Can
905 only be called when a replication origin has been selected
906 using <code class="function">pg_replication_origin_session_setup</code>.
907 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-XACT-RESET" class="func_table_entry"><p class="func_signature">
908 <a id="id-1.5.8.34.8.5.2.2.19.1.1.1" class="indexterm"></a>
909 <code class="function">pg_replication_origin_xact_reset</code> ()
910 → <code class="returnvalue">void</code>
913 Cancels the effects of
914 <code class="function">pg_replication_origin_xact_setup()</code>.
915 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-ADVANCE" class="func_table_entry"><p class="func_signature">
916 <a id="id-1.5.8.34.8.5.2.2.20.1.1.1" class="indexterm"></a>
917 <code class="function">pg_replication_origin_advance</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code>, <em class="parameter"><code>lsn</code></em> <code class="type">pg_lsn</code> )
918 → <code class="returnvalue">void</code>
921 Sets replication progress for the given node to the given
922 location. This is primarily useful for setting up the initial
923 location, or setting a new location after configuration changes and
924 similar. Be aware that careless use of this function can lead to
925 inconsistently replicated data.
926 </p></td></tr><tr><td id="PG-REPLICATION-ORIGIN-PROGRESS" class="func_table_entry"><p class="func_signature">
927 <a id="id-1.5.8.34.8.5.2.2.21.1.1.1" class="indexterm"></a>
928 <code class="function">pg_replication_origin_progress</code> ( <em class="parameter"><code>node_name</code></em> <code class="type">text</code>, <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> )
929 → <code class="returnvalue">pg_lsn</code>
932 Returns the replay location for the given replication origin. The
933 parameter <em class="parameter"><code>flush</code></em> determines whether the
934 corresponding local transaction will be guaranteed to have been
935 flushed to disk or not.
936 </p></td></tr><tr><td id="PG-LOGICAL-EMIT-MESSAGE" class="func_table_entry"><p class="func_signature">
937 <a id="id-1.5.8.34.8.5.2.2.22.1.1.1" class="indexterm"></a>
938 <code class="function">pg_logical_emit_message</code> ( <em class="parameter"><code>transactional</code></em> <code class="type">boolean</code>, <em class="parameter"><code>prefix</code></em> <code class="type">text</code>, <em class="parameter"><code>content</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> <code class="literal">DEFAULT</code> <code class="literal">false</code></span>] )
939 → <code class="returnvalue">pg_lsn</code>
941 <p class="func_signature">
942 <code class="function">pg_logical_emit_message</code> ( <em class="parameter"><code>transactional</code></em> <code class="type">boolean</code>, <em class="parameter"><code>prefix</code></em> <code class="type">text</code>, <em class="parameter"><code>content</code></em> <code class="type">bytea</code> [<span class="optional">, <em class="parameter"><code>flush</code></em> <code class="type">boolean</code> <code class="literal">DEFAULT</code> <code class="literal">false</code></span>] )
943 → <code class="returnvalue">pg_lsn</code>
946 Emits a logical decoding message. This can be used to pass generic
947 messages to logical decoding plugins through
948 WAL. The <em class="parameter"><code>transactional</code></em> parameter specifies if
949 the message should be part of the current transaction, or if it should
950 be written immediately and decoded as soon as the logical decoder
951 reads the record. The <em class="parameter"><code>prefix</code></em> parameter is a
952 textual prefix that can be used by logical decoding plugins to easily
953 recognize messages that are interesting for them.
954 The <em class="parameter"><code>content</code></em> parameter is the content of the
955 message, given either in text or binary form.
956 The <em class="parameter"><code>flush</code></em> parameter (default set to
957 <code class="literal">false</code>) controls if the message is immediately
958 flushed to WAL or not. <em class="parameter"><code>flush</code></em> has no effect
959 with <em class="parameter"><code>transactional</code></em>, as the message's WAL
960 record is flushed along with its transaction.
961 </p></td></tr><tr><td id="PG-SYNC-REPLICATION-SLOTS" class="func_table_entry"><p class="func_signature">
962 <a id="id-1.5.8.34.8.5.2.2.23.1.1.1" class="indexterm"></a>
963 <code class="function">pg_sync_replication_slots</code> ()
964 → <code class="returnvalue">void</code>
967 Synchronize the logical failover replication slots from the primary
968 server to the standby server. This function can only be executed on the
969 standby server. Temporary synced slots, if any, cannot be used for
970 logical decoding and must be dropped after promotion. See
971 <a class="xref" href="logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS-SYNCHRONIZATION" title="47.2.3. Replication Slot Synchronization">Section 47.2.3</a> for details.
972 Note that this function is primarily intended for testing and
973 debugging purposes and should be used with caution. Additionally,
974 this function cannot be executed if
975 <a class="link" href="runtime-config-replication.html#GUC-SYNC-REPLICATION-SLOTS"><code class="varname">
976 sync_replication_slots</code></a> is enabled and the slotsync
977 worker is already running to perform the synchronization of slots.
980 <div class="caution"><h3 class="title">Caution</h3><p>
981 If, after executing the function,
982 <a class="link" href="runtime-config-replication.html#GUC-HOT-STANDBY-FEEDBACK">
983 <code class="varname">hot_standby_feedback</code></a> is disabled on
984 the standby or the physical slot configured in
985 <a class="link" href="runtime-config-replication.html#GUC-PRIMARY-SLOT-NAME">
986 <code class="varname">primary_slot_name</code></a> is
987 removed, then it is possible that the necessary rows of the
988 synchronized slot will be removed by the VACUUM process on the primary
989 server, resulting in the synchronized slot becoming invalidated.
991 </td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-DBOBJECT"><div class="titlepage"><div><div><h3 class="title">9.28.7. Database Object Management Functions <a href="#FUNCTIONS-ADMIN-DBOBJECT" class="id_link">#</a></h3></div></div></div><p>
992 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-DBSIZE" title="Table 9.102. Database Object Size Functions">Table 9.102</a> calculate
993 the disk space usage of database objects, or assist in presentation
994 or understanding of usage results. <code class="literal">bigint</code> results
995 are measured in bytes. If an OID that does
996 not represent an existing object is passed to one of these
997 functions, <code class="literal">NULL</code> is returned.
998 </p><div class="table" id="FUNCTIONS-ADMIN-DBSIZE"><p class="title"><strong>Table 9.102. Database Object Size Functions</strong></p><div class="table-contents"><table class="table" summary="Database Object Size Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1003 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1004 <a id="id-1.5.8.34.9.3.2.2.1.1.1.1" class="indexterm"></a>
1005 <code class="function">pg_column_size</code> ( <code class="type">"any"</code> )
1006 → <code class="returnvalue">integer</code>
1009 Shows the number of bytes used to store any individual data value. If
1010 applied directly to a table column value, this reflects any
1011 compression that was done.
1012 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1013 <a id="id-1.5.8.34.9.3.2.2.2.1.1.1" class="indexterm"></a>
1014 <code class="function">pg_column_compression</code> ( <code class="type">"any"</code> )
1015 → <code class="returnvalue">text</code>
1018 Shows the compression algorithm that was used to compress
1019 an individual variable-length value. Returns <code class="literal">NULL</code>
1020 if the value is not compressed.
1021 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1022 <a id="id-1.5.8.34.9.3.2.2.3.1.1.1" class="indexterm"></a>
1023 <code class="function">pg_column_toast_chunk_id</code> ( <code class="type">"any"</code> )
1024 → <code class="returnvalue">oid</code>
1027 Shows the <code class="structfield">chunk_id</code> of an on-disk
1028 <acronym class="acronym">TOAST</acronym>ed value. Returns <code class="literal">NULL</code>
1029 if the value is un-<acronym class="acronym">TOAST</acronym>ed or not on-disk. See
1030 <a class="xref" href="storage-toast.html" title="66.2. TOAST">Section 66.2</a> for more information about
1031 <acronym class="acronym">TOAST</acronym>.
1032 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1033 <a id="id-1.5.8.34.9.3.2.2.4.1.1.1" class="indexterm"></a>
1034 <code class="function">pg_database_size</code> ( <code class="type">name</code> )
1035 → <code class="returnvalue">bigint</code>
1037 <p class="func_signature">
1038 <code class="function">pg_database_size</code> ( <code class="type">oid</code> )
1039 → <code class="returnvalue">bigint</code>
1042 Computes the total disk space used by the database with the specified
1043 name or OID. To use this function, you must
1044 have <code class="literal">CONNECT</code> privilege on the specified database
1045 (which is granted by default) or have privileges of
1046 the <code class="literal">pg_read_all_stats</code> role.
1047 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1048 <a id="id-1.5.8.34.9.3.2.2.5.1.1.1" class="indexterm"></a>
1049 <code class="function">pg_indexes_size</code> ( <code class="type">regclass</code> )
1050 → <code class="returnvalue">bigint</code>
1053 Computes the total disk space used by indexes attached to the
1055 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1056 <a id="id-1.5.8.34.9.3.2.2.6.1.1.1" class="indexterm"></a>
1057 <code class="function">pg_relation_size</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> [<span class="optional">, <em class="parameter"><code>fork</code></em> <code class="type">text</code> </span>] )
1058 → <code class="returnvalue">bigint</code>
1061 Computes the disk space used by one <span class="quote">“<span class="quote">fork</span>”</span> of the
1062 specified relation. (Note that for most purposes it is more
1063 convenient to use the higher-level
1064 functions <code class="function">pg_total_relation_size</code>
1065 or <code class="function">pg_table_size</code>, which sum the sizes of all
1066 forks.) With one argument, this returns the size of the main data
1067 fork of the relation. The second argument can be provided to specify
1068 which fork to examine:
1069 </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem"><p>
1070 <code class="literal">main</code> returns the size of the main
1071 data fork of the relation.
1072 </p></li><li class="listitem"><p>
1073 <code class="literal">fsm</code> returns the size of the Free Space Map
1074 (see <a class="xref" href="storage-fsm.html" title="66.3. Free Space Map">Section 66.3</a>) associated with the relation.
1075 </p></li><li class="listitem"><p>
1076 <code class="literal">vm</code> returns the size of the Visibility Map
1077 (see <a class="xref" href="storage-vm.html" title="66.4. Visibility Map">Section 66.4</a>) associated with the relation.
1078 </p></li><li class="listitem"><p>
1079 <code class="literal">init</code> returns the size of the initialization
1080 fork, if any, associated with the relation.
1081 </p></li></ul></div><p>
1082 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1083 <a id="id-1.5.8.34.9.3.2.2.7.1.1.1" class="indexterm"></a>
1084 <code class="function">pg_size_bytes</code> ( <code class="type">text</code> )
1085 → <code class="returnvalue">bigint</code>
1088 Converts a size in human-readable format (as returned
1089 by <code class="function">pg_size_pretty</code>) into bytes. Valid units are
1090 <code class="literal">bytes</code>, <code class="literal">B</code>, <code class="literal">kB</code>,
1091 <code class="literal">MB</code>, <code class="literal">GB</code>, <code class="literal">TB</code>,
1092 and <code class="literal">PB</code>.
1093 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1094 <a id="id-1.5.8.34.9.3.2.2.8.1.1.1" class="indexterm"></a>
1095 <code class="function">pg_size_pretty</code> ( <code class="type">bigint</code> )
1096 → <code class="returnvalue">text</code>
1098 <p class="func_signature">
1099 <code class="function">pg_size_pretty</code> ( <code class="type">numeric</code> )
1100 → <code class="returnvalue">text</code>
1103 Converts a size in bytes into a more easily human-readable format with
1104 size units (bytes, kB, MB, GB, TB, or PB as appropriate). Note that the
1105 units are powers of 2 rather than powers of 10, so 1kB is 1024 bytes,
1106 1MB is 1024<sup>2</sup> = 1048576 bytes, and so on.
1107 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1108 <a id="id-1.5.8.34.9.3.2.2.9.1.1.1" class="indexterm"></a>
1109 <code class="function">pg_table_size</code> ( <code class="type">regclass</code> )
1110 → <code class="returnvalue">bigint</code>
1113 Computes the disk space used by the specified table, excluding indexes
1114 (but including its TOAST table if any, free space map, and visibility
1116 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1117 <a id="id-1.5.8.34.9.3.2.2.10.1.1.1" class="indexterm"></a>
1118 <code class="function">pg_tablespace_size</code> ( <code class="type">name</code> )
1119 → <code class="returnvalue">bigint</code>
1121 <p class="func_signature">
1122 <code class="function">pg_tablespace_size</code> ( <code class="type">oid</code> )
1123 → <code class="returnvalue">bigint</code>
1126 Computes the total disk space used in the tablespace with the
1127 specified name or OID. To use this function, you must
1128 have <code class="literal">CREATE</code> privilege on the specified tablespace
1129 or have privileges of the <code class="literal">pg_read_all_stats</code> role,
1130 unless it is the default tablespace for the current database.
1131 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1132 <a id="id-1.5.8.34.9.3.2.2.11.1.1.1" class="indexterm"></a>
1133 <code class="function">pg_total_relation_size</code> ( <code class="type">regclass</code> )
1134 → <code class="returnvalue">bigint</code>
1137 Computes the total disk space used by the specified table, including
1138 all indexes and <acronym class="acronym">TOAST</acronym> data. The result is
1139 equivalent to <code class="function">pg_table_size</code>
1140 <code class="literal">+</code> <code class="function">pg_indexes_size</code>.
1141 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
1142 The functions above that operate on tables or indexes accept a
1143 <code class="type">regclass</code> argument, which is simply the OID of the table or index
1144 in the <code class="structname">pg_class</code> system catalog. You do not have to look up
1145 the OID by hand, however, since the <code class="type">regclass</code> data type's input
1146 converter will do the work for you. See <a class="xref" href="datatype-oid.html" title="8.19. Object Identifier Types">Section 8.19</a>
1149 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-DBLOCATION" title="Table 9.103. Database Object Location Functions">Table 9.103</a> assist
1150 in identifying the specific disk files associated with database objects.
1151 </p><div class="table" id="FUNCTIONS-ADMIN-DBLOCATION"><p class="title"><strong>Table 9.103. Database Object Location Functions</strong></p><div class="table-contents"><table class="table" summary="Database Object Location Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1156 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1157 <a id="id-1.5.8.34.9.6.2.2.1.1.1.1" class="indexterm"></a>
1158 <code class="function">pg_relation_filenode</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> )
1159 → <code class="returnvalue">oid</code>
1162 Returns the <span class="quote">“<span class="quote">filenode</span>”</span> number currently assigned to the
1163 specified relation. The filenode is the base component of the file
1164 name(s) used for the relation (see
1165 <a class="xref" href="storage-file-layout.html" title="66.1. Database File Layout">Section 66.1</a> for more information).
1166 For most relations the result is the same as
1167 <code class="structname">pg_class</code>.<code class="structfield">relfilenode</code>,
1168 but for certain system catalogs <code class="structfield">relfilenode</code>
1169 is zero and this function must be used to get the correct value. The
1170 function returns NULL if passed a relation that does not have storage,
1172 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1173 <a id="id-1.5.8.34.9.6.2.2.2.1.1.1" class="indexterm"></a>
1174 <code class="function">pg_relation_filepath</code> ( <em class="parameter"><code>relation</code></em> <code class="type">regclass</code> )
1175 → <code class="returnvalue">text</code>
1178 Returns the entire file path name (relative to the database cluster's
1179 data directory, <code class="varname">PGDATA</code>) of the relation.
1180 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1181 <a id="id-1.5.8.34.9.6.2.2.3.1.1.1" class="indexterm"></a>
1182 <code class="function">pg_filenode_relation</code> ( <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code>, <em class="parameter"><code>filenode</code></em> <code class="type">oid</code> )
1183 → <code class="returnvalue">regclass</code>
1186 Returns a relation's OID given the tablespace OID and filenode it is
1187 stored under. This is essentially the inverse mapping of
1188 <code class="function">pg_relation_filepath</code>. For a relation in the
1189 database's default tablespace, the tablespace can be specified as zero.
1190 Returns <code class="literal">NULL</code> if no relation in the current database
1191 is associated with the given values, or if dealing with a temporary
1193 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
1194 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-COLLATION" title="Table 9.104. Collation Management Functions">Table 9.104</a> lists functions used to manage
1196 </p><div class="table" id="FUNCTIONS-ADMIN-COLLATION"><p class="title"><strong>Table 9.104. Collation Management Functions</strong></p><div class="table-contents"><table class="table" summary="Collation Management Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1201 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1202 <a id="id-1.5.8.34.9.8.2.2.1.1.1.1" class="indexterm"></a>
1203 <code class="function">pg_collation_actual_version</code> ( <code class="type">oid</code> )
1204 → <code class="returnvalue">text</code>
1207 Returns the actual version of the collation object as it is currently
1208 installed in the operating system. If this is different from the
1210 <code class="structname">pg_collation</code>.<code class="structfield">collversion</code>,
1211 then objects depending on the collation might need to be rebuilt. See
1212 also <a class="xref" href="sql-altercollation.html" title="ALTER COLLATION"><span class="refentrytitle">ALTER COLLATION</span></a>.
1213 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1214 <a id="id-1.5.8.34.9.8.2.2.2.1.1.1" class="indexterm"></a>
1215 <code class="function">pg_database_collation_actual_version</code> ( <code class="type">oid</code> )
1216 → <code class="returnvalue">text</code>
1219 Returns the actual version of the database's collation as it is currently
1220 installed in the operating system. If this is different from the
1222 <code class="structname">pg_database</code>.<code class="structfield">datcollversion</code>,
1223 then objects depending on the collation might need to be rebuilt. See
1224 also <a class="xref" href="sql-alterdatabase.html" title="ALTER DATABASE"><span class="refentrytitle">ALTER DATABASE</span></a>.
1225 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1226 <a id="id-1.5.8.34.9.8.2.2.3.1.1.1" class="indexterm"></a>
1227 <code class="function">pg_import_system_collations</code> ( <em class="parameter"><code>schema</code></em> <code class="type">regnamespace</code> )
1228 → <code class="returnvalue">integer</code>
1231 Adds collations to the system
1232 catalog <code class="structname">pg_collation</code> based on all the locales
1233 it finds in the operating system. This is
1234 what <code class="command">initdb</code> uses; see
1235 <a class="xref" href="collation.html#COLLATION-MANAGING" title="23.2.2. Managing Collations">Section 23.2.2</a> for more details. If additional
1236 locales are installed into the operating system later on, this
1237 function can be run again to add collations for the new locales.
1238 Locales that match existing entries
1239 in <code class="structname">pg_collation</code> will be skipped. (But
1240 collation objects based on locales that are no longer present in the
1241 operating system are not removed by this function.)
1242 The <em class="parameter"><code>schema</code></em> parameter would typically
1243 be <code class="literal">pg_catalog</code>, but that is not a requirement; the
1244 collations could be installed into some other schema as well. The
1245 function returns the number of new collation objects it created.
1246 Use of this function is restricted to superusers.
1247 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
1248 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-STATSMOD" title="Table 9.105. Database Object Statistics Manipulation Functions">Table 9.105</a> lists functions used to
1249 manipulate statistics.
1250 These functions cannot be executed during recovery.
1251 </p><div class="warning"><h3 class="title">Warning</h3><p>
1252 Changes made by these statistics manipulation functions are likely to be
1253 overwritten by <a class="link" href="routine-vacuuming.html#AUTOVACUUM" title="24.1.6. The Autovacuum Daemon">autovacuum</a> (or manual
1254 <code class="command">VACUUM</code> or <code class="command">ANALYZE</code>) and should be
1255 considered temporary.
1257 </p><div class="table" id="FUNCTIONS-ADMIN-STATSMOD"><p class="title"><strong>Table 9.105. Database Object Statistics Manipulation Functions</strong></p><div class="table-contents"><table class="table" summary="Database Object Statistics Manipulation Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1262 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1263 <a id="id-1.5.8.34.9.10.2.2.1.1.1.1" class="indexterm"></a>
1264 <code class="function">pg_restore_relation_stats</code> (
1265 <code class="literal">VARIADIC</code> <em class="parameter"><code>kwargs</code></em> <code class="type">"any"</code> )
1266 → <code class="returnvalue">boolean</code>
1269 Updates table-level statistics. Ordinarily, these statistics are
1270 collected automatically or updated as a part of <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a> or <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>, so it's not
1271 necessary to call this function. However, it is useful after a
1272 restore to enable the optimizer to choose better plans if
1273 <code class="command">ANALYZE</code> has not been run yet.
1276 The tracked statistics may change from version to version, so
1277 arguments are passed as pairs of <em class="replaceable"><code>argname</code></em>
1278 and <em class="replaceable"><code>argvalue</code></em> in the form:
1279 </p><pre class="programlisting">
1280 SELECT pg_restore_relation_stats(
1281 '<em class="replaceable"><code>arg1name</code></em>', '<em class="replaceable"><code>arg1value</code></em>'::<em class="replaceable"><code>arg1type</code></em>,
1282 '<em class="replaceable"><code>arg2name</code></em>', '<em class="replaceable"><code>arg2value</code></em>'::<em class="replaceable"><code>arg2type</code></em>,
1283 '<em class="replaceable"><code>arg3name</code></em>', '<em class="replaceable"><code>arg3value</code></em>'::<em class="replaceable"><code>arg3type</code></em>);
1287 For example, to set the <code class="structfield">relpages</code> and
1288 <code class="structfield">reltuples</code> values for the table
1289 <code class="structname">mytable</code>:
1290 </p><pre class="programlisting">
1291 SELECT pg_restore_relation_stats(
1292 'schemaname', 'myschema',
1293 'relname', 'mytable',
1294 'relpages', 173::integer,
1295 'reltuples', 10000::real);
1299 The arguments <code class="literal">schemaname</code> and
1300 <code class="literal">relname</code> are required, and specify the table. Other
1301 arguments are the names and values of statistics corresponding to
1302 certain columns in <a class="link" href="catalog-pg-class.html" title="52.11. pg_class"><code class="structname">pg_class</code></a>.
1303 The currently-supported relation statistics are
1304 <code class="literal">relpages</code> with a value of type
1305 <code class="type">integer</code>, <code class="literal">reltuples</code> with a value of
1306 type <code class="type">real</code>, <code class="literal">relallvisible</code> with a value
1307 of type <code class="type">integer</code>, and <code class="literal">relallfrozen</code>
1308 with a value of type <code class="type">integer</code>.
1311 Additionally, this function accepts argument name
1312 <code class="literal">version</code> of type <code class="type">integer</code>, which
1313 specifies the server version from which the statistics originated.
1314 This is anticipated to be helpful in porting statistics from older
1315 versions of <span class="productname">PostgreSQL</span>.
1318 Minor errors are reported as a <code class="literal">WARNING</code> and
1319 ignored, and remaining statistics will still be restored. If all
1320 specified statistics are successfully restored, returns
1321 <code class="literal">true</code>, otherwise <code class="literal">false</code>.
1324 The caller must have the <code class="literal">MAINTAIN</code> privilege on the
1325 table or be the owner of the database.
1327 </td></tr><tr><td class="func_table_entry">
1328 <p class="func_signature">
1329 <a id="id-1.5.8.34.9.10.2.2.2.1.1.1" class="indexterm"></a>
1330 <code class="function">pg_clear_relation_stats</code> ( <em class="parameter"><code>schemaname</code></em> <code class="type">text</code>, <em class="parameter"><code>relname</code></em> <code class="type">text</code> )
1331 → <code class="returnvalue">void</code>
1334 Clears table-level statistics for the given relation, as though the
1335 table was newly created.
1338 The caller must have the <code class="literal">MAINTAIN</code> privilege on the
1339 table or be the owner of the database.
1341 </td></tr><tr><td class="func_table_entry"><p class="func_signature">
1342 <a id="id-1.5.8.34.9.10.2.2.3.1.1.1" class="indexterm"></a>
1343 <code class="function">pg_restore_attribute_stats</code> (
1344 <code class="literal">VARIADIC</code> <em class="parameter"><code>kwargs</code></em> <code class="type">"any"</code> )
1345 → <code class="returnvalue">boolean</code>
1348 Creates or updates column-level statistics. Ordinarily, these
1349 statistics are collected automatically or updated as a part of <a class="xref" href="sql-vacuum.html" title="VACUUM"><span class="refentrytitle">VACUUM</span></a> or <a class="xref" href="sql-analyze.html" title="ANALYZE"><span class="refentrytitle">ANALYZE</span></a>, so it's not
1350 necessary to call this function. However, it is useful after a
1351 restore to enable the optimizer to choose better plans if
1352 <code class="command">ANALYZE</code> has not been run yet.
1355 The tracked statistics may change from version to version, so
1356 arguments are passed as pairs of <em class="replaceable"><code>argname</code></em>
1357 and <em class="replaceable"><code>argvalue</code></em> in the form:
1358 </p><pre class="programlisting">
1359 SELECT pg_restore_attribute_stats(
1360 '<em class="replaceable"><code>arg1name</code></em>', '<em class="replaceable"><code>arg1value</code></em>'::<em class="replaceable"><code>arg1type</code></em>,
1361 '<em class="replaceable"><code>arg2name</code></em>', '<em class="replaceable"><code>arg2value</code></em>'::<em class="replaceable"><code>arg2type</code></em>,
1362 '<em class="replaceable"><code>arg3name</code></em>', '<em class="replaceable"><code>arg3value</code></em>'::<em class="replaceable"><code>arg3type</code></em>);
1366 For example, to set the <code class="structfield">avg_width</code> and
1367 <code class="structfield">null_frac</code> values for the attribute
1368 <code class="structfield">col1</code> of the table
1369 <code class="structname">mytable</code>:
1370 </p><pre class="programlisting">
1371 SELECT pg_restore_attribute_stats(
1372 'schemaname', 'myschema',
1373 'relname', 'mytable',
1376 'avg_width', 125::integer,
1377 'null_frac', 0.5::real);
1381 The required arguments are <code class="literal">schemaname</code> and
1382 <code class="literal">relname</code> with a value of type <code class="type">text</code>
1383 which specify the table; either <code class="literal">attname</code> with a
1384 value of type <code class="type">text</code> or <code class="literal">attnum</code> with a
1385 value of type <code class="type">smallint</code>, which specifies the column; and
1386 <code class="literal">inherited</code>, which specifies whether the statistics
1387 include values from child tables. Other arguments are the names and
1388 values of statistics corresponding to columns in <a class="link" href="view-pg-stats.html" title="53.29. pg_stats"><code class="structname">pg_stats</code></a>.
1391 Additionally, this function accepts argument name
1392 <code class="literal">version</code> of type <code class="type">integer</code>, which
1393 specifies the server version from which the statistics originated.
1394 This is anticipated to be helpful in porting statistics from older
1395 versions of <span class="productname">PostgreSQL</span>.
1398 Minor errors are reported as a <code class="literal">WARNING</code> and
1399 ignored, and remaining statistics will still be restored. If all
1400 specified statistics are successfully restored, returns
1401 <code class="literal">true</code>, otherwise <code class="literal">false</code>.
1404 The caller must have the <code class="literal">MAINTAIN</code> privilege on the
1405 table or be the owner of the database.
1407 </td></tr><tr><td class="func_table_entry">
1408 <p class="func_signature">
1409 <a id="id-1.5.8.34.9.10.2.2.4.1.1.1" class="indexterm"></a>
1410 <code class="function">pg_clear_attribute_stats</code> (
1411 <em class="parameter"><code>schemaname</code></em> <code class="type">text</code>,
1412 <em class="parameter"><code>relname</code></em> <code class="type">text</code>,
1413 <em class="parameter"><code>attname</code></em> <code class="type">text</code>,
1414 <em class="parameter"><code>inherited</code></em> <code class="type">boolean</code> )
1415 → <code class="returnvalue">void</code>
1418 Clears column-level statistics for the given relation and
1419 attribute, as though the table was newly created.
1422 The caller must have the <code class="literal">MAINTAIN</code> privilege on
1423 the table or be the owner of the database.
1425 </td></tr></tbody></table></div></div><br class="table-break" /><p>
1426 <a class="xref" href="functions-admin.html#FUNCTIONS-INFO-PARTITION" title="Table 9.106. Partitioning Information Functions">Table 9.106</a> lists functions that provide
1427 information about the structure of partitioned tables.
1428 </p><div class="table" id="FUNCTIONS-INFO-PARTITION"><p class="title"><strong>Table 9.106. Partitioning Information Functions</strong></p><div class="table-contents"><table class="table" summary="Partitioning Information Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1433 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1434 <a id="id-1.5.8.34.9.12.2.2.1.1.1.1" class="indexterm"></a>
1435 <code class="function">pg_partition_tree</code> ( <code class="type">regclass</code> )
1436 → <code class="returnvalue">setof record</code>
1437 ( <em class="parameter"><code>relid</code></em> <code class="type">regclass</code>,
1438 <em class="parameter"><code>parentrelid</code></em> <code class="type">regclass</code>,
1439 <em class="parameter"><code>isleaf</code></em> <code class="type">boolean</code>,
1440 <em class="parameter"><code>level</code></em> <code class="type">integer</code> )
1443 Lists the tables or indexes in the partition tree of the
1444 given partitioned table or partitioned index, with one row for each
1445 partition. Information provided includes the OID of the partition,
1446 the OID of its immediate parent, a boolean value telling if the
1447 partition is a leaf, and an integer telling its level in the hierarchy.
1448 The level value is 0 for the input table or index, 1 for its
1449 immediate child partitions, 2 for their partitions, and so on.
1450 Returns no rows if the relation does not exist or is not a partition
1451 or partitioned table.
1452 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1453 <a id="id-1.5.8.34.9.12.2.2.2.1.1.1" class="indexterm"></a>
1454 <code class="function">pg_partition_ancestors</code> ( <code class="type">regclass</code> )
1455 → <code class="returnvalue">setof regclass</code>
1458 Lists the ancestor relations of the given partition,
1459 including the relation itself. Returns no rows if the relation
1460 does not exist or is not a partition or partitioned table.
1461 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1462 <a id="id-1.5.8.34.9.12.2.2.3.1.1.1" class="indexterm"></a>
1463 <code class="function">pg_partition_root</code> ( <code class="type">regclass</code> )
1464 → <code class="returnvalue">regclass</code>
1467 Returns the top-most parent of the partition tree to which the given
1468 relation belongs. Returns <code class="literal">NULL</code> if the relation
1469 does not exist or is not a partition or partitioned table.
1470 </p></td></tr></tbody></table></div></div><br class="table-break" /><p>
1471 For example, to check the total size of the data contained in a
1472 partitioned table <code class="structname">measurement</code>, one could use the
1474 </p><pre class="programlisting">
1475 SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
1476 FROM pg_partition_tree('measurement');
1478 </p></div><div class="sect2" id="FUNCTIONS-ADMIN-INDEX"><div class="titlepage"><div><div><h3 class="title">9.28.8. Index Maintenance Functions <a href="#FUNCTIONS-ADMIN-INDEX" class="id_link">#</a></h3></div></div></div><p>
1479 <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-INDEX-TABLE" title="Table 9.107. Index Maintenance Functions">Table 9.107</a> shows the functions
1480 available for index maintenance tasks. (Note that these maintenance
1481 tasks are normally done automatically by autovacuum; use of these
1482 functions is only required in special cases.)
1483 These functions cannot be executed during recovery.
1484 Use of these functions is restricted to superusers and the owner
1486 </p><div class="table" id="FUNCTIONS-ADMIN-INDEX-TABLE"><p class="title"><strong>Table 9.107. Index Maintenance Functions</strong></p><div class="table-contents"><table class="table" summary="Index Maintenance Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1491 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1492 <a id="id-1.5.8.34.10.3.2.2.1.1.1.1" class="indexterm"></a>
1493 <code class="function">brin_summarize_new_values</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code> )
1494 → <code class="returnvalue">integer</code>
1497 Scans the specified BRIN index to find page ranges in the base table
1498 that are not currently summarized by the index; for any such range it
1499 creates a new summary index tuple by scanning those table pages.
1500 Returns the number of new page range summaries that were inserted
1502 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1503 <a id="id-1.5.8.34.10.3.2.2.2.1.1.1" class="indexterm"></a>
1504 <code class="function">brin_summarize_range</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>blockNumber</code></em> <code class="type">bigint</code> )
1505 → <code class="returnvalue">integer</code>
1508 Summarizes the page range covering the given block, if not already
1510 like <code class="function">brin_summarize_new_values</code> except that it
1511 only processes the page range that covers the given table block number.
1512 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1513 <a id="id-1.5.8.34.10.3.2.2.3.1.1.1" class="indexterm"></a>
1514 <code class="function">brin_desummarize_range</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code>, <em class="parameter"><code>blockNumber</code></em> <code class="type">bigint</code> )
1515 → <code class="returnvalue">void</code>
1518 Removes the BRIN index tuple that summarizes the page range covering
1519 the given table block, if there is one.
1520 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1521 <a id="id-1.5.8.34.10.3.2.2.4.1.1.1" class="indexterm"></a>
1522 <code class="function">gin_clean_pending_list</code> ( <em class="parameter"><code>index</code></em> <code class="type">regclass</code> )
1523 → <code class="returnvalue">bigint</code>
1526 Cleans up the <span class="quote">“<span class="quote">pending</span>”</span> list of the specified GIN index
1527 by moving entries in it, in bulk, to the main GIN data structure.
1528 Returns the number of pages removed from the pending list.
1529 If the argument is a GIN index built with
1530 the <code class="literal">fastupdate</code> option disabled, no cleanup happens
1531 and the result is zero, because the index doesn't have a pending list.
1532 See <a class="xref" href="gin.html#GIN-FAST-UPDATE" title="65.4.4.1. GIN Fast Update Technique">Section 65.4.4.1</a> and <a class="xref" href="gin.html#GIN-TIPS" title="65.4.5. GIN Tips and Tricks">Section 65.4.5</a>
1533 for details about the pending list and <code class="literal">fastupdate</code>
1535 </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADMIN-GENFILE"><div class="titlepage"><div><div><h3 class="title">9.28.9. Generic File Access Functions <a href="#FUNCTIONS-ADMIN-GENFILE" class="id_link">#</a></h3></div></div></div><p>
1536 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-GENFILE-TABLE" title="Table 9.108. Generic File Access Functions">Table 9.108</a> provide native access to
1537 files on the machine hosting the server. Only files within the
1538 database cluster directory and the <code class="varname">log_directory</code> can be
1539 accessed, unless the user is a superuser or is granted the role
1540 <code class="literal">pg_read_server_files</code>. Use a relative path for files in
1541 the cluster directory, and a path matching the <code class="varname">log_directory</code>
1542 configuration setting for log files.
1544 Note that granting users the EXECUTE privilege on
1545 <code class="function">pg_read_file()</code>, or related functions, allows them the
1546 ability to read any file on the server that the database server process can
1547 read; these functions bypass all in-database privilege checks. This means
1548 that, for example, a user with such access is able to read the contents of
1549 the <code class="structname">pg_authid</code> table where authentication
1550 information is stored, as well as read any table data in the database.
1551 Therefore, granting access to these functions should be carefully
1554 When granting privilege on these functions, note that the table entries
1555 showing optional parameters are mostly implemented as several physical
1556 functions with different parameter lists. Privilege must be granted
1557 separately on each such function, if it is to be
1558 used. <span class="application">psql</span>'s <code class="command">\df</code> command
1559 can be useful to check what the actual function signatures are.
1561 Some of these functions take an optional <em class="parameter"><code>missing_ok</code></em>
1562 parameter, which specifies the behavior when the file or directory does
1563 not exist. If <code class="literal">true</code>, the function
1564 returns <code class="literal">NULL</code> or an empty result set, as appropriate.
1565 If <code class="literal">false</code>, an error is raised. (Failure conditions
1566 other than <span class="quote">“<span class="quote">file not found</span>”</span> are reported as errors in any
1567 case.) The default is <code class="literal">false</code>.
1568 </p><div class="table" id="FUNCTIONS-ADMIN-GENFILE-TABLE"><p class="title"><strong>Table 9.108. Generic File Access Functions</strong></p><div class="table-contents"><table class="table" summary="Generic File Access Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1573 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1574 <a id="id-1.5.8.34.11.6.2.2.1.1.1.1" class="indexterm"></a>
1575 <code class="function">pg_ls_dir</code> ( <em class="parameter"><code>dirname</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code>, <em class="parameter"><code>include_dot_dirs</code></em> <code class="type">boolean</code> </span>] )
1576 → <code class="returnvalue">setof text</code>
1579 Returns the names of all files (and directories and other special
1580 files) in the specified
1581 directory. The <em class="parameter"><code>include_dot_dirs</code></em> parameter
1582 indicates whether <span class="quote">“<span class="quote">.</span>”</span> and <span class="quote">“<span class="quote">..</span>”</span> are to be
1583 included in the result set; the default is to exclude them. Including
1584 them can be useful when <em class="parameter"><code>missing_ok</code></em>
1585 is <code class="literal">true</code>, to distinguish an empty directory from a
1586 non-existent directory.
1589 This function is restricted to superusers by default, but other users
1590 can be granted EXECUTE to run the function.
1591 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1592 <a id="id-1.5.8.34.11.6.2.2.2.1.1.1" class="indexterm"></a>
1593 <code class="function">pg_ls_logdir</code> ()
1594 → <code class="returnvalue">setof record</code>
1595 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1596 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1597 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1600 Returns the name, size, and last modification time (mtime) of each
1601 ordinary file in the server's log directory. Filenames beginning with
1602 a dot, directories, and other special files are excluded.
1605 This function is restricted to superusers and roles with privileges of
1606 the <code class="literal">pg_monitor</code> role by default, but other users can
1607 be granted EXECUTE to run the function.
1608 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1609 <a id="id-1.5.8.34.11.6.2.2.3.1.1.1" class="indexterm"></a>
1610 <code class="function">pg_ls_waldir</code> ()
1611 → <code class="returnvalue">setof record</code>
1612 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1613 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1614 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1617 Returns the name, size, and last modification time (mtime) of each
1618 ordinary file in the server's write-ahead log (WAL) directory.
1619 Filenames beginning with a dot, directories, and other special files
1623 This function is restricted to superusers and roles with privileges of
1624 the <code class="literal">pg_monitor</code> role by default, but other users can
1625 be granted EXECUTE to run the function.
1626 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1627 <a id="id-1.5.8.34.11.6.2.2.4.1.1.1" class="indexterm"></a>
1628 <code class="function">pg_ls_logicalmapdir</code> ()
1629 → <code class="returnvalue">setof record</code>
1630 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1631 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1632 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1635 Returns the name, size, and last modification time (mtime) of each
1636 ordinary file in the server's <code class="filename">pg_logical/mappings</code>
1637 directory. Filenames beginning with a dot, directories, and other
1638 special files are excluded.
1641 This function is restricted to superusers and members of
1642 the <code class="literal">pg_monitor</code> role by default, but other users can
1643 be granted EXECUTE to run the function.
1644 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1645 <a id="id-1.5.8.34.11.6.2.2.5.1.1.1" class="indexterm"></a>
1646 <code class="function">pg_ls_logicalsnapdir</code> ()
1647 → <code class="returnvalue">setof record</code>
1648 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1649 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1650 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1653 Returns the name, size, and last modification time (mtime) of each
1654 ordinary file in the server's <code class="filename">pg_logical/snapshots</code>
1655 directory. Filenames beginning with a dot, directories, and other
1656 special files are excluded.
1659 This function is restricted to superusers and members of
1660 the <code class="literal">pg_monitor</code> role by default, but other users can
1661 be granted EXECUTE to run the function.
1662 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1663 <a id="id-1.5.8.34.11.6.2.2.6.1.1.1" class="indexterm"></a>
1664 <code class="function">pg_ls_replslotdir</code> ( <em class="parameter"><code>slot_name</code></em> <code class="type">text</code> )
1665 → <code class="returnvalue">setof record</code>
1666 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1667 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1668 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1671 Returns the name, size, and last modification time (mtime) of each
1672 ordinary file in the server's <code class="filename">pg_replslot/slot_name</code>
1673 directory, where <em class="parameter"><code>slot_name</code></em> is the name of the
1674 replication slot provided as input of the function. Filenames beginning
1675 with a dot, directories, and other special files are excluded.
1678 This function is restricted to superusers and members of
1679 the <code class="literal">pg_monitor</code> role by default, but other users can
1680 be granted EXECUTE to run the function.
1681 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1682 <a id="id-1.5.8.34.11.6.2.2.7.1.1.1" class="indexterm"></a>
1683 <code class="function">pg_ls_summariesdir</code> ()
1684 → <code class="returnvalue">setof record</code>
1685 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1686 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1687 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1690 Returns the name, size, and last modification time (mtime) of each
1691 ordinary file in the server's WAL summaries directory
1692 (<code class="filename">pg_wal/summaries</code>). Filenames beginning
1693 with a dot, directories, and other special files are excluded.
1696 This function is restricted to superusers and members of
1697 the <code class="literal">pg_monitor</code> role by default, but other users can
1698 be granted EXECUTE to run the function.
1699 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1700 <a id="id-1.5.8.34.11.6.2.2.8.1.1.1" class="indexterm"></a>
1701 <code class="function">pg_ls_archive_statusdir</code> ()
1702 → <code class="returnvalue">setof record</code>
1703 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1704 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1705 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1708 Returns the name, size, and last modification time (mtime) of each
1709 ordinary file in the server's WAL archive status directory
1710 (<code class="filename">pg_wal/archive_status</code>). Filenames beginning
1711 with a dot, directories, and other special files are excluded.
1714 This function is restricted to superusers and members of
1715 the <code class="literal">pg_monitor</code> role by default, but other users can
1716 be granted EXECUTE to run the function.
1717 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1719 <a id="id-1.5.8.34.11.6.2.2.9.1.1.1" class="indexterm"></a>
1720 <code class="function">pg_ls_tmpdir</code> ( [<span class="optional"> <em class="parameter"><code>tablespace</code></em> <code class="type">oid</code> </span>] )
1721 → <code class="returnvalue">setof record</code>
1722 ( <em class="parameter"><code>name</code></em> <code class="type">text</code>,
1723 <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1724 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code> )
1727 Returns the name, size, and last modification time (mtime) of each
1728 ordinary file in the temporary file directory for the
1729 specified <em class="parameter"><code>tablespace</code></em>.
1730 If <em class="parameter"><code>tablespace</code></em> is not provided,
1731 the <code class="literal">pg_default</code> tablespace is examined. Filenames
1732 beginning with a dot, directories, and other special files are
1736 This function is restricted to superusers and members of
1737 the <code class="literal">pg_monitor</code> role by default, but other users can
1738 be granted EXECUTE to run the function.
1739 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1740 <a id="id-1.5.8.34.11.6.2.2.10.1.1.1" class="indexterm"></a>
1741 <code class="function">pg_read_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">bigint</code> </span>] [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
1742 → <code class="returnvalue">text</code>
1745 Returns all or part of a text file, starting at the
1746 given byte <em class="parameter"><code>offset</code></em>, returning at
1747 most <em class="parameter"><code>length</code></em> bytes (less if the end of file is
1748 reached first). If <em class="parameter"><code>offset</code></em> is negative, it is
1749 relative to the end of the file. If <em class="parameter"><code>offset</code></em>
1750 and <em class="parameter"><code>length</code></em> are omitted, the entire file is
1751 returned. The bytes read from the file are interpreted as a string in
1752 the database's encoding; an error is thrown if they are not valid in
1756 This function is restricted to superusers by default, but other users
1757 can be granted EXECUTE to run the function.
1758 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1759 <a id="id-1.5.8.34.11.6.2.2.11.1.1.1" class="indexterm"></a>
1760 <code class="function">pg_read_binary_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>offset</code></em> <code class="type">bigint</code>, <em class="parameter"><code>length</code></em> <code class="type">bigint</code> </span>] [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
1761 → <code class="returnvalue">bytea</code>
1764 Returns all or part of a file. This function is identical to
1765 <code class="function">pg_read_file</code> except that it can read arbitrary
1766 binary data, returning the result as <code class="type">bytea</code>
1767 not <code class="type">text</code>; accordingly, no encoding checks are performed.
1770 This function is restricted to superusers by default, but other users
1771 can be granted EXECUTE to run the function.
1774 In combination with the <code class="function">convert_from</code> function,
1775 this function can be used to read a text file in a specified encoding
1776 and convert to the database's encoding:
1777 </p><pre class="programlisting">
1778 SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
1780 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1781 <a id="id-1.5.8.34.11.6.2.2.12.1.1.1" class="indexterm"></a>
1782 <code class="function">pg_stat_file</code> ( <em class="parameter"><code>filename</code></em> <code class="type">text</code> [<span class="optional">, <em class="parameter"><code>missing_ok</code></em> <code class="type">boolean</code> </span>] )
1783 → <code class="returnvalue">record</code>
1784 ( <em class="parameter"><code>size</code></em> <code class="type">bigint</code>,
1785 <em class="parameter"><code>access</code></em> <code class="type">timestamp with time zone</code>,
1786 <em class="parameter"><code>modification</code></em> <code class="type">timestamp with time zone</code>,
1787 <em class="parameter"><code>change</code></em> <code class="type">timestamp with time zone</code>,
1788 <em class="parameter"><code>creation</code></em> <code class="type">timestamp with time zone</code>,
1789 <em class="parameter"><code>isdir</code></em> <code class="type">boolean</code> )
1792 Returns a record containing the file's size, last access time stamp,
1793 last modification time stamp, last file status change time stamp (Unix
1794 platforms only), file creation time stamp (Windows only), and a flag
1795 indicating if it is a directory.
1798 This function is restricted to superusers by default, but other users
1799 can be granted EXECUTE to run the function.
1800 </p></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="FUNCTIONS-ADVISORY-LOCKS"><div class="titlepage"><div><div><h3 class="title">9.28.10. Advisory Lock Functions <a href="#FUNCTIONS-ADVISORY-LOCKS" class="id_link">#</a></h3></div></div></div><p>
1801 The functions shown in <a class="xref" href="functions-admin.html#FUNCTIONS-ADVISORY-LOCKS-TABLE" title="Table 9.109. Advisory Lock Functions">Table 9.109</a>
1802 manage advisory locks. For details about proper use of these functions,
1803 see <a class="xref" href="explicit-locking.html#ADVISORY-LOCKS" title="13.3.5. Advisory Locks">Section 13.3.5</a>.
1805 All these functions are intended to be used to lock application-defined
1806 resources, which can be identified either by a single 64-bit key value or
1807 two 32-bit key values (note that these two key spaces do not overlap).
1808 If another session already holds a conflicting lock on the same resource
1809 identifier, the functions will either wait until the resource becomes
1810 available, or return a <code class="literal">false</code> result, as appropriate for
1812 Locks can be either shared or exclusive: a shared lock does not conflict
1813 with other shared locks on the same resource, only with exclusive locks.
1814 Locks can be taken at session level (so that they are held until released
1815 or the session ends) or at transaction level (so that they are held until
1816 the current transaction ends; there is no provision for manual release).
1817 Multiple session-level lock requests stack, so that if the same resource
1818 identifier is locked three times there must then be three unlock requests
1819 to release the resource in advance of session end.
1820 </p><div class="table" id="FUNCTIONS-ADVISORY-LOCKS-TABLE"><p class="title"><strong>Table 9.109. Advisory Lock Functions</strong></p><div class="table-contents"><table class="table" summary="Advisory Lock Functions" border="1"><colgroup><col /></colgroup><thead><tr><th class="func_table_entry"><p class="func_signature">
1825 </p></th></tr></thead><tbody><tr><td class="func_table_entry"><p class="func_signature">
1826 <a id="id-1.5.8.34.12.4.2.2.1.1.1.1" class="indexterm"></a>
1827 <code class="function">pg_advisory_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1828 → <code class="returnvalue">void</code>
1830 <p class="func_signature">
1831 <code class="function">pg_advisory_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1832 → <code class="returnvalue">void</code>
1835 Obtains an exclusive session-level advisory lock, waiting if necessary.
1836 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1837 <a id="id-1.5.8.34.12.4.2.2.2.1.1.1" class="indexterm"></a>
1838 <code class="function">pg_advisory_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1839 → <code class="returnvalue">void</code>
1841 <p class="func_signature">
1842 <code class="function">pg_advisory_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1843 → <code class="returnvalue">void</code>
1846 Obtains a shared session-level advisory lock, waiting if necessary.
1847 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1848 <a id="id-1.5.8.34.12.4.2.2.3.1.1.1" class="indexterm"></a>
1849 <code class="function">pg_advisory_unlock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1850 → <code class="returnvalue">boolean</code>
1852 <p class="func_signature">
1853 <code class="function">pg_advisory_unlock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1854 → <code class="returnvalue">boolean</code>
1857 Releases a previously-acquired exclusive session-level advisory lock.
1858 Returns <code class="literal">true</code> if the lock is successfully released.
1859 If the lock was not held, <code class="literal">false</code> is returned, and in
1860 addition, an SQL warning will be reported by the server.
1861 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1862 <a id="id-1.5.8.34.12.4.2.2.4.1.1.1" class="indexterm"></a>
1863 <code class="function">pg_advisory_unlock_all</code> ()
1864 → <code class="returnvalue">void</code>
1867 Releases all session-level advisory locks held by the current session.
1868 (This function is implicitly invoked at session end, even if the
1869 client disconnects ungracefully.)
1870 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1871 <a id="id-1.5.8.34.12.4.2.2.5.1.1.1" class="indexterm"></a>
1872 <code class="function">pg_advisory_unlock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1873 → <code class="returnvalue">boolean</code>
1875 <p class="func_signature">
1876 <code class="function">pg_advisory_unlock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1877 → <code class="returnvalue">boolean</code>
1880 Releases a previously-acquired shared session-level advisory lock.
1881 Returns <code class="literal">true</code> if the lock is successfully released.
1882 If the lock was not held, <code class="literal">false</code> is returned, and in
1883 addition, an SQL warning will be reported by the server.
1884 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1885 <a id="id-1.5.8.34.12.4.2.2.6.1.1.1" class="indexterm"></a>
1886 <code class="function">pg_advisory_xact_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1887 → <code class="returnvalue">void</code>
1889 <p class="func_signature">
1890 <code class="function">pg_advisory_xact_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1891 → <code class="returnvalue">void</code>
1894 Obtains an exclusive transaction-level advisory lock, waiting if
1896 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1897 <a id="id-1.5.8.34.12.4.2.2.7.1.1.1" class="indexterm"></a>
1898 <code class="function">pg_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1899 → <code class="returnvalue">void</code>
1901 <p class="func_signature">
1902 <code class="function">pg_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1903 → <code class="returnvalue">void</code>
1906 Obtains a shared transaction-level advisory lock, waiting if
1908 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1909 <a id="id-1.5.8.34.12.4.2.2.8.1.1.1" class="indexterm"></a>
1910 <code class="function">pg_try_advisory_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1911 → <code class="returnvalue">boolean</code>
1913 <p class="func_signature">
1914 <code class="function">pg_try_advisory_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1915 → <code class="returnvalue">boolean</code>
1918 Obtains an exclusive session-level advisory lock if available.
1919 This will either obtain the lock immediately and
1920 return <code class="literal">true</code>, or return <code class="literal">false</code>
1921 without waiting if the lock cannot be acquired immediately.
1922 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1923 <a id="id-1.5.8.34.12.4.2.2.9.1.1.1" class="indexterm"></a>
1924 <code class="function">pg_try_advisory_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1925 → <code class="returnvalue">boolean</code>
1927 <p class="func_signature">
1928 <code class="function">pg_try_advisory_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1929 → <code class="returnvalue">boolean</code>
1932 Obtains a shared session-level advisory lock if available.
1933 This will either obtain the lock immediately and
1934 return <code class="literal">true</code>, or return <code class="literal">false</code>
1935 without waiting if the lock cannot be acquired immediately.
1936 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1937 <a id="id-1.5.8.34.12.4.2.2.10.1.1.1" class="indexterm"></a>
1938 <code class="function">pg_try_advisory_xact_lock</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1939 → <code class="returnvalue">boolean</code>
1941 <p class="func_signature">
1942 <code class="function">pg_try_advisory_xact_lock</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1943 → <code class="returnvalue">boolean</code>
1946 Obtains an exclusive transaction-level advisory lock if available.
1947 This will either obtain the lock immediately and
1948 return <code class="literal">true</code>, or return <code class="literal">false</code>
1949 without waiting if the lock cannot be acquired immediately.
1950 </p></td></tr><tr><td class="func_table_entry"><p class="func_signature">
1951 <a id="id-1.5.8.34.12.4.2.2.11.1.1.1" class="indexterm"></a>
1952 <code class="function">pg_try_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key</code></em> <code class="type">bigint</code> )
1953 → <code class="returnvalue">boolean</code>
1955 <p class="func_signature">
1956 <code class="function">pg_try_advisory_xact_lock_shared</code> ( <em class="parameter"><code>key1</code></em> <code class="type">integer</code>, <em class="parameter"><code>key2</code></em> <code class="type">integer</code> )
1957 → <code class="returnvalue">boolean</code>
1960 Obtains a shared transaction-level advisory lock if available.
1961 This will either obtain the lock immediately and
1962 return <code class="literal">true</code>, or return <code class="literal">false</code>
1963 without waiting if the lock cannot be acquired immediately.
1964 </p></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="functions-info.html" title="9.27. System Information Functions and Operators">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="functions.html" title="Chapter 9. Functions and Operators">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="functions-trigger.html" title="9.29. Trigger Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">9.27. System Information Functions and Operators </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 9.29. Trigger Functions</td></tr></table></div></body></html>
begriffs.com / projects / ai-pg / blob