@@ -117,6 +117,36 @@ newtype Only a = Only {
117-- Example:
117-- Example:
119-- > query c "select * from whatever where id in ?" (Only (In [3,4,5]))
119-- > query c "select * from whatever where id in ?" (Only (In [3,4,5]))
121+-- Note that @IN []@ expands to @(null)@, which works as expected in
122+-- the query above, but evaluates to the logical null value on every
123+-- row instead of @TRUE@. This means that changing the query above
124+-- to @... id NOT in ?@ and supplying the empty list as the parameter
125+-- returns zero rows, instead of all of them as one would expect.
127+-- Since postgresql doesn't seem to provide a syntax for actually specifying
128+-- an empty list, which could solve this completely, there are two
129+-- workarounds worth mentioning, namely:
131+-- 1. Use postgresql-simple's 'Values' instead, which can handle the
132+-- empty case correctly. Note however that while specifying the
133+-- postgresql type @"int4"@ is mandatory in the empty case, specifying
134+-- the haskell type @[Int]@ would not normally be needed in realistic
137+-- > query c "select * from whatever where id not in ?"
138+-- > (Only (Values "int4") ([] :: [Int]))
141+-- 2. Use sql's @COALESCE@ operator to turn a logical @null@ into the correct
142+-- boolean. Note however that the correct boolean depends on the use
145+-- > query c "select * from whatever where coalesce(id NOT in ?, TRUE)"
146+-- > (Only (In ([] :: [Int])))
148+-- > query c "select * from whatever where coalesce(id IN ?, FALSE)"
149+-- > (Only (In ([] :: [Int])))
120newtype In a = In a
150newtype In a = In a
121 deriving (Eq, Ord, Read, Show, Typeable, Functor)
151 deriving (Eq, Ord, Read, Show, Typeable, Functor)