Document hint for comparing a Maybe value with nullable, treating NULL as comparable value

[robinp]

Hello,

This is more to leave an issue footprint for future readers and self, but might be nice if a hint ended up in the haddocks intro section as well.

The problem

I, as a unit-radius user, ended up trying to compare a nullable value with a bound Maybe value in a query using plain equality, like

PG.query conn "SELECT ... FROM ... WHERE nullable_thing = ?" (PG.Only mbSomething)

Which understandably doesn't work for a NULL - Nothing pair, since SQL's NULL is contagious, once it is a parameter of a comparison, the whole result is NULL AFAIU, instead of a match.

The trick that saves the day

https://www.postgresql.org/docs/current/functions-comparison.html documents

datatype IS NOT DISTINCT FROM datatype → boolean
Equal, treating null as a comparable value.
1 IS NOT DISTINCT FROM NULL → f (rather than NULL)
NULL IS NOT DISTINCT FROM NULL → t (rather than NULL)

So changing = to IS NOT DISTINCT FROM in the query helped. So it is advisable to use if one wants to strictly treat a nullable sql type as a Maybe Haskell-type, for comparison.