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:~$