\pset

Description

This command sets options affecting the output of query result tables. option indicates which option is to be set. The semantics of value vary depending on the selected option. For some options, omitting value causes the option to be toggled or unset, as described under the particular option. If no such behavior is mentioned, then omitting value just results in the current setting being displayed.

Client

psql 18.6

Case-sensitive spelling

\pset

Usage

\pset [ option [ value ] ]

Related entries

• psql command-line options and complete manual

Documentation and source

• 18.6 English manual · app-psql.html

Compare versions

PostgreSQL 18 → 19: changed.

--- PostgreSQL 18
+++ PostgreSQL 19
@@ -1,5 +1,5 @@
 {
-  "definition": "This command sets options affecting the output of query result tables. option indicates which option is to be set. The semantics of value vary depending on the selected option. For some options, omitting value causes the option to be toggled or unset, as described under the particular option. If no such behavior is mentioned, then omitting value just results in the current setting being displayed. \\pset without any arguments displays the current status of all printing options. Adjustable printing options are: border The value must be a number. In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. In HTML format, this will translate directly into the border=... attribute. In most other formats only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense, and values above 2 will be treated the same as border = 2 . The latex and latex-longtable formats additionally allow a value of 3 to add dividing lines between data rows. columns Sets the target width for the wrapped format, and also the width limit for determining whether output is wide enough to require the pager or switch to the vertical display in expanded auto mode. Zero (the default) causes the target width to be controlled by the environment variable COLUMNS , or the detected screen width if COLUMNS is not set. In addition, if columns is zero then the wrapped format only affects screen output. If columns is nonzero then file and pipe output is wrapped to that width as well. csv_fieldsep Specifies the field separator to be used in CSV output format. If the separator character appears in a field's value, that field is output within double quotes, following standard CSV rules. The default is a comma. expanded (or x ) If value is specified it must be either on or off , which will enable or disable expanded mode, or auto . If value is omitted the command toggles between the on and off settings. When expanded mode is enabled, query results are displayed in two columns, with the column name on the left and the data on the right. This mode is useful if the data wouldn't fit on the screen in the normal “ horizontal ” mode. In the auto setting, the expanded mode is used whenever the query output has more than one column and is wider than the screen; otherwise, the regular mode is used. The auto setting is only effective in the aligned and wrapped formats. In other formats, it always behaves as if the expanded mode is off. fieldsep Specifies the field separator to be used in unaligned output format. That way one can create, for example, tab-separated output, which other programs might prefer. To set a tab as field separator, type \\pset fieldsep '\\t' . The default field separator is '|' (a vertical bar). fieldsep_zero Sets the field separator to use in unaligned output format to a zero byte. footer If value is specified it must be either on or off which will enable or disable display of the table footer (the ( n rows) count). If value is omitted the command toggles footer display on or off. format Sets the output format to one of aligned , asciidoc , csv , html , latex , latex-longtable , troff-ms , unaligned , or wrapped . Unique abbreviations are allowed. aligned format is the standard, human-readable, nicely formatted text output; this is the default. unaligned format writes all columns of a row on one line, separated by the currently active field separator. This is useful for creating output that might be intended to be read in by other programs, for example, tab-separated or comma-separated format. However, the field separator character is not treated specially if it appears in a column's value; so CSV format may be better suited for such purposes. csv format writes column values separated by commas, applying the quoting rules described in RFC 4180 . This output is compatible with the CSV format of the server's COPY command. A header line with column names is generated unless the tuples_only parameter is on . Titles and footers are not printed. Each row is terminated by the system-dependent end-of-line character, which is typically a single newline ( \\n ) for Unix-like systems or a carriage return and newline sequence ( \\r\\n ) for Microsoft Windows. Field separator characters other than comma can be selected with \\pset csv_fieldsep . wrapped format is like aligned but wraps wide data values across lines to make the output fit in the target column width. The target width is determined as described under the columns option. Note that psql will not attempt to wrap column header titles; therefore, wrapped format behaves the same as aligned if the total width needed for column headers exceeds the target. The asciidoc , html , latex , latex-longtable , and troff-ms formats put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! This might not be necessary in HTML , but in LaTeX you must have a complete document wrapper. The latex format uses LaTeX 's tabular environment. The latex-longtable format requires the LaTeX longtable and booktabs packages. linestyle Sets the border line drawing style to one of ascii , old-ascii , or unicode . Unique abbreviations are allowed. (That would mean one letter is enough.) The default setting is ascii . This option only affects the aligned and wrapped output formats. ascii style uses plain ASCII characters. Newlines in data are shown using a + symbol in the right-hand margin. When the wrapped format wraps data from one line to the next without a newline character, a dot ( . ) is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. old-ascii style uses plain ASCII characters, using the formatting style used in PostgreSQL 8.4 and earlier. Newlines in data are shown using a : symbol in place of the left-hand column separator. When the data is wrapped from one line to the next without a newline character, a ; symbol is used in place of the left-hand column separator. unicode style uses Unicode box-drawing characters. Newlines in data are shown using a carriage return symbol in the right-hand margin. When the data is wrapped from one line to the next without a newline character, an ellipsis symbol is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. When the border setting is greater than zero, the linestyle option also determines the characters with which the border lines are drawn. Plain ASCII characters work everywhere, but Unicode characters look nicer on displays that recognize them. null Sets the string to be printed in place of a null value. The default is to print nothing, which can easily be mistaken for an empty string. For example, one might prefer \\pset null '(null)' . numericlocale If value is specified it must be either on or off which will enable or disable display of a locale-specific character to separate groups of digits to the left of the decimal marker. If value is omitted the command toggles between regular and locale-specific numeric output. pager Controls use of a pager program for query and psql help output. When the pager option is off , the pager program is not used. When the pager option is on , the pager is used when appropriate, i.e., when the output is to a terminal and will not fit on the screen. The pager option can also be set to always , which causes the pager to be used for all terminal output regardless of whether it fits on the screen. \\pset pager without a value toggles pager use on and off. If the environment variable PSQL_PAGER or PAGER is set, output to be paged is piped to the specified program. Otherwise a platform-dependent default program (such as more ) is used. When using the \\watch command to execute a query repeatedly, the environment variable PSQL_WATCH_PAGER is used to find the pager program instead, on Unix systems. This is configured separately because it may confuse traditional pagers, but can be used to send output to tools that understand psql 's output format (such as pspg --stream ). pager_min_lines If pager_min_lines is set to a number greater than the page height, the pager program will not be called unless there are at least this many lines of output to show. The default setting is 0. recordsep Specifies the record (line) separator to use in unaligned output format. The default is a newline character. recordsep_zero Sets the record separator to use in unaligned output format to a zero byte. tableattr (or T ) In HTML format, this specifies attributes to be placed inside the table tag. This could for example be cellpadding or bgcolor . Note that you probably don't want to specify border here, as that is already taken care of by \\pset border . If no value is given, the table attributes are unset. In latex-longtable format, this controls the proportional width of each column containing a left-aligned data type. It is specified as a whitespace-separated list of values, e.g., '0.2 0.2 0.6' . Unspecified output columns use the last specified value. title (or C ) Sets the table title for any subsequently printed tables. This can be used to give your output descriptive tags. If no value is given, the title is unset. tuples_only (or t ) If value is specified it must be either on or off which will enable or disable tuples-only mode. If value is omitted the command toggles between regular and tuples-only output. Regular output includes extra information such as column headers, titles, and various footers. In tuples-only mode, only actual table data is shown. unicode_border_linestyle Sets the border drawing style for the unicode line style to one of single or double . unicode_column_linestyle Sets the column drawing style for the unicode line style to one of single or double . unicode_header_linestyle Sets the header drawing style for the unicode line style to one of single or double . xheader_width Sets the maximum width of the header for expanded output to one of full (the default value), column , page , or an integer value . full : the expanded header is not truncated, and will be as wide as the widest output line. column : truncate the header line to the width of the first column. page : truncate the header line to the terminal width. integer value : specify the exact maximum width of the header line. Illustrations of how these different formats look can be seen in Examples , below. Tip There are various shortcut commands for \\pset . See \\a , \\C , \\f , \\H , \\t , \\T , and \\x .",
+  "definition": "This command sets options affecting the output of query result tables. option indicates which option is to be set. The semantics of value vary depending on the selected option. For some options, omitting value causes the option to be toggled or unset, as described under the particular option. If no such behavior is mentioned, then omitting value just results in the current setting being displayed. \\pset without any arguments displays the current status of all printing options. Adjustable printing options are: border The value must be a number. In general, the higher the number the more borders and lines the tables will have, but details depend on the particular format. In HTML format, this will translate directly into the border=... attribute. In most other formats only values 0 (no border), 1 (internal dividing lines), and 2 (table frame) make sense, and values above 2 will be treated the same as border = 2 . The latex and latex-longtable formats additionally allow a value of 3 to add dividing lines between data rows. columns Sets the target width for the wrapped format, and also the width limit for determining whether output is wide enough to require the pager or switch to the vertical display in expanded auto mode. Zero (the default) causes the target width to be controlled by the environment variable COLUMNS , or the detected screen width if COLUMNS is not set. In addition, if columns is zero then the wrapped format only affects screen output. If columns is nonzero then file and pipe output is wrapped to that width as well. csv_fieldsep Specifies the field separator to be used in CSV output format. If the separator character appears in a field's value, that field is output within double quotes, following standard CSV rules. The default is a comma. display_false Sets the string to be printed in place of a false value. The default is to print f . display_true Sets the string to be printed in place of a true value. The default is to print t . expanded (or x ) If value is specified it must be either on or off , which will enable or disable expanded mode, or auto . If value is omitted the command toggles between the on and off settings. When expanded mode is enabled, query results are displayed in two columns, with the column name on the left and the data on the right. This mode is useful if the data wouldn't fit on the screen in the normal “ horizontal ” mode. In the auto setting, the expanded mode is used whenever the query output has more than one column and is wider than the screen; otherwise, the regular mode is used. The auto setting is only effective in the aligned and wrapped formats. In other formats, it always behaves as if the expanded mode is off. fieldsep Specifies the field separator to be used in unaligned output format. That way one can create, for example, tab-separated output, which other programs might prefer. To set a tab as field separator, type \\pset fieldsep '\\t' . The default field separator is '|' (a vertical bar). fieldsep_zero Sets the field separator to use in unaligned output format to a zero byte. footer If value is specified it must be either on or off which will enable or disable display of the table footer (the ( n rows) count). If value is omitted the command toggles footer display on or off. format Sets the output format to one of aligned , asciidoc , csv , html , latex , latex-longtable , troff-ms , unaligned , or wrapped . Unique abbreviations are allowed. aligned format is the standard, human-readable, nicely formatted text output; this is the default. unaligned format writes all columns of a row on one line, separated by the currently active field separator. This is useful for creating output that might be intended to be read in by other programs, for example, tab-separated or comma-separated format. However, the field separator character is not treated specially if it appears in a column's value; so CSV format may be better suited for such purposes. csv format writes column values separated by commas, applying the quoting rules described in RFC 4180 . This output is compatible with the CSV format of the server's COPY command. A header line with column names is generated unless the tuples_only parameter is on . Titles and footers are not printed. Each row is terminated by the system-dependent end-of-line character, which is typically a single newline ( \\n ) for Unix-like systems or a carriage return and newline sequence ( \\r\\n ) for Microsoft Windows. Field separator characters other than comma can be selected with \\pset csv_fieldsep . wrapped format is like aligned but wraps wide data values across lines to make the output fit in the target column width. The target width is determined as described under the columns option. Note that psql will not attempt to wrap column header titles; therefore, wrapped format behaves the same as aligned if the total width needed for column headers exceeds the target. The asciidoc , html , latex , latex-longtable , and troff-ms formats put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! This might not be necessary in HTML , but in LaTeX you must have a complete document wrapper. The latex format uses LaTeX 's tabular environment. The latex-longtable format requires the LaTeX longtable and booktabs packages. linestyle Sets the border line drawing style to one of ascii , old-ascii , or unicode . Unique abbreviations are allowed. (That would mean one letter is enough.) The default setting is ascii . This option only affects the aligned and wrapped output formats. ascii style uses plain ASCII characters. Newlines in data are shown using a + symbol in the right-hand margin. When the wrapped format wraps data from one line to the next without a newline character, a dot ( . ) is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. old-ascii style uses plain ASCII characters, using the formatting style used in PostgreSQL 8.4 and earlier. Newlines in data are shown using a : symbol in place of the left-hand column separator. When the data is wrapped from one line to the next without a newline character, a ; symbol is used in place of the left-hand column separator. unicode style uses Unicode box-drawing characters. Newlines in data are shown using a carriage return symbol in the right-hand margin. When the data is wrapped from one line to the next without a newline character, an ellipsis symbol is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. When the border setting is greater than zero, the linestyle option also determines the characters with which the border lines are drawn. Plain ASCII characters work everywhere, but Unicode characters look nicer on displays that recognize them. null Sets the string to be printed in place of a null value. The default is to print nothing, which can easily be mistaken for an empty string. For example, one might prefer \\pset null '(null)' . numericlocale If value is specified it must be either on or off which will enable or disable display of a locale-specific character to separate groups of digits to the left of the decimal marker. If value is omitted the command toggles between regular and locale-specific numeric output. pager Controls use of a pager program for query and psql help output. When the pager option is off , the pager program is not used. When the pager option is on , the pager is used when appropriate, i.e., when the output is to a terminal and will not fit on the screen. The pager option can also be set to always , which causes the pager to be used for all terminal output regardless of whether it fits on the screen. \\pset pager without a value toggles pager use on and off. If the environment variable PSQL_PAGER or PAGER is set, output to be paged is piped to the specified program. Otherwise a platform-dependent default program (such as more ) is used. When using the \\watch command to execute a query repeatedly, the environment variable PSQL_WATCH_PAGER is used to find the pager program instead, on Unix systems. This is configured separately because it may confuse traditional pagers, but can be used to send output to tools that understand psql 's output format (such as pspg --stream ). pager_min_lines If pager_min_lines is set to a number greater than the page height, the pager program will not be called unless there are at least this many lines of output to show. The default setting is 0. recordsep Specifies the record (line) separator to use in unaligned output format. The default is a newline character. recordsep_zero Sets the record separator to use in unaligned output format to a zero byte. tableattr (or T ) In HTML format, this specifies attributes to be placed inside the table tag. This could for example be cellpadding or bgcolor . Note that you probably don't want to specify border here, as that is already taken care of by \\pset border . If no value is given, the table attributes are unset. In latex-longtable format, this controls the proportional width of each column containing a left-aligned data type. It is specified as a whitespace-separated list of values, e.g., '0.2 0.2 0.6' . Unspecified output columns use the last specified value. title (or C ) Sets the table title for any subsequently printed tables. This can be used to give your output descriptive tags. If no value is given, the title is unset. tuples_only (or t ) If value is specified it must be either on or off which will enable or disable tuples-only mode. If value is omitted the command toggles between regular and tuples-only output. Regular output includes extra information such as column headers, titles, and various footers. In tuples-only mode, only actual table data is shown. unicode_border_linestyle Sets the border drawing style for the unicode line style to one of single or double . unicode_column_linestyle Sets the column drawing style for the unicode line style to one of single or double . unicode_header_linestyle Sets the header drawing style for the unicode line style to one of single or double . xheader_width Sets the maximum width of the header for expanded output to one of full (the default value), column , page , or an integer value . full : the expanded header is not truncated, and will be as wide as the widest output line. column : truncate the header line to the width of the first column. page : truncate the header line to the terminal width. integer value : specify the exact maximum width of the header line. Illustrations of how these different formats look can be seen in Examples , below. Tip There are various shortcut commands for \\pset . See \\a , \\C , \\f , \\H , \\t , \\T , and \\x .",
   "modifiers": [],
   "signature": "\\pset [ option [ value ] ]",
   "spellings": [

Compares recorded interfaces and attributes. Source fingerprints and build metadata are excluded; an absent sample is not proof of the introduction or removal release.

Related entries

• \C
• \H
• \T
• \a
• \crosstabview
• \f
• \html
• \o
• \out
• \t
• \x