diff --git a/persistent/ChangeLog.md b/persistent/ChangeLog.md
index 1baedd22b..e0c208d03 100644
--- a/persistent/ChangeLog.md
+++ b/persistent/ChangeLog.md
@@ -1,9 +1,14 @@
 # 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.18.0.0
 
 * [#1610](https://github.com/yesodweb/persistent/pull/1610)
-  * Added `NoAction` as a `CascadeAction` 
+  * Added `NoAction` as a `CascadeAction`
 
 # 2.17.1.0
 
diff --git a/persistent/Database/Persist/Class/PersistUnique.hs b/persistent/Database/Persist/Class/PersistUnique.hs
index 0f981ab85..574cdda6a 100644
--- a/persistent/Database/Persist/Class/PersistUnique.hs
+++ b/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>:
diff --git a/persistent/Database/Persist/TH/Internal.hs b/persistent/Database/Persist/TH/Internal.hs
index f2226b429..c694190c8 100644
--- a/persistent/Database/Persist/TH/Internal.hs
+++ b/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'.