@@ -131,11 +131,11 @@ newtype Only a = Only {
131131-- 1. Use postgresql-simple's 'Values' type instead, which can handle the
132132-- empty case correctly. Note however that while specifying the
133133-- postgresql type @"int4"@ is mandatory in the empty case, specifying
134−-- the haskell type @[Only Int]@ would not normally be needed in
134+-- the haskell type @Values (Only Int)@ would not normally be needed in
135135-- realistic use cases.
136136--
137137-- > query c "select * from whatever where id not in ?"
138−-- > (Only (Values "int4") ([] :: [Only Int]))
138+-- > (Only (Values ["int4"] [] :: Values (Only Int)))
139139--
140140--
141141-- 2. Use sql's @COALESCE@ operator to turn a logical @null@ into the correct
@@ -147,6 +147,14 @@ newtype Only a = Only {
147147--
148148-- > query c "select * from whatever where coalesce(id IN ?, FALSE)"
149149-- > (Only (In ([] :: [Int])))
150+--
151+-- Note that at as of PostgreSQL 9.4 at least, the query planner cannot
152+-- see inside the @COALESCE@ operator, so if you have an index on @id@
153+-- then you probably don't want to write the last example with @COALESCE@,
154+-- which would result in a table scan. There are further caveats if
155+-- @id@ can be null or you want null treated sensibly as a component
156+-- of @IN@ or @NOT IN@.
157+
150158newtype In a = In a
151159 deriving (Eq, Ord, Read, Show, Typeable, Functor)
152160