Anything
you enter in psql that starts with a backslash without quotation marks is a psql meta-command that is processed by psql itself. These commands make psql more useful for administration or scripting. Meta commands are often referred to as forward slash or backslash commands.
The format of a psql command is the backslash, followed immediately by a command verb, then any argument. Arguments are separated from the command verb and from each other by any number of whitespace characters.
To include white space in an argument, you can quote it with single quotation marks. To include a single citation in an argument, type two single quotation marks inside text in quotation marks. Everything contained in single quotation marks is also subject to substitutions similar to C for n (new line), t (tab), b (backspace), r (carriage return), f (form advance), digits (octal) and xdigits (hexadecimal). A backslash that precedes any other character within the text in single quotation marks cites that unique character, whatever it is.
If the two uncited points (:) followed by a psql variable name appearing inside an argument, replaced by the value of the variable, as described in SQL interpolation below. The forms: ‘variable_name’ and ‘variable_name’ described there also work. The :{?variable_name} syntax allows you to test whether a variable is defined. It is replaced by TRUE or FALSE. Escaping the colon with an inverted bar protects it from substitution.
Within an argument, text enclosed in quotation marks (‘) is taken as a command line passed to the shell. The output of the command (with any new final lines deleted) replaces the text in quotation marks. Within the quoted text, no special citation or other processing occurs, except that occurrences of :variable_name where variable_name is a psql variable name are replaced by the value of the variable. In addition, the appearances of :’variable_name’ are replaced by the value of the appropriately cited variable to become a single shell command argument. (The latter form is almost always preferable, unless you’re quite sure what’s in the variable.) Because carriage return and line break characters cannot be quoted securely on all platforms, the ‘variable_name’ form prints an error message and does not replace the value of the variable when those characters appear in the value.
Some commands take an SQL identifier (such as a table name) as an argument. These arguments follow SQL syntax rules: letters without quotation marks are lowercase, while double quotation marks (“) protect letters from case-conversion and allow whitespace to be incorporated into the identifier. Within double quotation marks, paired double quotation marks are reduced to a single double quotation mark in the resulting name. For example, FOO”BAR”BAZ is interpreted as fooBARbaz, and “A strange name” becomes a “weird” name.
Argument parsing stops at the end of the line, or when another backslash without quotation marks is found. A backslash without quotation marks is taken as the beginning of a new meta-command. The special sequence \ (two backslashes) marks the end of the arguments and continues to parse the SQL commands, if any. That way, SQL and psql commands can be freely mixed on one line. But in any case, the arguments of a meta-command cannot continue beyond the end of the line.
Many of the
meta commands act on top of the current query buffer. This is simply a buffer containing any SQL command text that has been written but not yet sent to the server for execution. This will include the previous entry lines, as well as any text that appears before the metacommand on the same line.
The following metacommands are defined: