Skip to main content
0 reactions

How to Customize psql with .psqlrc

Featured card for the guide Customize psql with .psqlrc, showing a terminal with the timing, expanded display and null display settings, and the new postgres@postgres=# prompt they produce.
Customize psql with .psqlrc

Every time psql starts, it reads a settings file named .psqlrc in your home folder. Put your favourite psql commands in it, and every session starts set up the way you like.

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

Syntax

Syntax (one line in ~/.psqlrc)Plain text
\command [ value ]
  • Each line of the file is a psql command, typed exactly as you would at the postgres=# prompt.
  • psql runs the lines in order after it connects, and before it shows you the prompt.
  • Lines usually hold \set, \pset and similar settings.

The psql documentation (opens in a new tab) describes the file in its Files section.

Step 1: Create Your .psqlrc

In Terminal, open the file in nano, a simple text editor:

TerminalBash
nano ~/.psqlrc

Type these four lines, then press Control-O and Return to save, and Control-X to close nano:

~/.psqlrcPlain text
\timing on
\x auto
\pset null '(null)'
\set PROMPT1 '%n@%/%R%# '
  • \timing on: shows how long each statement takes.
  • \x auto: shows wide results as lists, one line per column.
  • \pset null '(null)': shows empty values (NULL) as (null) instead of a blank.
  • \set PROMPT1 '%n@%/%R%# ': makes the prompt show your user name and the database, as in postgres@postgres=#.

Step 2: Start psql

TerminalBash
psql -U postgres
OutputPlain text
Password for user postgres:
Timing is on.
Expanded display is used automatically.
Null display is "(null)".
psql (19.0)
Type "help" for help.

postgres@postgres=#

The first lines confirm each setting from the file, and the prompt now shows the user and the database.

Step 3: See the Settings at Work

postgres@postgres=#SQL
SELECT NULL AS nothing, 42 AS answer;
OutputPlain text
 nothing | answer
---------+--------
 (null)  |     42
(1 row)

Time: 0.365 ms

The empty value shows as (null), and the Time: line comes from \timing on.

Step 4: Start psql Without Your Settings

To start a session without the file, add -X:

TerminalBash
psql -U postgres -X
OutputPlain text
Password for user postgres:
psql (19.0)
Type "help" for help.

postgres=#

The prompt is back to postgres=#, and no settings were applied.

Common Mistakes

MistakeWhat happensDo this instead
A typo in the file, such as \timming onpsql starts, but first prints psql:/Users/user/.psqlrc:1: error: invalid command \timmingFix that line in ~/.psqlrc: the message gives its line number.

FAQ

Can I put SQL in .psqlrc?

Yes. The documentation says the file is typically used for \set and SET commands, and SET is SQL that changes a setting for your session.

Can I keep the file somewhere else?

Yes. Set the PSQLRC environment variable to the file’s path, as the psql documentation (opens in a new tab) describes.

Conclusion

Write psql commands into ~/.psqlrc, one per line, and psql runs them every time it starts. Start with -X when you want a session without them.

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