Cannot induce exit code 3 from psql

Question

The docs page states (emphasis mine)

Exit Status

psql returns 0 to the shell if it finished normally, 1 if a fatal error of its own occurs (e.g. out of memory, file not found), 2 if the connection to the server went bad and the session was not interactive, and 3 if an error occurred in a script and the variable ON_ERROR_STOP was set.

However, I seem to be unable to induce exit code 3.

bash-4.2$ uname -a
Linux mvpg-centos-76.vagrantup.com 3.10.0-957.21.3.el7.x86_64 #1 SMP Tue Jun 18 16:35:19 UTC 2019 x86_64 x86_64 x86_64 GNU/Linux
bash-4.2$ psql --version
psql (PostgreSQL) 10.12
bash-4.2$ psql -v ON_ERROR_STOP=1 -c 'select 1/0;'
ERROR: division by zero
bash-4.2$ echo $?
1
bash-4.2$ 

I've also reproduced this behaviour on FreeBSD 11.3 and Darwin 19.3. Am I misunderstanding the documentation or using a faulty syntax?

Answer 1

Got it to work a few ways:

postgres@ironforge:~$ cat onerrorstop.sql 
\set ON_ERROR_STOP on
select * from gurumeditationerror;
postgres@ironforge:~$ psql -f 'onerrorstop.sql'
psql:onerrorstop.sql:2: ERROR: relation "gurumeditationerror" does not exist
LINE 1: select * from gurumeditationerror;
 ^
postgres@ironforge:~$ echo $?
3
postgres@ironforge:~$

and:

postgres@ironforge:~$ echo "\set ON_ERROR_STOP on
> select * from smellyfarts;" | psql
ERROR: relation "smellyfarts" does not exist
LINE 1: select * from smellyfarts;
 ^
postgres@ironforge:~$ echo $?
3
postgres@ironforge:~$

and:

postgres@ironforge:~$ cat onerrorstop.sql 
select * from gurumeditationerror;
postgres@ironforge:~$ psql -v ON_ERROR_STOP=on -f 'onerrorstop.sql' 
psql:onerrorstop.sql:1: ERROR: relation "gurumeditationerror" does not exist
LINE 1: select * from gurumeditationerror;
 ^
postgres@ironforge:~$ echo $?
3
postgres@ironforge:~$ 
Version:
 postgres@ironforge:~$ psql --version
 psql (Post greySKULL) 9.5.19
 postgres@ironforge:~$

• user1822: @PeterVandivier: you could put that into .psqlrc postgresql.org/docs/current/app-psql.html#id-1.9.4.18.10
• Philᵀᴹ: @PeterVandivier yes, answer edited
• Peter Vandivier: ah... so it seems -v & -c together prevent exit code 3, but -v & -f allow it