Skip to main content
0 reactions

How to Use Expanded Display in psql

Featured card titled Use Expanded Display in psql, with a terminal window showing \x on, the -[ RECORD 1 ]- line of an expanded result, \x auto and \gx.
Show wide psql results as lists with expanded display.

When a row has many columns, psql prints it as one very long line that wraps or runs off the side of your window. Expanded display shows each row as a list instead: one line per column, with its name on the left.

Every command and output on this page is real, from PostgreSQL 19 on macOS.

Syntax

SyntaxPlain text
\x [ on | off | auto ]
  • \x: on its own, switches expanded display on if it’s off, and off if it’s on.
  • on or off: sets it either way.
  • auto: lets psql decide for each result, and expands only the ones too wide for your window.
  • \gx: ends a single query instead of the semicolon, and shows just that result expanded.

Both are described in the psql documentation (opens in a new tab).

Step 1: Look at a Wide Row

Connect with psql, as Part 2 of the PostgreSQL Tutorial shows. This query returns one made-up row with six columns, and no table is needed:

postgres=#SQL
SELECT 1 AS id, 'Asha Rao' AS name, 'Pune' AS city, '2024-03-15' AS joined, 'Mystery and science fiction' AS favourite_genres, 'Reads two books a week, runs the club newsletter and hosts the monthly meeting' AS note;
OutputPlain text
 id |   name   | city |   joined   |      favourite_genres       |                                      note
----+----------+------+------------+-----------------------------+--------------------------------------------------------------------------------
  1 | Asha Rao | Pune | 2024-03-15 | Mystery and science fiction | Reads two books a week, runs the club newsletter and hosts the monthly meeting
(1 row)

The row is wider than most windows, so it’s hard to tell which value belongs to which column.

Step 2: Turn On Expanded Display

postgres=#Plain text
\x on
OutputPlain text
Expanded display is on.

Run the same query again:

postgres=#SQL
SELECT 1 AS id, 'Asha Rao' AS name, 'Pune' AS city, '2024-03-15' AS joined, 'Mystery and science fiction' AS favourite_genres, 'Reads two books a week, runs the club newsletter and hosts the monthly meeting' AS note;
OutputPlain text
-[ RECORD 1 ]----+-------------------------------------------------------------------------------
id               | 1
name             | Asha Rao
city             | Pune
joined           | 2024-03-15
favourite_genres | Mystery and science fiction
note             | Reads two books a week, runs the club newsletter and hosts the monthly meeting

Each column now has its own line, and -[ RECORD 1 ]- marks the start of the row.

Step 3: Let psql Decide with auto

postgres=#Plain text
\x auto
OutputPlain text
Expanded display is used automatically.

With auto, psql expands a result only when it’s too wide for your window. This row is, so it comes out expanded:

postgres=#SQL
SELECT 1 AS id, 'Asha Rao' AS name, 'Pune' AS city, '2024-03-15' AS joined, 'Mystery and science fiction' AS favourite_genres, 'Reads two books a week, runs the club newsletter and hosts the monthly meeting' AS note;
OutputPlain text
-[ RECORD 1 ]----+-------------------------------------------------------------------------------
id               | 1
name             | Asha Rao
city             | Pune
joined           | 2024-03-15
favourite_genres | Mystery and science fiction
note             | Reads two books a week, runs the club newsletter and hosts the monthly meeting

Step 4: Expand Just One Query with \gx

With expanded display off, end the query with \gx instead of the semicolon:

postgres=#SQL
SELECT 1 AS id, 'Asha Rao' AS name, 'Pune' AS city, '2024-03-15' AS joined, 'Mystery and science fiction' AS favourite_genres, 'Reads two books a week, runs the club newsletter and hosts the monthly meeting' AS note \gx
OutputPlain text
-[ RECORD 1 ]----+-------------------------------------------------------------------------------
id               | 1
name             | Asha Rao
city             | Pune
joined           | 2024-03-15
favourite_genres | Mystery and science fiction
note             | Reads two books a week, runs the club newsletter and hosts the monthly meeting

Only this result is expanded. The next query comes out as a normal table again.

Common Mistakes

MistakeWhat happensDo this instead
A typo such as \xxinvalid command \xx Try \? for help.The command is \x.

Troubleshooting

ProblemCauseFix
A wide result opens in a screen with : on the last lineThe result is wider than your window, so psql shows it in its pagerPress q, then turn on expanded display with \x and run the query again.

FAQ

Does expanded display change my data?

No. It only changes how psql prints results. The rows in the database stay the same.

Can I make auto the default?

Yes. Put \x auto in your psql settings file, .psqlrc, which psql reads every time it starts, as How to Customize psql with .psqlrc shows.

Conclusion

Type \x to switch expanded display on or off, \x auto to let psql expand only wide results, and end a query with \gx to expand just that one.

Additional Resources

Postgres, PostgreSQL and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada, and used with their permission.

0 comments