@@ -45,6 +45,39 @@ import Data.Time.LocalTime ( TimeOfDay, LocalTime )
45import Data.UUID ( UUID )
45import Data.UUID ( UUID )
48+-- | Database types that can be compared for equality in queries. If a type is
49+-- an instance of 'DBEq', it means we can compare expressions for equality
50+-- using the SQL @=@ operator.
52+-- [ @DBEq@ with @newtype@s ]
54+-- Like with 'Rel8.DBType', @DBEq@ plays well with generalized newtype
55+-- deriving. The example given for @DBType@ added a @UserId@ @newtype@, but
56+-- without a @DBEq@ instance won't actually be able to use that in joins or
57+-- where-clauses, because it lacks equality. We can add this by changing our
58+-- @newtype@ definition to:
60+-- >>> newtype UserId = UserId { toInt32 :: Int32 } deriving newtype (DBType, DBEq)
62+-- This will re-use the equality logic for @Int32@, which is to just use the
65+-- [ @DBEq@ with @DeriveAnyType@ ]
67+-- You can also use @DBEq@ with the @DeriveAnyType@ extension to easily add
68+-- equality to your type, assuming that @=@ is sufficient on @DBType@ encoded
69+-- values. Extending the example from 'Rel8.ReadShow''s 'Rel8.DBType' instance,
70+-- we could add equality to @Color@ by writing:
73+-- data Color = Red | Green | Blue | Purple | Gold
74+-- deriving (Generic, Show, Read, DBEq)
75+-- deriving DBType via ReadShow Color
78+-- This means @Color@s will be treated as the literal strings @"Red"@,
79+-- @"Green"@, etc, in the database, and they can be compared for equality by
48type DBEq :: Type -> Constraint
81type DBEq :: Type -> Constraint
49class DBType a => DBEq a
82class DBType a => DBEq a