From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Sun, 4 Jun 2023 23:18:03 +0000 (+0200)
Subject: docs: add notes about using IS with placeholders
X-Git-Tag: pool-3.2.0~95
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=f09eb30f6f7bcf702fb4e42a1a9349f9a9d34b01;p=thirdparty%2Fpsycopg.git

docs: add notes about using IS with placeholders

See #582.
---

diff --git a/docs/basic/from_pg2.rst b/docs/basic/from_pg2.rst
index 83dfd3dc6..c04be9786 100644
--- a/docs/basic/from_pg2.rst
+++ b/docs/basic/from_pg2.rst
@@ -234,6 +234,43 @@ the :sql:`IN` operator instead.
     #id-1.5.8.30.16
 
 
+.. _is-null:
+
+You cannot use ``IS %s``
+------------------------
+
+You cannot use :sql:`IS %s` or :sql:`IS NOT %s`::
+
+    >>> conn.execute("SELECT * FROM foo WHERE field IS %s", [None])
+    Traceback (most recent call last):
+    ...
+    psycopg.errors.SyntaxError: syntax error at or near "$1"
+    LINE 1: SELECT * FROM foo WHERE field IS $1
+                                         ^
+
+This is probably caused by the fact that :sql:`IS` is not a binary operator in
+PostgreSQL; rather, :sql:`IS NULL` and :sql:`IS NOT NULL` are unary operators
+and you cannot use :sql:`IS` with anything else on the right hand side.
+Testing in psql:
+
+.. code:: text
+
+    =# SELECT 10 IS 10;
+    ERROR:  syntax error at or near "10"
+    LINE 1: select 10 is 10;
+                         ^
+
+What you can do instead is to use the `IS DISTINCT FROM operator`__, which
+will gladly accept a placeholder::
+
+    >>> conn.execute("SELECT * FROM foo WHERE field IS NOT DISTINCT FROM %s", [None])
+
+.. __: https://www.postgresql.org/docs/current/functions-comparison.html
+
+Analogously you can use :sql:`IS DISTINCT FROM %s` as a parametric version of
+:sql:`IS NOT %s`.
+
+
 .. _diff-adapt:
 
 Different adaptation system