From 772e4368efc931dd0280a20ecaf40dc80ecd6979 Mon Sep 17 00:00:00 2001 From: Shinya Kato Date: Tue, 18 Aug 2026 22:37:47 +0900 Subject: [PATCH v2 2/2] doc: Describe how a NULL-valued pgbench variable is used The pgbench expression language has had a null value since \set gained the NULL constant, but nothing said how such a variable behaves outside an expression. Two points surprise users. A variable holding NULL is inserted into an SQL command as the unquoted word NULL, so in the extended and prepared query modes it reaches the server as the string "NULL" rather than as an SQL null parameter. A variable whose string value is NULL is also indistinguishable from the null value in expressions, because makeVariableValue() accepts that spelling in any letter case. Both apply to every variable regardless of how it was set, so this goes next to the description of the variable-substitution facility rather than under an individual meta command. This documents existing behavior and changes no code. Author: Shinya Kato Reviewed-by: Kyotaro Horiguchi Discussion: https://postgr.es/m/CAOzEurT9J9QMmpJt_8pWZCziNYCUHOD=c-hoccOVYJLc_VxVRg@mail.gmail.com --- doc/src/sgml/ref/pgbench.sgml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index 9688527c955..7a5d26e5b33 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -1169,6 +1169,16 @@ pgbench options d statement. + + A variable holding NULL is inserted into an SQL command + as the unquoted word NULL. In the + extended and prepared query modes, + however, it is passed as the string NULL rather than as + an SQL null parameter. Conversely, a variable whose string value is + NULL, in any letter case, is treated as + NULL in an expression. + + pgbench Automatic Variables -- 2.47.3