Improve error messages around getBy with NULLABLE fields

persistent/ChangeLog.md

@@ -1,5 +1,10 @@
 # Changelog for persistent
 
+# Unreleased 
+* [#1608](https://github.com/yesodweb/persistent/pull/1608)
+  * Improves documentation on getBy with nullable fields
+  * Updates the warning text present when you try to make a Unique field that is nullable
+
 # 2.17.1.0
 
 * [#1601](https://github.com/yesodweb/persistent/pull/1601)

persistent/Database/Persist/Class/PersistUnique.hs

@@ -57,6 +57,8 @@ import Database.Persist.Types
 class (PersistStoreRead backend) => PersistUniqueRead backend where
     -- | Get a record by unique key, if available. Returns also the identifier.
     --
+    -- If your unique key contains a nullable field, then, by default, getBy will not match if any of the fields are NULL.
+    --
     -- === __Example usage__
     --
     -- With <#schema-persist-unique-1 schema-1> and <#dataset-persist-unique-1 dataset-1>:

persistent/Database/Persist/TH/Internal.hs

@@ -1524,7 +1524,8 @@ mkUnique mps entityMap entDef (UniqueDef constr _ fields attrs) =
             , "column in question.  If you understand this feature of SQL and still "
             , "intend to add a uniqueness constraint here,    *** Use a \"!force\" "
             , "attribute on the end of the line that defines your uniqueness "
-            , "constraint in order to disable this check. ***"
+            , "constraint in order to disable this check. ***\n"
+            , "By default, this means using `getBy`, `insertBy`, or anything that fetches by unique key will NOT match if any of the fields are NULL."
             ]
 
 -- | This function renders a Template Haskell 'Type' for an 'UnboundFieldDef'.