codekingpro/portable-devtools
115k
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>psql</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="app-pgverifybackup.html" title="pg_verifybackup" /><link rel="next" href="app-reindexdb.html" title="reindexdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">psql</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-pgverifybackup.html" title="pg_verifybackup">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-reindexdb.html" title="reindexdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-PSQL"><div class="titlepage"></div><a id="id-1.9.4.20.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">psql</span></span></h2><p><span class="application">psql</span> — 3 <span class="productname">PostgreSQL</span> interactive terminal4 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.20.4.1"><code class="command">psql</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>5 [<em class="replaceable"><code>username</code></em>]]</p></div></div><div class="refsect1" id="id-1.9.4.20.5"><h2>Description</h2><p>6 <span class="application">psql</span> is a terminal-based front-end to7 <span class="productname">PostgreSQL</span>. It enables you to type in8 queries interactively, issue them to9 <span class="productname">PostgreSQL</span>, and see the query results.10 Alternatively, input can be from a file or from command line11 arguments. In addition, <span class="application">psql</span> provides a12 number of meta-commands and various shell-like features to13 facilitate writing scripts and automating a wide variety of tasks.14 </p></div><div class="refsect1" id="R1-APP-PSQL-3"><h2>Options</h2><div class="variablelist"><dl class="variablelist"><dt id="APP-PSQL-OPTION-ECHO-ALL"><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--echo-all</code></span> <a href="#APP-PSQL-OPTION-ECHO-ALL" class="id_link">#</a></dt><dd><p>15 Print all nonempty input lines to standard output as they are read.16 (This does not apply to lines read interactively.) This is17 equivalent to setting the variable <code class="varname">ECHO</code> to18 <code class="literal">all</code>.19 </p></dd><dt id="APP-PSQL-OPTION-NO-ALIGN"><span class="term"><code class="option">-A</code><br /></span><span class="term"><code class="option">--no-align</code></span> <a href="#APP-PSQL-OPTION-NO-ALIGN" class="id_link">#</a></dt><dd><p>20 Switches to unaligned output mode. (The default output mode is21 <code class="literal">aligned</code>.) This is equivalent to22 <code class="command">\pset format unaligned</code>.23 </p></dd><dt id="APP-PSQL-OPTION-ECHO-ERRORS"><span class="term"><code class="option">-b</code><br /></span><span class="term"><code class="option">--echo-errors</code></span> <a href="#APP-PSQL-OPTION-ECHO-ERRORS" class="id_link">#</a></dt><dd><p>24 Print failed SQL commands to standard error output. This is25 equivalent to setting the variable <code class="varname">ECHO</code> to26 <code class="literal">errors</code>.27 </p></dd><dt id="APP-PSQL-OPTION-COMMAND"><span class="term"><code class="option">-c <em class="replaceable"><code>command</code></em></code><br /></span><span class="term"><code class="option">--command=<em class="replaceable"><code>command</code></em></code></span> <a href="#APP-PSQL-OPTION-COMMAND" class="id_link">#</a></dt><dd><p>28 Specifies that <span class="application">psql</span> is to execute the given29 command string, <em class="replaceable"><code>command</code></em>.30 This option can be repeated and combined in any order with31 the <code class="option">-f</code> option. When either <code class="option">-c</code>32 or <code class="option">-f</code> is specified, <span class="application">psql</span>33 does not read commands from standard input; instead it terminates34 after processing all the <code class="option">-c</code> and <code class="option">-f</code>35 options in sequence.36 </p><p>37 <em class="replaceable"><code>command</code></em> must be either38 a command string that is completely parsable by the server (i.e.,39 it contains no <span class="application">psql</span>-specific features),40 or a single backslash command. Thus you cannot mix41 <acronym class="acronym">SQL</acronym> and <span class="application">psql</span>42 meta-commands within a <code class="option">-c</code> option. To achieve that,43 you could use repeated <code class="option">-c</code> options or pipe the string44 into <span class="application">psql</span>, for example:45</p><pre class="programlisting">46psql -c '\x' -c 'SELECT * FROM foo;'47</pre><p>48 or49</p><pre class="programlisting">50echo '\x \\ SELECT * FROM foo;' | psql51</pre><p>52 (<code class="literal">\\</code> is the separator meta-command.)53 </p><p>54 Each <acronym class="acronym">SQL</acronym> command string passed55 to <code class="option">-c</code> is sent to the server as a single request.56 Because of this, the server executes it as a single transaction even57 if the string contains multiple <acronym class="acronym">SQL</acronym> commands,58 unless there are explicit <code class="command">BEGIN</code>/<code class="command">COMMIT</code>59 commands included in the string to divide it into multiple60 transactions. (See <a class="xref" href="protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT" title="55.2.2.1. Multiple Statements in a Simple Query">Section 55.2.2.1</a>61 for more details about how the server handles multi-query strings.)62 </p><p>63 If having several commands executed in one transaction is not desired,64 use repeated <code class="option">-c</code> commands or feed multiple commands to65 <span class="application">psql</span>'s standard input,66 either using <span class="application">echo</span> as illustrated above, or67 via a shell here-document, for example:68</p><pre class="programlisting">69psql <<EOF70\x71SELECT * FROM foo;72EOF73</pre></dd><dt id="APP-PSQL-OPTION-CSV"><span class="term"><code class="option">--csv</code></span> <a href="#APP-PSQL-OPTION-CSV" class="id_link">#</a></dt><dd><p>74 Switches to <acronym class="acronym">CSV</acronym> (Comma-Separated Values) output75 mode. This is equivalent to <code class="command">\pset format csv</code>.76 </p></dd><dt id="APP-PSQL-OPTION-DBNAME"><span class="term"><code class="option">-d <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">--dbname=<em class="replaceable"><code>dbname</code></em></code></span> <a href="#APP-PSQL-OPTION-DBNAME" class="id_link">#</a></dt><dd><p>77 Specifies the name of the database to connect to. This is78 equivalent to specifying <em class="replaceable"><code>dbname</code></em> as the first non-option79 argument on the command line. The <em class="replaceable"><code>dbname</code></em>80 can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection string</a>.81 If so, connection string parameters will override any conflicting82 command line options.83 </p></dd><dt id="APP-PSQL-OPTION-ECHO-QUERIES"><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo-queries</code></span> <a href="#APP-PSQL-OPTION-ECHO-QUERIES" class="id_link">#</a></dt><dd><p>84 Copy all SQL commands sent to the server to standard output as well.85 This is equivalent86 to setting the variable <code class="varname">ECHO</code> to87 <code class="literal">queries</code>.88 </p></dd><dt id="APP-PSQL-OPTION-ECHO-HIDDEN"><span class="term"><code class="option">-E</code><br /></span><span class="term"><code class="option">--echo-hidden</code></span> <a href="#APP-PSQL-OPTION-ECHO-HIDDEN" class="id_link">#</a></dt><dd><p>89 Echo the actual queries generated by <code class="command">\d</code> and other backslash90 commands. You can use this to study <span class="application">psql</span>'s91 internal operations. This is equivalent to92 setting the variable <code class="varname">ECHO_HIDDEN</code> to <code class="literal">on</code>.93 </p></dd><dt id="APP-PSQL-OPTION-FILE"><span class="term"><code class="option">-f <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--file=<em class="replaceable"><code>filename</code></em></code></span> <a href="#APP-PSQL-OPTION-FILE" class="id_link">#</a></dt><dd><p>94 Read commands from the95 file <em class="replaceable"><code>filename</code></em>,96 rather than standard input.97 This option can be repeated and combined in any order with98 the <code class="option">-c</code> option. When either <code class="option">-c</code>99 or <code class="option">-f</code> is specified, <span class="application">psql</span>100 does not read commands from standard input; instead it terminates101 after processing all the <code class="option">-c</code> and <code class="option">-f</code>102 options in sequence.103 Except for that, this option is largely equivalent to the104 meta-command <code class="command">\i</code>.105 </p><p>106 If <em class="replaceable"><code>filename</code></em> is <code class="literal">-</code>107 (hyphen), then standard input is read until an EOF indication108 or <code class="command">\q</code> meta-command. This can be used to intersperse109 interactive input with input from files. Note however that Readline110 is not used in this case (much as if <code class="option">-n</code> had been111 specified).112 </p><p>113 Using this option is subtly different from writing <code class="literal">psql114 < <em class="replaceable"><code>filename</code></em></code>. In general,115 both will do what you expect, but using <code class="literal">-f</code>116 enables some nice features such as error messages with line117 numbers. There is also a slight chance that using this option will118 reduce the start-up overhead. On the other hand, the variant using119 the shell's input redirection is (in theory) guaranteed to yield120 exactly the same output you would have received had you entered121 everything by hand.122 </p></dd><dt id="APP-PSQL-OPTION-FIELD-SEPARATOR"><span class="term"><code class="option">-F <em class="replaceable"><code>separator</code></em></code><br /></span><span class="term"><code class="option">--field-separator=<em class="replaceable"><code>separator</code></em></code></span> <a href="#APP-PSQL-OPTION-FIELD-SEPARATOR" class="id_link">#</a></dt><dd><p>123 Use <em class="replaceable"><code>separator</code></em> as the124 field separator for unaligned output. This is equivalent to125 <code class="command">\pset fieldsep</code> or <code class="command">\f</code>.126 </p></dd><dt id="APP-PSQL-OPTION-FIELD-HOST"><span class="term"><code class="option">-h <em class="replaceable"><code>hostname</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>hostname</code></em></code></span> <a href="#APP-PSQL-OPTION-FIELD-HOST" class="id_link">#</a></dt><dd><p>127 Specifies the host name of the machine on which the128 server is running. If the value begins129 with a slash, it is used as the directory for the Unix-domain130 socket.131 </p></dd><dt id="APP-PSQL-OPTION-HTML"><span class="term"><code class="option">-H</code><br /></span><span class="term"><code class="option">--html</code></span> <a href="#APP-PSQL-OPTION-HTML" class="id_link">#</a></dt><dd><p>132 Switches to <acronym class="acronym">HTML</acronym> output mode. This is133 equivalent to <code class="command">\pset format html</code> or the134 <code class="command">\H</code> command.135 </p></dd><dt id="APP-PSQL-OPTION-LIST"><span class="term"><code class="option">-l</code><br /></span><span class="term"><code class="option">--list</code></span> <a href="#APP-PSQL-OPTION-LIST" class="id_link">#</a></dt><dd><p>136 List all available databases, then exit. Other non-connection137 options are ignored. This is similar to the meta-command138 <code class="command">\list</code>.139 </p><p>140 When this option is used, <span class="application">psql</span> will connect141 to the database <code class="literal">postgres</code>, unless a different database142 is named on the command line (option <code class="option">-d</code> or non-option143 argument, possibly via a service entry, but not via an environment144 variable).145 </p></dd><dt id="APP-PSQL-OPTION-LOG-FILE"><span class="term"><code class="option">-L <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--log-file=<em class="replaceable"><code>filename</code></em></code></span> <a href="#APP-PSQL-OPTION-LOG-FILE" class="id_link">#</a></dt><dd><p>146 Write all query output into file <em class="replaceable"><code>filename</code></em>, in addition to the147 normal output destination.148 </p></dd><dt id="APP-PSQL-OPTION-NO-READLINE"><span class="term"><code class="option">-n</code><br /></span><span class="term"><code class="option">--no-readline</code></span> <a href="#APP-PSQL-OPTION-NO-READLINE" class="id_link">#</a></dt><dd><p>149 Do not use <span class="application">Readline</span> for line editing and150 do not use the command history (see151 <a class="xref" href="app-psql.html#APP-PSQL-READLINE" title="Command-Line Editing">the section called “Command-Line Editing”</a> below).152 </p></dd><dt id="APP-PSQL-OPTION-OUTPUT"><span class="term"><code class="option">-o <em class="replaceable"><code>filename</code></em></code><br /></span><span class="term"><code class="option">--output=<em class="replaceable"><code>filename</code></em></code></span> <a href="#APP-PSQL-OPTION-OUTPUT" class="id_link">#</a></dt><dd><p>153 Put all query output into file <em class="replaceable"><code>filename</code></em>. This is equivalent to154 the command <code class="command">\o</code>.155 </p></dd><dt id="APP-PSQL-OPTION-PORT"><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span> <a href="#APP-PSQL-OPTION-PORT" class="id_link">#</a></dt><dd><p>156 Specifies the TCP port or the local Unix-domain157 socket file extension on which the server is listening for158 connections. Defaults to the value of the <code class="envar">PGPORT</code>159 environment variable or, if not set, to the port specified at160 compile time, usually 5432.161 </p></dd><dt id="APP-PSQL-OPTION-PSET"><span class="term"><code class="option">-P <em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--pset=<em class="replaceable"><code>assignment</code></em></code></span> <a href="#APP-PSQL-OPTION-PSET" class="id_link">#</a></dt><dd><p>162 Specifies printing options, in the style of163 <code class="command">\pset</code>. Note that here you164 have to separate name and value with an equal sign instead of a165 space. For example, to set the output format to <span class="application">LaTeX</span>, you could write166 <code class="literal">-P format=latex</code>.167 </p></dd><dt id="APP-PSQL-OPTION-QUIET"><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span> <a href="#APP-PSQL-OPTION-QUIET" class="id_link">#</a></dt><dd><p>168 Specifies that <span class="application">psql</span> should do its work169 quietly. By default, it prints welcome messages and various170 informational output. If this option is used, none of this171 happens. This is useful with the <code class="option">-c</code> option.172 This is equivalent to setting the variable <code class="varname">QUIET</code>173 to <code class="literal">on</code>.174 </p></dd><dt id="APP-PSQL-OPTION-RECORD-SEPARATOR"><span class="term"><code class="option">-R <em class="replaceable"><code>separator</code></em></code><br /></span><span class="term"><code class="option">--record-separator=<em class="replaceable"><code>separator</code></em></code></span> <a href="#APP-PSQL-OPTION-RECORD-SEPARATOR" class="id_link">#</a></dt><dd><p>175 Use <em class="replaceable"><code>separator</code></em> as the176 record separator for unaligned output. This is equivalent to177 <code class="command">\pset recordsep</code>.178 </p></dd><dt id="APP-PSQL-OPTION-SINGLE-STEP"><span class="term"><code class="option">-s</code><br /></span><span class="term"><code class="option">--single-step</code></span> <a href="#APP-PSQL-OPTION-SINGLE-STEP" class="id_link">#</a></dt><dd><p>179 Run in single-step mode. That means the user is prompted before180 each command is sent to the server, with the option to cancel181 execution as well. Use this to debug scripts.182 </p></dd><dt id="APP-PSQL-OPTION-SINGLE-LINE"><span class="term"><code class="option">-S</code><br /></span><span class="term"><code class="option">--single-line</code></span> <a href="#APP-PSQL-OPTION-SINGLE-LINE" class="id_link">#</a></dt><dd><p>183 Runs in single-line mode where a newline terminates an SQL command, as a184 semicolon does.185 </p><div class="note"><h3 class="title">Note</h3><p>186 This mode is provided for those who insist on it, but you are not187 necessarily encouraged to use it. In particular, if you mix188 <acronym class="acronym">SQL</acronym> and meta-commands on a line the order of189 execution might not always be clear to the inexperienced user.190 </p></div></dd><dt id="APP-PSQL-OPTION-TUPLES-ONLY"><span class="term"><code class="option">-t</code><br /></span><span class="term"><code class="option">--tuples-only</code></span> <a href="#APP-PSQL-OPTION-TUPLES-ONLY" class="id_link">#</a></dt><dd><p>191 Turn off printing of column names and result row count footers,192 etc. This is equivalent to <code class="command">\t</code> or193 <code class="command">\pset tuples_only</code>.194 </p></dd><dt id="APP-PSQL-OPTION-TABLE-ATTR"><span class="term"><code class="option">-T <em class="replaceable"><code>table_options</code></em></code><br /></span><span class="term"><code class="option">--table-attr=<em class="replaceable"><code>table_options</code></em></code></span> <a href="#APP-PSQL-OPTION-TABLE-ATTR" class="id_link">#</a></dt><dd><p>195 Specifies options to be placed within the196 <acronym class="acronym">HTML</acronym> <code class="sgmltag-element">table</code> tag. See197 <code class="command">\pset tableattr</code> for details.198 </p></dd><dt id="APP-PSQL-OPTION-USERNAME"><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span> <a href="#APP-PSQL-OPTION-USERNAME" class="id_link">#</a></dt><dd><p>199 Connect to the database as the user <em class="replaceable"><code>username</code></em> instead of the default.200 (You must have permission to do so, of course.)201 </p></dd><dt id="APP-PSQL-OPTION-VARIABLE"><span class="term"><code class="option">-v <em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--set=<em class="replaceable"><code>assignment</code></em></code><br /></span><span class="term"><code class="option">--variable=<em class="replaceable"><code>assignment</code></em></code></span> <a href="#APP-PSQL-OPTION-VARIABLE" class="id_link">#</a></dt><dd><p>202 Perform a variable assignment, like the <code class="command">\set</code>203 meta-command. Note that you must separate name and value, if204 any, by an equal sign on the command line. To unset a variable,205 leave off the equal sign. To set a variable with an empty value,206 use the equal sign but leave off the value. These assignments are207 done during command line processing, so variables that reflect208 connection state will get overwritten later.209 </p></dd><dt id="APP-PSQL-OPTION-VERSION"><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span> <a href="#APP-PSQL-OPTION-VERSION" class="id_link">#</a></dt><dd><p>210 Print the <span class="application">psql</span> version and exit.211 </p></dd><dt id="APP-PSQL-OPTION-NO-PASSWORD"><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span> <a href="#APP-PSQL-OPTION-NO-PASSWORD" class="id_link">#</a></dt><dd><p>212 Never issue a password prompt. If the server requires password213 authentication and a password is not available from other sources214 such as a <code class="filename">.pgpass</code> file, the connection215 attempt will fail. This option can be useful in batch jobs and216 scripts where no user is present to enter a password.217 </p><p>218 Note that this option will remain set for the entire session,219 and so it affects uses of the meta-command220 <code class="command">\connect</code> as well as the initial connection attempt.221 </p></dd><dt id="APP-PSQL-OPTION-PASSWORD"><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span> <a href="#APP-PSQL-OPTION-PASSWORD" class="id_link">#</a></dt><dd><p>222 Force <span class="application">psql</span> to prompt for a223 password before connecting to a database, even if the password will224 not be used.225 </p><p>226 If the server requires password authentication and a password is not227 available from other sources such as a <code class="filename">.pgpass</code>228 file, <span class="application">psql</span> will prompt for a229 password in any case. However, <span class="application">psql</span>230 will waste a connection attempt finding out that the server wants a231 password. In some cases it is worth typing <code class="option">-W</code> to avoid232 the extra connection attempt.233 </p><p>234 Note that this option will remain set for the entire session,235 and so it affects uses of the meta-command236 <code class="command">\connect</code> as well as the initial connection attempt.237 </p></dd><dt id="APP-PSQL-OPTION-EXPANDED"><span class="term"><code class="option">-x</code><br /></span><span class="term"><code class="option">--expanded</code></span> <a href="#APP-PSQL-OPTION-EXPANDED" class="id_link">#</a></dt><dd><p>238 Turn on the expanded table formatting mode. This is equivalent to239 <code class="command">\x</code> or <code class="command">\pset expanded</code>.240 </p></dd><dt id="APP-PSQL-OPTION-NO-PSQLRC"><span class="term"><code class="option">-X</code><br /></span><span class="term"><code class="option">--no-psqlrc</code></span> <a href="#APP-PSQL-OPTION-NO-PSQLRC" class="id_link">#</a></dt><dd><p>241 Do not read the start-up file (neither the system-wide242 <code class="filename">psqlrc</code> file nor the user's243 <code class="filename">~/.psqlrc</code> file).244 </p></dd><dt id="APP-PSQL-OPTION-FIELD-SEPARATOR-ZERO"><span class="term"><code class="option">-z</code><br /></span><span class="term"><code class="option">--field-separator-zero</code></span> <a href="#APP-PSQL-OPTION-FIELD-SEPARATOR-ZERO" class="id_link">#</a></dt><dd><p>245 Set the field separator for unaligned output to a zero byte. This is246 equivalent to <code class="command">\pset fieldsep_zero</code>.247 </p></dd><dt id="APP-PSQL-OPTION-RECORD-SEPARATOR-ZERO"><span class="term"><code class="option">-0</code><br /></span><span class="term"><code class="option">--record-separator-zero</code></span> <a href="#APP-PSQL-OPTION-RECORD-SEPARATOR-ZERO" class="id_link">#</a></dt><dd><p>248 Set the record separator for unaligned output to a zero byte. This is249 useful for interfacing, for example, with <code class="literal">xargs -0</code>.250 This is equivalent to <code class="command">\pset recordsep_zero</code>.251 </p></dd><dt id="APP-PSQL-OPTION-SINGLE-TRANSACTION"><span class="term"><code class="option">-1</code><br /></span><span class="term"><code class="option">--single-transaction</code></span> <a href="#APP-PSQL-OPTION-SINGLE-TRANSACTION" class="id_link">#</a></dt><dd><p>252 This option can only be used in combination with one or more253 <code class="option">-c</code> and/or <code class="option">-f</code> options. It causes254 <span class="application">psql</span> to issue a <code class="command">BEGIN</code> command255 before the first such option and a <code class="command">COMMIT</code> command after256 the last one, thereby wrapping all the commands into a single257 transaction. If any of the commands fails and the variable258 <code class="varname">ON_ERROR_STOP</code> was set, a259 <code class="command">ROLLBACK</code> command is sent instead. This ensures that260 either all the commands complete successfully, or no changes are261 applied.262 </p><p>263 If the commands themselves264 contain <code class="command">BEGIN</code>, <code class="command">COMMIT</code>,265 or <code class="command">ROLLBACK</code>, this option will not have the desired266 effects. Also, if an individual command cannot be executed inside a267 transaction block, specifying this option will cause the whole268 transaction to fail.269 </p></dd><dt id="APP-PSQL-OPTION-HELP"><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help[=<em class="replaceable"><code>topic</code></em>]</code></span> <a href="#APP-PSQL-OPTION-HELP" class="id_link">#</a></dt><dd><p>270 Show help about <span class="application">psql</span> and exit. The optional271 <em class="replaceable"><code>topic</code></em> parameter (defaulting272 to <code class="literal">options</code>) selects which part of <span class="application">psql</span> is273 explained: <code class="literal">commands</code> describes <span class="application">psql</span>'s274 backslash commands; <code class="literal">options</code> describes the command-line275 options that can be passed to <span class="application">psql</span>;276 and <code class="literal">variables</code> shows help about <span class="application">psql</span> configuration277 variables.278 </p></dd></dl></div></div><div class="refsect1" id="id-1.9.4.20.7"><h2>Exit Status</h2><p>279 <span class="application">psql</span> returns 0 to the shell if it280 finished normally, 1 if a fatal error of its own occurs (e.g., out of memory,281 file not found), 2 if the connection to the server went bad282 and the session was not interactive, and 3 if an error occurred in a283 script and the variable <code class="varname">ON_ERROR_STOP</code> was set.284 </p></div><div class="refsect1" id="id-1.9.4.20.8"><h2>Usage</h2><div class="refsect2" id="R2-APP-PSQL-CONNECTING"><h3>Connecting to a Database</h3><p>285 <span class="application">psql</span> is a regular286 <span class="productname">PostgreSQL</span> client application. In order287 to connect to a database you need to know the name of your target288 database, the host name and port number of the server, and what289 database user name you want to connect as. <span class="application">psql</span>290 can be told about those parameters via command line options, namely291 <code class="option">-d</code>, <code class="option">-h</code>, <code class="option">-p</code>, and292 <code class="option">-U</code> respectively. If an argument is found that does293 not belong to any option it will be interpreted as the database name294 (or the database user name, if the database name is already given). Not all295 of these options are required; there are useful defaults. If you omit the host296 name, <span class="application">psql</span> will connect via a Unix-domain socket297 to a server on the local host, or via TCP/IP to <code class="literal">localhost</code> on298 Windows. The default port number is299 determined at compile time.300 Since the database server uses the same default, you will not have301 to specify the port in most cases. The default database user name is your302 operating-system user name. Once the database user name is determined, it303 is used as the default database name.304 Note that you cannot305 just connect to any database under any database user name. Your database306 administrator should have informed you about your access rights.307 </p><p>308 When the defaults aren't quite right, you can save yourself309 some typing by setting the environment variables310 <code class="envar">PGDATABASE</code>, <code class="envar">PGHOST</code>,311 <code class="envar">PGPORT</code> and/or <code class="envar">PGUSER</code> to appropriate312 values. (For additional environment variables, see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>.) It is also convenient to have a313 <code class="filename">~/.pgpass</code> file to avoid regularly having to type in314 passwords. See <a class="xref" href="libpq-pgpass.html" title="34.16. The Password File">Section 34.16</a> for more information.315 </p><p>316 An alternative way to specify connection parameters is in a317 <em class="parameter"><code>conninfo</code></em> string or318 a <acronym class="acronym">URI</acronym>, which is used instead of a database319 name. This mechanism give you very wide control over the320 connection. For example:321</p><pre class="programlisting">322$ <strong class="userinput"><code>psql "service=myservice sslmode=require"</code></strong>323$ <strong class="userinput"><code>psql postgresql://dbmaster:5433/mydb?sslmode=require</code></strong>324</pre><p>325 This way you can also use <acronym class="acronym">LDAP</acronym> for connection326 parameter lookup as described in <a class="xref" href="libpq-ldap.html" title="34.18. LDAP Lookup of Connection Parameters">Section 34.18</a>.327 See <a class="xref" href="libpq-connect.html#LIBPQ-PARAMKEYWORDS" title="34.1.2. Parameter Key Words">Section 34.1.2</a> for more information on all the328 available connection options.329 </p><p>330 If the connection could not be made for any reason (e.g., insufficient331 privileges, server is not running on the targeted host, etc.),332 <span class="application">psql</span> will return an error and terminate.333 </p><p>334 If both standard input and standard output are a335 terminal, then <span class="application">psql</span> sets the client336 encoding to <span class="quote">“<span class="quote">auto</span>”</span>, which will detect the337 appropriate client encoding from the locale settings338 (<code class="envar">LC_CTYPE</code> environment variable on Unix systems).339 If this doesn't work out as expected, the client encoding can be340 overridden using the environment341 variable <code class="envar">PGCLIENTENCODING</code>.342 </p></div><div class="refsect2" id="R2-APP-PSQL-4"><h3>Entering SQL Commands</h3><p>343 In normal operation, <span class="application">psql</span> provides a344 prompt with the name of the database to which345 <span class="application">psql</span> is currently connected, followed by346 the string <code class="literal">=></code>. For example:347</p><pre class="programlisting">348$ <strong class="userinput"><code>psql testdb</code></strong>349psql (16.3)350Type "help" for help.351 352testdb=>353</pre><p>354 </p><p>355 At the prompt, the user can type in <acronym class="acronym">SQL</acronym> commands.356 Ordinarily, input lines are sent to the server when a357 command-terminating semicolon is reached. An end of line does not358 terminate a command. Thus commands can be spread over several lines for359 clarity. If the command was sent and executed without error, the results360 of the command are displayed on the screen.361 </p><p>362 If untrusted users have access to a database that has not adopted a363 <a class="link" href="ddl-schemas.html#DDL-SCHEMAS-PATTERNS" title="5.9.6. Usage Patterns">secure schema usage pattern</a>,364 begin your session by removing publicly-writable schemas365 from <code class="varname">search_path</code>. One can366 add <code class="literal">options=-csearch_path=</code> to the connection string or367 issue <code class="literal">SELECT pg_catalog.set_config('search_path', '',368 false)</code> before other SQL commands. This consideration is not369 specific to <span class="application">psql</span>; it applies to every interface370 for executing arbitrary SQL commands.371 </p><p>372 Whenever a command is executed, <span class="application">psql</span> also polls373 for asynchronous notification events generated by374 <a class="link" href="sql-listen.html" title="LISTEN"><code class="command">LISTEN</code></a> and375 <a class="link" href="sql-notify.html" title="NOTIFY"><code class="command">NOTIFY</code></a>.376 </p><p>377 While C-style block comments are passed to the server for378 processing and removal, SQL-standard comments are removed by379 <span class="application">psql</span>.380 </p></div><div class="refsect2" id="APP-PSQL-META-COMMANDS"><h3>Meta-Commands</h3><p>381 Anything you enter in <span class="application">psql</span> that begins382 with an unquoted backslash is a <span class="application">psql</span>383 meta-command that is processed by <span class="application">psql</span>384 itself. These commands make385 <span class="application">psql</span> more useful for administration or386 scripting. Meta-commands are often called slash or backslash commands.387 </p><p>388 The format of a <span class="application">psql</span> command is the backslash,389 followed immediately by a command verb, then any arguments. The arguments390 are separated from the command verb and each other by any number of391 whitespace characters.392 </p><p>393 To include whitespace in an argument you can quote it with394 single quotes. To include a single quote in an argument,395 write two single quotes within single-quoted text.396 Anything contained in single quotes is397 furthermore subject to C-like substitutions for398 <code class="literal">\n</code> (new line), <code class="literal">\t</code> (tab),399 <code class="literal">\b</code> (backspace), <code class="literal">\r</code> (carriage return),400 <code class="literal">\f</code> (form feed),401 <code class="literal">\</code><em class="replaceable"><code>digits</code></em> (octal), and402 <code class="literal">\x</code><em class="replaceable"><code>digits</code></em> (hexadecimal).403 A backslash preceding any other character within single-quoted text404 quotes that single character, whatever it is.405 </p><p>406 If an unquoted colon (<code class="literal">:</code>) followed by a407 <span class="application">psql</span> variable name appears within an argument, it is408 replaced by the variable's value, as described in <a class="xref" href="app-psql.html#APP-PSQL-INTERPOLATION" title="SQL Interpolation">SQL Interpolation</a> below.409 The forms <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> and410 <code class="literal">:"<em class="replaceable"><code>variable_name</code></em>"</code> described there411 work as well.412 The <code class="literal">:{?<em class="replaceable"><code>variable_name</code></em>}</code> syntax allows413 testing whether a variable is defined. It is substituted by414 TRUE or FALSE.415 Escaping the colon with a backslash protects it from substitution.416 </p><p>417 Within an argument, text that is enclosed in backquotes418 (<code class="literal">`</code>) is taken as a command line that is passed to the419 shell. The output of the command (with any trailing newline removed)420 replaces the backquoted text. Within the text enclosed in backquotes,421 no special quoting or other processing occurs, except that appearances422 of <code class="literal">:<em class="replaceable"><code>variable_name</code></em></code> where423 <em class="replaceable"><code>variable_name</code></em> is a <span class="application">psql</span> variable name424 are replaced by the variable's value. Also, appearances of425 <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> are replaced by the426 variable's value suitably quoted to become a single shell command427 argument. (The latter form is almost always preferable, unless you are428 very sure of what is in the variable.) Because carriage return and line429 feed characters cannot be safely quoted on all platforms, the430 <code class="literal">:'<em class="replaceable"><code>variable_name</code></em>'</code> form prints an431 error message and does not substitute the variable value when such432 characters appear in the value.433 </p><p>434 Some commands take an <acronym class="acronym">SQL</acronym> identifier (such as a435 table name) as argument. These arguments follow the syntax rules436 of <acronym class="acronym">SQL</acronym>: Unquoted letters are forced to437 lowercase, while double quotes (<code class="literal">"</code>) protect letters438 from case conversion and allow incorporation of whitespace into439 the identifier. Within double quotes, paired double quotes reduce440 to a single double quote in the resulting name. For example,441 <code class="literal">FOO"BAR"BAZ</code> is interpreted as <code class="literal">fooBARbaz</code>,442 and <code class="literal">"A weird"" name"</code> becomes <code class="literal">A weird"443 name</code>.444 </p><p>445 Parsing for arguments stops at the end of the line, or when another446 unquoted backslash is found. An unquoted backslash447 is taken as the beginning of a new meta-command. The special448 sequence <code class="literal">\\</code> (two backslashes) marks the end of449 arguments and continues parsing <acronym class="acronym">SQL</acronym> commands, if450 any. That way <acronym class="acronym">SQL</acronym> and451 <span class="application">psql</span> commands can be freely mixed on a452 line. But in any case, the arguments of a meta-command cannot453 continue beyond the end of the line.454 </p><p>455 Many of the meta-commands act on the <em class="firstterm">current query buffer</em>.456 This is simply a buffer holding whatever SQL command text has been typed457 but not yet sent to the server for execution. This will include previous458 input lines as well as any text appearing before the meta-command on the459 same line.460 </p><p>461 The following meta-commands are defined:462 463 </p><div class="variablelist"><dl class="variablelist"><dt id="APP-PSQL-META-COMMAND-A"><span class="term"><code class="literal">\a</code></span> <a href="#APP-PSQL-META-COMMAND-A" class="id_link">#</a></dt><dd><p>464 If the current table output format is unaligned, it is switched to aligned.465 If it is not unaligned, it is set to unaligned. This command is466 kept for backwards compatibility. See <code class="command">\pset</code> for a467 more general solution.468 </p></dd><dt id="APP-PSQL-META-COMMAND-BIND"><span class="term"><code class="literal">\bind</code> [ <em class="replaceable"><code>parameter</code></em> ] ... </span> <a href="#APP-PSQL-META-COMMAND-BIND" class="id_link">#</a></dt><dd><p>469 Sets query parameters for the next query execution, with the470 specified parameters passed for any parameter placeholders471 (<code class="literal">$1</code> etc.).472 </p><p>473 Example:474</p><pre class="programlisting">475INSERT INTO tbl1 VALUES ($1, $2) \bind 'first value' 'second value' \g476</pre><p>477 </p><p>478 This also works for query-execution commands besides479 <code class="literal">\g</code>, such as <code class="literal">\gx</code> and480 <code class="literal">\gset</code>.481 </p><p>482 This command causes the extended query protocol (see <a class="xref" href="protocol-overview.html#PROTOCOL-QUERY-CONCEPTS" title="55.1.2. Extended Query Overview">Section 55.1.2</a>) to be used, unlike normal483 <span class="application">psql</span> operation, which uses the simple484 query protocol. So this command can be useful to test the extended485 query protocol from psql. (The extended query protocol is used even486 if the query has no parameters and this command specifies zero487 parameters.) This command affects only the next query executed; all488 subsequent queries will use the simple query protocol by default.489 </p></dd><dt id="APP-PSQL-META-COMMAND-C-LC"><span class="term"><code class="literal">\c</code> or <code class="literal">\connect [ -reuse-previous=<em class="replaceable"><code>on|off</code></em> ] [ <em class="replaceable"><code>dbname</code></em> [ <em class="replaceable"><code>username</code></em> ] [ <em class="replaceable"><code>host</code></em> ] [ <em class="replaceable"><code>port</code></em> ] | <em class="replaceable"><code>conninfo</code></em> ]</code></span> <a href="#APP-PSQL-META-COMMAND-C-LC" class="id_link">#</a></dt><dd><p>490 Establishes a new connection to a <span class="productname">PostgreSQL</span>491 server. The connection parameters to use can be specified either492 using a positional syntax (one or more of database name, user,493 host, and port), or using a <em class="replaceable"><code>conninfo</code></em>494 connection string as detailed in495 <a class="xref" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">Section 34.1.1</a>. If no arguments are given, a496 new connection is made using the same parameters as before.497 </p><p>498 Specifying any499 of <em class="replaceable"><code>dbname</code></em>,500 <em class="replaceable"><code>username</code></em>,501 <em class="replaceable"><code>host</code></em> or502 <em class="replaceable"><code>port</code></em>503 as <code class="literal">-</code> is equivalent to omitting that parameter.504 </p><p>505 The new connection can re-use connection parameters from the previous506 connection; not only database name, user, host, and port, but other507 settings such as <em class="replaceable"><code>sslmode</code></em>. By default,508 parameters are re-used in the positional syntax, but not when509 a <em class="replaceable"><code>conninfo</code></em> string is given. Passing a510 first argument of <code class="literal">-reuse-previous=on</code>511 or <code class="literal">-reuse-previous=off</code> overrides that default. If512 parameters are re-used, then any parameter not explicitly specified as513 a positional parameter or in the <em class="replaceable"><code>conninfo</code></em>514 string is taken from the existing connection's parameters. An515 exception is that if the <em class="replaceable"><code>host</code></em> setting516 is changed from its previous value using the positional syntax,517 any <em class="replaceable"><code>hostaddr</code></em> setting present in the518 existing connection's parameters is dropped.519 Also, any password used for the existing connection will be re-used520 only if the user, host, and port settings are not changed.521 When the command neither specifies nor reuses a particular parameter,522 the <span class="application">libpq</span> default is used.523 </p><p>524 If the new connection is successfully made, the previous525 connection is closed.526 If the connection attempt fails (wrong user name, access527 denied, etc.), the previous connection will be kept if528 <span class="application">psql</span> is in interactive mode. But when529 executing a non-interactive script, the old connection is closed530 and an error is reported. That may or may not terminate the531 script; if it does not, all database-accessing commands will fail532 until another <code class="literal">\connect</code> command is successfully533 executed. This distinction was chosen as534 a user convenience against typos on the one hand, and a safety535 mechanism that scripts are not accidentally acting on the536 wrong database on the other hand.537 Note that whenever a <code class="literal">\connect</code> command attempts538 to re-use parameters, the values re-used are those of the last539 successful connection, not of any failed attempts made subsequently.540 However, in the case of a541 non-interactive <code class="literal">\connect</code> failure, no parameters542 are allowed to be re-used later, since the script would likely be543 expecting the values from the failed <code class="literal">\connect</code>544 to be re-used.545 </p><p>546 Examples:547 </p><pre class="programlisting">548=> \c mydb myuser host.dom 6432549=> \c service=foo550=> \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable"551=> \c -reuse-previous=on sslmode=require -- changes only sslmode552=> \c postgresql://tom@localhost/mydb?application_name=myapp553</pre></dd><dt id="APP-PSQL-META-COMMAND-C-UC"><span class="term"><code class="literal">\C [ <em class="replaceable"><code>title</code></em> ]</code></span> <a href="#APP-PSQL-META-COMMAND-C-UC" class="id_link">#</a></dt><dd><p>554 Sets the title of any tables being printed as the result of a555 query or unset any such title. This command is equivalent to556 <code class="literal">\pset title <em class="replaceable"><code>title</code></em></code>. (The name of557 this command derives from <span class="quote">“<span class="quote">caption</span>”</span>, as it was558 previously only used to set the caption in an559 <acronym class="acronym">HTML</acronym> table.)560 </p></dd><dt id="APP-PSQL-META-COMMAND-CD"><span class="term"><code class="literal">\cd [ <em class="replaceable"><code>directory</code></em> ]</code></span> <a href="#APP-PSQL-META-COMMAND-CD" class="id_link">#</a></dt><dd><p>561 Changes the current working directory to562 <em class="replaceable"><code>directory</code></em>. Without argument, changes563 to the current user's home directory.564 </p><div class="tip"><h3 class="title">Tip</h3><p>565 To print your current working directory, use <code class="literal">\! pwd</code>.566 </p></div></dd><dt id="APP-PSQL-META-COMMAND-CONNINFO"><span class="term"><code class="literal">\conninfo</code></span> <a href="#APP-PSQL-META-COMMAND-CONNINFO" class="id_link">#</a></dt><dd><p>567 Outputs information about the current database connection.568 </p></dd><dt id="APP-PSQL-META-COMMANDS-COPY"><span class="term"><code class="literal">\copy { <em class="replaceable"><code>table</code></em> [ ( <em class="replaceable"><code>column_list</code></em> ) ] }569 <code class="literal">from</code>570 { <em class="replaceable"><code>'filename'</code></em> | program <em class="replaceable"><code>'command'</code></em> | stdin | pstdin }571 [ [ with ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]572 [ where <em class="replaceable"><code>condition</code></em> ]</code><br /></span><span class="term"><code class="literal">\copy { <em class="replaceable"><code>table</code></em> [ ( <em class="replaceable"><code>column_list</code></em> ) ] | ( <em class="replaceable"><code>query</code></em> ) }573 <code class="literal">to</code>574 { <em class="replaceable"><code>'filename'</code></em> | program <em class="replaceable"><code>'command'</code></em> | stdout | pstdout }575 [ [ with ] ( <em class="replaceable"><code>option</code></em> [, ...] ) ]</code></span> <a href="#APP-PSQL-META-COMMANDS-COPY" class="id_link">#</a></dt><dd><p>576 Performs a frontend (client) copy. This is an operation that577 runs an <acronym class="acronym">SQL</acronym> <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a>578 command, but instead of the server579 reading or writing the specified file,580 <span class="application">psql</span> reads or writes the file and581 routes the data between the server and the local file system.582 This means that file accessibility and privileges are those of583 the local user, not the server, and no SQL superuser584 privileges are required.585 </p><p>586 When <code class="literal">program</code> is specified,587 <em class="replaceable"><code>command</code></em> is588 executed by <span class="application">psql</span> and the data passed from589 or to <em class="replaceable"><code>command</code></em> is590 routed between the server and the client.591 Again, the execution privileges are those of592 the local user, not the server, and no SQL superuser593 privileges are required.594 </p><p>595 For <code class="literal">\copy ... from stdin</code>, data rows are read from the same596 source that issued the command, continuing until <code class="literal">\.</code>597 is read or the stream reaches <acronym class="acronym">EOF</acronym>. This option is useful598 for populating tables in-line within an SQL script file.599 For <code class="literal">\copy ... to stdout</code>, output is sent to the same place600 as <span class="application">psql</span> command output, and601 the <code class="literal">COPY <em class="replaceable"><code>count</code></em></code> command status is602 not printed (since it might be confused with a data row).603 To read/write <span class="application">psql</span>'s standard input or604 output regardless of the current command source or <code class="literal">\o</code>605 option, write <code class="literal">from pstdin</code> or <code class="literal">to pstdout</code>.606 </p><p>607 The syntax of this command is similar to that of the608 <acronym class="acronym">SQL</acronym> <a class="link" href="sql-copy.html" title="COPY"><code class="command">COPY</code></a>609 command. All options other than the data source/destination are610 as specified for <code class="command">COPY</code>.611 Because of this, special parsing rules apply to the <code class="command">\copy</code>612 meta-command. Unlike most other meta-commands, the entire remainder613 of the line is always taken to be the arguments of <code class="command">\copy</code>,614 and neither variable interpolation nor backquote expansion are615 performed in the arguments.616 </p><div class="tip"><h3 class="title">Tip</h3><p>617 Another way to obtain the same result as <code class="literal">\copy618 ... to</code> is to use the <acronym class="acronym">SQL</acronym> <code class="literal">COPY619 ... TO STDOUT</code> command and terminate it620 with <code class="literal">\g <em class="replaceable"><code>filename</code></em></code>621 or <code class="literal">\g |<em class="replaceable"><code>program</code></em></code>.622 Unlike <code class="literal">\copy</code>, this method allows the command to623 span multiple lines; also, variable interpolation and backquote624 expansion can be used.625 </p></div><div class="tip"><h3 class="title">Tip</h3><p>626 These operations are not as efficient as the <acronym class="acronym">SQL</acronym>627 <code class="command">COPY</code> command with a file or program data source or628 destination, because all data must pass through the client/server629 connection. For large amounts of data the <acronym class="acronym">SQL</acronym>630 command might be preferable.631 Also, because of this pass-through method, <code class="literal">\copy632 ... from</code> in <acronym class="acronym">CSV</acronym> mode will erroneously633 treat a <code class="literal">\.</code> data value alone on a line as an634 end-of-input marker.635 </p></div></dd><dt id="APP-PSQL-META-COMMAND-COPYRIGHT"><span class="term"><code class="literal">\copyright</code></span> <a href="#APP-PSQL-META-COMMAND-COPYRIGHT" class="id_link">#</a></dt><dd><p>636 Shows the copyright and distribution terms of637 <span class="productname">PostgreSQL</span>.638 </p></dd><dt id="APP-PSQL-META-COMMANDS-CROSSTABVIEW"><span class="term"><code class="literal">\crosstabview [639 <em class="replaceable"><code>colV</code></em>640 [ <em class="replaceable"><code>colH</code></em>641 [ <em class="replaceable"><code>colD</code></em>642 [ <em class="replaceable"><code>sortcolH</code></em>643 ] ] ] ] </code></span> <a href="#APP-PSQL-META-COMMANDS-CROSSTABVIEW" class="id_link">#</a></dt><dd><p>644 Executes the current query buffer (like <code class="literal">\g</code>) and645 shows the results in a crosstab grid.646 The query must return at least three columns.647 The output column identified by <em class="replaceable"><code>colV</code></em>648 becomes a vertical header and the output column identified by649 <em class="replaceable"><code>colH</code></em>650 becomes a horizontal header.651 <em class="replaceable"><code>colD</code></em> identifies652 the output column to display within the grid.653 <em class="replaceable"><code>sortcolH</code></em> identifies654 an optional sort column for the horizontal header.655 </p><p>656 Each column specification can be a column number (starting at 1) or657 a column name. The usual SQL case folding and quoting rules apply to658 column names. If omitted,659 <em class="replaceable"><code>colV</code></em> is taken as column 1660 and <em class="replaceable"><code>colH</code></em> as column 2.661 <em class="replaceable"><code>colH</code></em> must differ from662 <em class="replaceable"><code>colV</code></em>.663 If <em class="replaceable"><code>colD</code></em> is not664 specified, then there must be exactly three columns in the query665 result, and the column that is neither666 <em class="replaceable"><code>colV</code></em> nor667 <em class="replaceable"><code>colH</code></em>668 is taken to be <em class="replaceable"><code>colD</code></em>.669 </p><p>670 The vertical header, displayed as the leftmost column, contains the671 values found in column <em class="replaceable"><code>colV</code></em>, in the672 same order as in the query results, but with duplicates removed.673 </p><p>674 The horizontal header, displayed as the first row, contains the values675 found in column <em class="replaceable"><code>colH</code></em>,676 with duplicates removed. By default, these appear in the same order677 as in the query results. But if the678 optional <em class="replaceable"><code>sortcolH</code></em> argument is given,679 it identifies a column whose values must be integer numbers, and the680 values from <em class="replaceable"><code>colH</code></em> will681 appear in the horizontal header sorted according to the682 corresponding <em class="replaceable"><code>sortcolH</code></em> values.683 </p><p>684 Inside the crosstab grid, for each distinct value <code class="literal">x</code>685 of <em class="replaceable"><code>colH</code></em> and each distinct686 value <code class="literal">y</code>687 of <em class="replaceable"><code>colV</code></em>, the cell located688 at the intersection <code class="literal">(x,y)</code> contains the value of689 the <code class="literal">colD</code> column in the query result row for which690 the value of <em class="replaceable"><code>colH</code></em>691 is <code class="literal">x</code> and the value692 of <em class="replaceable"><code>colV</code></em>693 is <code class="literal">y</code>. If there is no such row, the cell is empty. If694 there are multiple such rows, an error is reported.695 </p></dd><dt id="APP-PSQL-META-COMMAND-D"><span class="term"><code class="literal">\d[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-D" class="id_link">#</a></dt><dd><p>696 For each relation (table, view, materialized view, index, sequence,697 or foreign table)698 or composite type matching the699 <em class="replaceable"><code>pattern</code></em>, show all700 columns, their types, the tablespace (if not the default) and any701 special attributes such as <code class="literal">NOT NULL</code> or defaults.702 Associated indexes, constraints, rules, and triggers are703 also shown. For foreign tables, the associated foreign704 server is shown as well.705 (<span class="quote">“<span class="quote">Matching the pattern</span>”</span> is defined in706 <a class="xref" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns">Patterns</a> below.)707 </p><p>708 For some types of relation, <code class="literal">\d</code> shows additional information709 for each column: column values for sequences, indexed expressions for710 indexes, and foreign data wrapper options for foreign tables.711 </p><p>712 The command form <code class="literal">\d+</code> is identical, except that713 more information is displayed: any comments associated with the714 columns of the table are shown, as is the presence of OIDs in the715 table, the view definition if the relation is a view, a non-default716 <a class="link" href="sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY">replica717 identity</a> setting and the718 <a class="link" href="sql-create-access-method.html" title="CREATE ACCESS METHOD">access method</a> name719 if the relation has an access method.720 </p><p>721 By default, only user-created objects are shown; supply a722 pattern or the <code class="literal">S</code> modifier to include system723 objects.724 </p><div class="note"><h3 class="title">Note</h3><p>725 If <code class="command">\d</code> is used without a726 <em class="replaceable"><code>pattern</code></em> argument, it is727 equivalent to <code class="command">\dtvmsE</code> which will show a list of728 all visible tables, views, materialized views, sequences and729 foreign tables.730 This is purely a convenience measure.731 </p></div></dd><dt id="APP-PSQL-META-COMMAND-DA-LC"><span class="term"><code class="literal">\da[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DA-LC" class="id_link">#</a></dt><dd><p>732 Lists aggregate functions, together with their733 return type and the data types they operate on. If <em class="replaceable"><code>pattern</code></em>734 is specified, only aggregates whose names match the pattern are shown.735 By default, only user-created objects are shown; supply a736 pattern or the <code class="literal">S</code> modifier to include system737 objects.738 </p></dd><dt id="APP-PSQL-META-COMMAND-DA-UC"><span class="term"><code class="literal">\dA[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DA-UC" class="id_link">#</a></dt><dd><p>739 Lists access methods. If <em class="replaceable"><code>pattern</code></em> is specified, only access740 methods whose names match the pattern are shown. If741 <code class="literal">+</code> is appended to the command name, each access742 method is listed with its associated handler function and description.743 </p></dd><dt id="APP-PSQL-META-COMMAND-DAC"><span class="term">744 <code class="literal">\dAc[+]745 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>746 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>input-type-pattern</code></em></a>]]747 </code>748 </span> <a href="#APP-PSQL-META-COMMAND-DAC" class="id_link">#</a></dt><dd><p>749 Lists operator classes750 (see <a class="xref" href="xindex.html#XINDEX-OPCLASS" title="38.16.1. Index Methods and Operator Classes">Section 38.16.1</a>).751 If <em class="replaceable"><code>access-method-pattern</code></em>752 is specified, only operator classes associated with access methods whose753 names match that pattern are listed.754 If <em class="replaceable"><code>input-type-pattern</code></em>755 is specified, only operator classes associated with input types whose756 names match that pattern are listed.757 If <code class="literal">+</code> is appended to the command name, each operator758 class is listed with its associated operator family and owner.759 </p></dd><dt id="APP-PSQL-META-COMMAND-DAF"><span class="term">760 <code class="literal">\dAf[+]761 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>762 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>input-type-pattern</code></em></a>]]763 </code>764 </span> <a href="#APP-PSQL-META-COMMAND-DAF" class="id_link">#</a></dt><dd><p>765 Lists operator families766 (see <a class="xref" href="xindex.html#XINDEX-OPFAMILY" title="38.16.5. Operator Classes and Operator Families">Section 38.16.5</a>).767 If <em class="replaceable"><code>access-method-pattern</code></em>768 is specified, only operator families associated with access methods whose769 names match that pattern are listed.770 If <em class="replaceable"><code>input-type-pattern</code></em>771 is specified, only operator families associated with input types whose772 names match that pattern are listed.773 If <code class="literal">+</code> is appended to the command name, each operator774 family is listed with its owner.775 </p></dd><dt id="APP-PSQL-META-COMMAND-DAO"><span class="term">776 <code class="literal">\dAo[+]777 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>778 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>operator-family-pattern</code></em></a>]]779 </code>780 </span> <a href="#APP-PSQL-META-COMMAND-DAO" class="id_link">#</a></dt><dd><p>781 Lists operators associated with operator families782 (see <a class="xref" href="xindex.html#XINDEX-STRATEGIES" title="38.16.2. Index Method Strategies">Section 38.16.2</a>).783 If <em class="replaceable"><code>access-method-pattern</code></em>784 is specified, only members of operator families associated with access785 methods whose names match that pattern are listed.786 If <em class="replaceable"><code>operator-family-pattern</code></em>787 is specified, only members of operator families whose names match that788 pattern are listed.789 If <code class="literal">+</code> is appended to the command name, each operator790 is listed with its sort operator family (if it is an ordering operator).791 </p></dd><dt id="APP-PSQL-META-COMMAND-DAP"><span class="term">792 <code class="literal">\dAp[+]793 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>access-method-pattern</code></em></a>794 [<a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>operator-family-pattern</code></em></a>]]795 </code>796 </span> <a href="#APP-PSQL-META-COMMAND-DAP" class="id_link">#</a></dt><dd><p>797 Lists support functions associated with operator families798 (see <a class="xref" href="xindex.html#XINDEX-SUPPORT" title="38.16.3. Index Method Support Routines">Section 38.16.3</a>).799 If <em class="replaceable"><code>access-method-pattern</code></em>800 is specified, only functions of operator families associated with801 access methods whose names match that pattern are listed.802 If <em class="replaceable"><code>operator-family-pattern</code></em>803 is specified, only functions of operator families whose names match804 that pattern are listed.805 If <code class="literal">+</code> is appended to the command name, functions are806 displayed verbosely, with their actual parameter lists.807 </p></dd><dt id="APP-PSQL-META-COMMAND-DB"><span class="term"><code class="literal">\db[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DB" class="id_link">#</a></dt><dd><p>808 Lists tablespaces. If <em class="replaceable"><code>pattern</code></em>809 is specified, only tablespaces whose names match the pattern are shown.810 If <code class="literal">+</code> is appended to the command name, each tablespace811 is listed with its associated options, on-disk size, permissions and812 description.813 </p></dd><dt id="APP-PSQL-META-COMMAND-DC-LC"><span class="term"><code class="literal">\dc[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DC-LC" class="id_link">#</a></dt><dd><p>814 Lists conversions between character-set encodings.815 If <em class="replaceable"><code>pattern</code></em>816 is specified, only conversions whose names match the pattern are817 listed.818 By default, only user-created objects are shown; supply a819 pattern or the <code class="literal">S</code> modifier to include system820 objects.821 If <code class="literal">+</code> is appended to the command name, each object822 is listed with its associated description.823 </p></dd><dt id="APP-PSQL-META-COMMAND-DCONFIG"><span class="term"><code class="literal">\dconfig[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DCONFIG" class="id_link">#</a></dt><dd><p>824 Lists server configuration parameters and their values.825 If <em class="replaceable"><code>pattern</code></em> is specified,826 only parameters whose names match the pattern are listed. Without827 a <em class="replaceable"><code>pattern</code></em>, only828 parameters that are set to non-default values are listed.829 (Use <code class="literal">\dconfig *</code> to see all parameters.)830 If <code class="literal">+</code> is appended to the command name, each831 parameter is listed with its data type, context in which the832 parameter can be set, and access privileges (if non-default access833 privileges have been granted).834 </p></dd><dt id="APP-PSQL-META-COMMAND-DC-UC"><span class="term"><code class="literal">\dC[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DC-UC" class="id_link">#</a></dt><dd><p>835 Lists type casts.836 If <em class="replaceable"><code>pattern</code></em>837 is specified, only casts whose source or target types match the838 pattern are listed.839 If <code class="literal">+</code> is appended to the command name, each object840 is listed with its associated description.841 </p></dd><dt id="APP-PSQL-META-COMMAND-DD-LC"><span class="term"><code class="literal">\dd[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DD-LC" class="id_link">#</a></dt><dd><p>842 Shows the descriptions of objects of type <code class="literal">constraint</code>,843 <code class="literal">operator class</code>, <code class="literal">operator family</code>,844 <code class="literal">rule</code>, and <code class="literal">trigger</code>. All845 other comments may be viewed by the respective backslash commands for846 those object types.847 </p><p><code class="literal">\dd</code> displays descriptions for objects matching the848 <em class="replaceable"><code>pattern</code></em>, or of visible849 objects of the appropriate type if no argument is given. But in either850 case, only objects that have a description are listed.851 By default, only user-created objects are shown; supply a852 pattern or the <code class="literal">S</code> modifier to include system853 objects.854 </p><p>855 Descriptions for objects can be created with the <a class="link" href="sql-comment.html" title="COMMENT"><code class="command">COMMENT</code></a>856 <acronym class="acronym">SQL</acronym> command.857 </p></dd><dt id="APP-PSQL-META-COMMAND-DD-UC"><span class="term"><code class="literal">\dD[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DD-UC" class="id_link">#</a></dt><dd><p>858 Lists domains. If <em class="replaceable"><code>pattern</code></em>859 is specified, only domains whose names match the pattern are shown.860 By default, only user-created objects are shown; supply a861 pattern or the <code class="literal">S</code> modifier to include system862 objects.863 If <code class="literal">+</code> is appended to the command name, each object864 is listed with its associated permissions and description.865 </p></dd><dt id="APP-PSQL-META-COMMAND-DDP"><span class="term"><code class="literal">\ddp [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DDP" class="id_link">#</a></dt><dd><p>866 Lists default access privilege settings. An entry is shown for867 each role (and schema, if applicable) for which the default868 privilege settings have been changed from the built-in defaults.869 If <em class="replaceable"><code>pattern</code></em> is870 specified, only entries whose role name or schema name matches871 the pattern are listed.872 </p><p>873 The <a class="link" href="sql-alterdefaultprivileges.html" title="ALTER DEFAULT PRIVILEGES"><code class="command">ALTER DEFAULT874 PRIVILEGES</code></a> command is used to set default access875 privileges. The meaning of the privilege display is explained in876 <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.877 </p></dd><dt id="APP-PSQL-META-COMMAND-DE"><span class="term"><code class="literal">\dE[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\di[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dm[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\ds[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dt[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code><br /></span><span class="term"><code class="literal">\dv[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DE" class="id_link">#</a></dt><dd><p>878 In this group of commands, the letters <code class="literal">E</code>,879 <code class="literal">i</code>, <code class="literal">m</code>, <code class="literal">s</code>,880 <code class="literal">t</code>, and <code class="literal">v</code>881 stand for foreign table, index, materialized view,882 sequence, table, and view,883 respectively.884 You can specify any or all of885 these letters, in any order, to obtain a listing of objects886 of these types. For example, <code class="literal">\dti</code> lists887 tables and indexes. If <code class="literal">+</code> is888 appended to the command name, each object is listed with its889 persistence status (permanent, temporary, or unlogged),890 physical size on disk, and associated description if any.891 If <em class="replaceable"><code>pattern</code></em> is892 specified, only objects whose names match the pattern are listed.893 By default, only user-created objects are shown; supply a894 pattern or the <code class="literal">S</code> modifier to include system895 objects.896 </p></dd><dt id="APP-PSQL-META-COMMAND-DES"><span class="term"><code class="literal">\des[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DES" class="id_link">#</a></dt><dd><p>897 Lists foreign servers (mnemonic: <span class="quote">“<span class="quote">external898 servers</span>”</span>).899 If <em class="replaceable"><code>pattern</code></em> is900 specified, only those servers whose name matches the pattern901 are listed. If the form <code class="literal">\des+</code> is used, a902 full description of each server is shown, including the903 server's access privileges, type, version, options, and description.904 </p></dd><dt id="APP-PSQL-META-COMMAND-DET"><span class="term"><code class="literal">\det[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DET" class="id_link">#</a></dt><dd><p>905 Lists foreign tables (mnemonic: <span class="quote">“<span class="quote">external tables</span>”</span>).906 If <em class="replaceable"><code>pattern</code></em> is907 specified, only entries whose table name or schema name matches908 the pattern are listed. If the form <code class="literal">\det+</code>909 is used, generic options and the foreign table description910 are also displayed.911 </p></dd><dt id="APP-PSQL-META-COMMAND-DEU"><span class="term"><code class="literal">\deu[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DEU" class="id_link">#</a></dt><dd><p>912 Lists user mappings (mnemonic: <span class="quote">“<span class="quote">external913 users</span>”</span>).914 If <em class="replaceable"><code>pattern</code></em> is915 specified, only those mappings whose user names match the916 pattern are listed. If the form <code class="literal">\deu+</code> is917 used, additional information about each mapping is shown.918 </p><div class="caution"><h3 class="title">Caution</h3><p>919 <code class="literal">\deu+</code> might also display the user name and920 password of the remote user, so care should be taken not to921 disclose them.922 </p></div></dd><dt id="APP-PSQL-META-COMMAND-DEW"><span class="term"><code class="literal">\dew[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DEW" class="id_link">#</a></dt><dd><p>923 Lists foreign-data wrappers (mnemonic: <span class="quote">“<span class="quote">external924 wrappers</span>”</span>).925 If <em class="replaceable"><code>pattern</code></em> is926 specified, only those foreign-data wrappers whose name matches927 the pattern are listed. If the form <code class="literal">\dew+</code>928 is used, the access privileges, options, and description of the929 foreign-data wrapper are also shown.930 </p></dd><dt id="APP-PSQL-META-COMMAND-DF-LC"><span class="term"><code class="literal">\df[anptwS+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> [ <em class="replaceable"><code>arg_pattern</code></em> ... ] ]</code></span> <a href="#APP-PSQL-META-COMMAND-DF-LC" class="id_link">#</a></dt><dd><p>931 Lists functions, together with their result data types, argument data932 types, and function types, which are classified as <span class="quote">“<span class="quote">agg</span>”</span>933 (aggregate), <span class="quote">“<span class="quote">normal</span>”</span>, <span class="quote">“<span class="quote">procedure</span>”</span>, <span class="quote">“<span class="quote">trigger</span>”</span>, or <span class="quote">“<span class="quote">window</span>”</span>.934 To display only functions935 of specific type(s), add the corresponding letters <code class="literal">a</code>,936 <code class="literal">n</code>, <code class="literal">p</code>, <code class="literal">t</code>, or <code class="literal">w</code> to the command.937 If <em class="replaceable"><code>pattern</code></em> is specified, only938 functions whose names match the pattern are shown.939 Any additional arguments are type-name patterns, which are matched940 to the type names of the first, second, and so on arguments of the941 function. (Matching functions can have more arguments than what942 you specify. To prevent that, write a dash <code class="literal">-</code> as943 the last <em class="replaceable"><code>arg_pattern</code></em>.)944 By default, only user-created945 objects are shown; supply a pattern or the <code class="literal">S</code>946 modifier to include system objects.947 If the form <code class="literal">\df+</code> is used, additional information948 about each function is shown, including volatility,949 parallel safety, owner, security classification, access privileges,950 language, internal name (for C and internal functions only),951 and description.952 Source code for a specific function can be seen953 using <code class="literal">\sf</code>.954 </p></dd><dt id="APP-PSQL-META-COMMAND-DF-UC"><span class="term"><code class="literal">\dF[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DF-UC" class="id_link">#</a></dt><dd><p>955 Lists text search configurations.956 If <em class="replaceable"><code>pattern</code></em> is specified,957 only configurations whose names match the pattern are shown.958 If the form <code class="literal">\dF+</code> is used, a full description of959 each configuration is shown, including the underlying text search960 parser and the dictionary list for each parser token type.961 </p></dd><dt id="APP-PSQL-META-COMMAND-DFD"><span class="term"><code class="literal">\dFd[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DFD" class="id_link">#</a></dt><dd><p>962 Lists text search dictionaries.963 If <em class="replaceable"><code>pattern</code></em> is specified,964 only dictionaries whose names match the pattern are shown.965 If the form <code class="literal">\dFd+</code> is used, additional information966 is shown about each selected dictionary, including the underlying967 text search template and the option values.968 </p></dd><dt id="APP-PSQL-META-COMMAND-DFP"><span class="term"><code class="literal">\dFp[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DFP" class="id_link">#</a></dt><dd><p>969 Lists text search parsers.970 If <em class="replaceable"><code>pattern</code></em> is specified,971 only parsers whose names match the pattern are shown.972 If the form <code class="literal">\dFp+</code> is used, a full description of973 each parser is shown, including the underlying functions and the974 list of recognized token types.975 </p></dd><dt id="APP-PSQL-META-COMMAND-DFT"><span class="term"><code class="literal">\dFt[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DFT" class="id_link">#</a></dt><dd><p>976 Lists text search templates.977 If <em class="replaceable"><code>pattern</code></em> is specified,978 only templates whose names match the pattern are shown.979 If the form <code class="literal">\dFt+</code> is used, additional information980 is shown about each template, including the underlying function names.981 </p></dd><dt id="APP-PSQL-META-COMMAND-DG"><span class="term"><code class="literal">\dg[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DG" class="id_link">#</a></dt><dd><p>982 Lists database roles.983 (Since the concepts of <span class="quote">“<span class="quote">users</span>”</span> and <span class="quote">“<span class="quote">groups</span>”</span> have been984 unified into <span class="quote">“<span class="quote">roles</span>”</span>, this command is now equivalent to985 <code class="literal">\du</code>.)986 By default, only user-created roles are shown; supply the987 <code class="literal">S</code> modifier to include system roles.988 If <em class="replaceable"><code>pattern</code></em> is specified,989 only those roles whose names match the pattern are listed.990 If the form <code class="literal">\dg+</code> is used, additional information991 is shown about each role; currently this adds the comment for each992 role.993 </p></dd><dt id="APP-PSQL-META-COMMAND-DL-LC"><span class="term"><code class="literal">\dl[+]</code></span> <a href="#APP-PSQL-META-COMMAND-DL-LC" class="id_link">#</a></dt><dd><p>994 This is an alias for <code class="command">\lo_list</code>, which shows a995 list of large objects.996 If <code class="literal">+</code> is appended to the command name,997 each large object is listed with its associated permissions,998 if any.999 </p></dd><dt id="APP-PSQL-META-COMMAND-DL-UC"><span class="term"><code class="literal">\dL[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DL-UC" class="id_link">#</a></dt><dd><p>1000 Lists procedural languages. If <em class="replaceable"><code>pattern</code></em>1001 is specified, only languages whose names match the pattern are listed.1002 By default, only user-created languages1003 are shown; supply the <code class="literal">S</code> modifier to include system1004 objects. If <code class="literal">+</code> is appended to the command name, each1005 language is listed with its call handler, validator, access privileges,1006 and whether it is a system object.1007 </p></dd><dt id="APP-PSQL-META-COMMAND-DN"><span class="term"><code class="literal">\dn[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DN" class="id_link">#</a></dt><dd><p>1008 Lists schemas (namespaces). If <em class="replaceable"><code>pattern</code></em>1009 is specified, only schemas whose names match the pattern are listed.1010 By default, only user-created objects are shown; supply a1011 pattern or the <code class="literal">S</code> modifier to include system objects.1012 If <code class="literal">+</code> is appended to the command name, each object1013 is listed with its associated permissions and description, if any.1014 </p></dd><dt id="APP-PSQL-META-COMMAND-DO-LC"><span class="term"><code class="literal">\do[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> [ <em class="replaceable"><code>arg_pattern</code></em> [ <em class="replaceable"><code>arg_pattern</code></em> ] ] ]</code></span> <a href="#APP-PSQL-META-COMMAND-DO-LC" class="id_link">#</a></dt><dd><p>1015 Lists operators with their operand and result types.1016 If <em class="replaceable"><code>pattern</code></em> is1017 specified, only operators whose names match the pattern are listed.1018 If one <em class="replaceable"><code>arg_pattern</code></em> is1019 specified, only prefix operators whose right argument's type name1020 matches that pattern are listed.1021 If two <em class="replaceable"><code>arg_pattern</code></em>s1022 are specified, only binary operators whose argument type names match1023 those patterns are listed. (Alternatively, write <code class="literal">-</code>1024 for the unused argument of a unary operator.)1025 By default, only user-created objects are shown; supply a1026 pattern or the <code class="literal">S</code> modifier to include system1027 objects.1028 If <code class="literal">+</code> is appended to the command name,1029 additional information about each operator is shown, currently just1030 the name of the underlying function.1031 </p></dd><dt id="APP-PSQL-META-COMMAND-DO-UC"><span class="term"><code class="literal">\dO[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DO-UC" class="id_link">#</a></dt><dd><p>1032 Lists collations.1033 If <em class="replaceable"><code>pattern</code></em> is1034 specified, only collations whose names match the pattern are1035 listed. By default, only user-created objects are shown;1036 supply a pattern or the <code class="literal">S</code> modifier to1037 include system objects. If <code class="literal">+</code> is appended1038 to the command name, each collation is listed with its associated1039 description, if any.1040 Note that only collations usable with the current database's encoding1041 are shown, so the results may vary in different databases of the1042 same installation.1043 </p></dd><dt id="APP-PSQL-META-COMMAND-DP-LC"><span class="term"><code class="literal">\dp[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DP-LC" class="id_link">#</a></dt><dd><p>1044 Lists tables, views and sequences with their1045 associated access privileges.1046 If <em class="replaceable"><code>pattern</code></em> is1047 specified, only tables, views and sequences whose names match the1048 pattern are listed. By default only user-created objects are shown;1049 supply a pattern or the <code class="literal">S</code> modifier to include1050 system objects.1051 </p><p>1052 The <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a> and1053 <a class="link" href="sql-revoke.html" title="REVOKE"><code class="command">REVOKE</code></a>1054 commands are used to set access privileges. The meaning of the1055 privilege display is explained in1056 <a class="xref" href="ddl-priv.html" title="5.7. Privileges">Section 5.7</a>.1057 </p></dd><dt id="APP-PSQL-META-COMMAND-DP-UC"><span class="term"><code class="literal">\dP[itn+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DP-UC" class="id_link">#</a></dt><dd><p>1058 Lists partitioned relations.1059 If <em class="replaceable"><code>pattern</code></em>1060 is specified, only entries whose name matches the pattern are listed.1061 The modifiers <code class="literal">t</code> (tables) and <code class="literal">i</code>1062 (indexes) can be appended to the command, filtering the kind of1063 relations to list. By default, partitioned tables and indexes are1064 listed.1065 </p><p>1066 If the modifier <code class="literal">n</code> (<span class="quote">“<span class="quote">nested</span>”</span>) is used,1067 or a pattern is specified, then non-root partitioned relations are1068 included, and a column is shown displaying the parent of each1069 partitioned relation.1070 </p><p>1071 If <code class="literal">+</code> is appended to the command name, the sum of the1072 sizes of each relation's partitions is also displayed, along with the1073 relation's description.1074 If <code class="literal">n</code> is combined with <code class="literal">+</code>, two1075 sizes are shown: one including the total size of directly-attached1076 leaf partitions, and another showing the total size of all partitions,1077 including indirectly attached sub-partitions.1078 </p></dd><dt id="APP-PSQL-META-COMMAND-DRDS"><span class="term"><code class="literal">\drds [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>role-pattern</code></em></a> [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>database-pattern</code></em></a> ] ]</code></span> <a href="#APP-PSQL-META-COMMAND-DRDS" class="id_link">#</a></dt><dd><p>1079 Lists defined configuration settings. These settings can be1080 role-specific, database-specific, or both.1081 <em class="replaceable"><code>role-pattern</code></em> and1082 <em class="replaceable"><code>database-pattern</code></em> are used to select1083 specific roles and databases to list, respectively. If omitted, or if1084 <code class="literal">*</code> is specified, all settings are listed, including those1085 not role-specific or database-specific, respectively.1086 </p><p>1087 The <a class="link" href="sql-alterrole.html" title="ALTER ROLE"><code class="command">ALTER ROLE</code></a> and1088 <a class="link" href="sql-alterdatabase.html" title="ALTER DATABASE"><code class="command">ALTER DATABASE</code></a>1089 commands are used to define per-role and per-database configuration1090 settings.1091 </p></dd><dt id="APP-PSQL-META-COMMAND-DRG"><span class="term"><code class="literal">\drg[S] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DRG" class="id_link">#</a></dt><dd><p>1092 Lists information about each granted role membership, including1093 assigned options (<code class="literal">ADMIN</code>,1094 <code class="literal">INHERIT</code> and/or <code class="literal">SET</code>) and grantor.1095 See the <a class="link" href="sql-grant.html" title="GRANT"><code class="command">GRANT</code></a>1096 command for information about role memberships.1097 </p><p>1098 By default, only grants to user-created roles are shown; supply the1099 <code class="literal">S</code> modifier to include system roles.1100 If <em class="replaceable"><code>pattern</code></em> is specified,1101 only grants to those roles whose names match the pattern are listed.1102 </p></dd><dt id="APP-PSQL-META-COMMAND-DRP"><span class="term"><code class="literal">\dRp[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DRP" class="id_link">#</a></dt><dd><p>1103 Lists replication publications.1104 If <em class="replaceable"><code>pattern</code></em> is1105 specified, only those publications whose names match the pattern are1106 listed.1107 If <code class="literal">+</code> is appended to the command name, the tables and1108 schemas associated with each publication are shown as well.1109 </p></dd><dt id="APP-PSQL-META-COMMAND-DRS"><span class="term"><code class="literal">\dRs[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DRS" class="id_link">#</a></dt><dd><p>1110 Lists replication subscriptions.1111 If <em class="replaceable"><code>pattern</code></em> is1112 specified, only those subscriptions whose names match the pattern are1113 listed.1114 If <code class="literal">+</code> is appended to the command name, additional1115 properties of the subscriptions are shown.1116 </p></dd><dt id="APP-PSQL-META-COMMAND-DT"><span class="term"><code class="literal">\dT[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DT" class="id_link">#</a></dt><dd><p>1117 Lists data types.1118 If <em class="replaceable"><code>pattern</code></em> is1119 specified, only types whose names match the pattern are listed.1120 If <code class="literal">+</code> is appended to the command name, each type is1121 listed with its internal name and size, its allowed values1122 if it is an <code class="type">enum</code> type, and its associated permissions.1123 By default, only user-created objects are shown; supply a1124 pattern or the <code class="literal">S</code> modifier to include system1125 objects.1126 </p></dd><dt id="APP-PSQL-META-COMMAND-DU"><span class="term"><code class="literal">\du[S+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DU" class="id_link">#</a></dt><dd><p>1127 Lists database roles.1128 (Since the concepts of <span class="quote">“<span class="quote">users</span>”</span> and <span class="quote">“<span class="quote">groups</span>”</span> have been1129 unified into <span class="quote">“<span class="quote">roles</span>”</span>, this command is now equivalent to1130 <code class="literal">\dg</code>.)1131 By default, only user-created roles are shown; supply the1132 <code class="literal">S</code> modifier to include system roles.1133 If <em class="replaceable"><code>pattern</code></em> is specified,1134 only those roles whose names match the pattern are listed.1135 If the form <code class="literal">\du+</code> is used, additional information1136 is shown about each role; currently this adds the comment for each1137 role.1138 </p></dd><dt id="APP-PSQL-META-COMMAND-DX-LC"><span class="term"><code class="literal">\dx[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DX-LC" class="id_link">#</a></dt><dd><p>1139 Lists installed extensions.1140 If <em class="replaceable"><code>pattern</code></em>1141 is specified, only those extensions whose names match the pattern1142 are listed.1143 If the form <code class="literal">\dx+</code> is used, all the objects belonging1144 to each matching extension are listed.1145 </p></dd><dt id="APP-PSQL-META-COMMAND-DX-UC"><span class="term"><code class="literal">\dX [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DX-UC" class="id_link">#</a></dt><dd><p>1146 Lists extended statistics.1147 If <em class="replaceable"><code>pattern</code></em>1148 is specified, only those extended statistics whose names match the1149 pattern are listed.1150 </p><p>1151 The status of each kind of extended statistics is shown in a column1152 named after its statistic kind (e.g. Ndistinct).1153 <code class="literal">defined</code> means that it was requested when creating1154 the statistics, and NULL means it wasn't requested.1155 You can use <code class="structname">pg_stats_ext</code> if you'd like to1156 know whether <a class="link" href="sql-analyze.html" title="ANALYZE"><code class="command">ANALYZE</code></a>1157 was run and statistics are available to the planner.1158 </p></dd><dt id="APP-PSQL-META-COMMAND-DY"><span class="term"><code class="literal">\dy[+] [ <a class="link" href="app-psql.html#APP-PSQL-PATTERNS" title="Patterns"><em class="replaceable"><code>pattern</code></em></a> ]</code></span> <a href="#APP-PSQL-META-COMMAND-DY" class="id_link">#</a></dt><dd><p>1159 Lists event triggers.1160 If <em class="replaceable"><code>pattern</code></em>1161 is specified, only those event triggers whose names match the pattern1162 are listed.1163 If <code class="literal">+</code> is appended to the command name, each object1164 is listed with its associated description.1165 </p></dd><dt id="APP-PSQL-META-COMMAND-EDIT"><span class="term"><code class="literal">\e</code> or <code class="literal">\edit</code> <code class="literal"> [<span class="optional"> <em class="replaceable"><code>filename</code></em> </span>] [<span class="optional"> <em class="replaceable"><code>line_number</code></em> </span>] </code></span> <a href="#APP-PSQL-META-COMMAND-EDIT" class="id_link">#</a></dt><dd><p>1166 If <em class="replaceable"><code>filename</code></em> is1167 specified, the file is edited; after the editor exits, the file's1168 content is copied into the current query buffer. If no <em class="replaceable"><code>filename</code></em> is given, the current query1169 buffer is copied to a temporary file which is then edited in the same1170 fashion. Or, if the current query buffer is empty, the most recently1171 executed query is copied to a temporary file and edited in the same1172 fashion.1173 </p><p>1174 If you edit a file or the previous query, and you quit the editor without1175 modifying the file, the query buffer is cleared.1176 Otherwise, the new contents of the query buffer are re-parsed according to1177 the normal rules of <span class="application">psql</span>, treating the1178 whole buffer as a single line. Any complete queries are immediately1179 executed; that is, if the query buffer contains or ends with a1180 semicolon, everything up to that point is executed and removed from1181 the query buffer. Whatever remains in the query buffer is1182 redisplayed. Type semicolon or <code class="literal">\g</code> to send it,1183 or <code class="literal">\r</code> to cancel it by clearing the query buffer.1184 </p><p>1185 Treating the buffer as a single line primarily affects meta-commands:1186 whatever is in the buffer after a meta-command will be taken as1187 argument(s) to the meta-command, even if it spans multiple lines.1188 (Thus you cannot make meta-command-using scripts this way.1189 Use <code class="command">\i</code> for that.)1190 </p><p>1191 If a line number is specified, <span class="application">psql</span> will1192 position the cursor on the specified line of the file or query buffer.1193 Note that if a single all-digits argument is given,1194 <span class="application">psql</span> assumes it is a line number,1195 not a file name.1196 </p><div class="tip"><h3 class="title">Tip</h3><p>1197 See <a class="xref" href="app-psql.html#APP-PSQL-ENVIRONMENT" title="Environment">Environment</a>, below, for how to1198 configure and customize your editor.1199 </p></div></dd><dt id="APP-PSQL-META-COMMAND-ECHO"><span class="term"><code class="literal">\echo <em class="replaceable"><code>text</code></em> [ ... ]</code></span> <a href="#APP-PSQL-META-COMMAND-ECHO" class="id_link">#</a></dt><dd><p>1200 Prints the evaluated arguments to standard output, separated by