@@ -66,6 +66,26 @@ class DBType a where
66 typeInformation :: TypeInformation a
66 typeInformation :: TypeInformation a
69+-- | Haskell types that can be represented as expressions in a database. There
70+-- should be an instance of @DBType@ for all column types in your database
71+-- schema (e.g., @int@, @timestamptz@, etc).
73+-- Rel8 comes with stock instances for most default types in PostgreSQL, so you
74+-- should only need to derive instances of this class for custom database
75+-- types, such as types defined in PostgreSQL extensions, or custom domain
78+-- [ Creating @DBType@s using @newtype@ ]
80+-- Generalized newtype deriving can be used when you want use a @newtype@
81+-- around a database type for clarity and accuracy in your Haskell code. A
82+-- common example is to @newtype@ row id types:
84+-- >>> newtype UserId = UserId { toInt32 :: Int32 } deriving newtype (DBType)
86+-- You can now write queries using @UserId@ instead of @Int32@, which may help
87+-- avoid making bad joins. However, when SQL is generated, it will be as if you
88+-- just used integers (the type distinction does not impact query generation).
69instance DBType Bool where
89instance DBType Bool where
70 typeInformation = TypeInformation
90 typeInformation = TypeInformation
71 { encode = Opaleye.ConstExpr . Opaleye.BoolLit
91 { encode = Opaleye.ConstExpr . Opaleye.BoolLit