@@ -1,5 +1,3 @@
1−This documentation covers the main concepts that are used throughout Rel8.
2−
31``DBType``
42==========
53
@@ -114,114 +112,39 @@ this type with Rel8 by writing::
114112Here we used ``JSONBEncoded``, which will serialize to PostgreSQL ``jsonb``
115113(binary JSON) type, which is generally the best choice.
116114
117−``Expr`` and ``Sql``
118−====================
119−
120−``Expr``
121−--------
122−
123−Now that we've seen how types are bridged between a database and Haskell via
124−``DBType``, we can start looking at how expressions are modelled. In Rel8, any
125−expression will be a value of the form ``Expr a``, where ``a`` is the type of
126−the expression. For example, the SQL expression ``user.id = 42`` is an ``Expr
127−Bool``, and the subexpressions ``user.id`` and ``42`` might be ``Expr
128−UserId``\s.
129−
130−``Expr``\s are usually created by combining other ``Expr``\s together, like
131−using numeric operations like `+` and `*`, or by quoting Haskell values into
132−queries with ``lit``. Continuing with the example of ``user.id = 42``, we can
133−write this in Rel8 as::
134−
135− userId ==. lit (UserId 42)
136−
137−Here it's assumed that a ``userId :: Expr UserId`` expression is already in
138−scope, and we can compare that against another ``Expr UserId`` using the ``==.``
139−operator (which is like Haskell's normal ``==`` operator, but lifted to work on
140−``Expr``). The expression ``lit (UserId 42)`` quotes the Haskell term ``UserId
141−42`` literally as the SQL expression ``42``. This particular encoding is chosen
142−because ``UserId`` is simply a ``newtype`` around ``Int64``.
143−
144−``null``
145−--------
146−
147−So far we've only talked about ``DBType``, which represents database types
148−*excluding* ``null``. Rel8 chooses this encoding because ``null`` is rather
149−special in SQL, and doesn't really constitute a distinct type. For example,
150−there is no SQL notion of "stacking" nulls - which is to say a type like ``Maybe
151−(Maybe UserId))`` has no real analogous type in SQL.
152−
153−Of course, as ``null`` is pervasive in SQL queries, Rel8 does support ``null`` -
154−simply wrap up your type in ``Maybe``. ``Nothing`` will be translated as
155−``null``, and ``Just`` is used to represent non-null values.
156−
157−Rel8 comes with a set of functions to work with ``null`` values thash should
158−feel familiar to Haskell programmers:
159−
160−* ``null`` creates null values (you can also use ``lit Nothing``).
161−* ``nullify`` turns an ``Expr a`` into a ``Expr (Maybe a)`` (like ``Just``).
162−* ``nullable`` allows you to eliminate null values, like the ``maybe`` function.
163−* ``isNull`` and ``isNonNull`` work like ``isNothing`` and ``isJust``,
164− respectively.
165−* ``mapNullable`` is like ``fmap`` for ``Maybe``, and allows you to map over
166− non-null values.
167−* ``liftOpNullable`` is like ``liftA2`` for ``Maybe``, and allows you to combine
168− expressions together, given a way to combine non-null expressions.
169−
170−``SQL`` and null-polymorphic expressions
171−----------------------------------------
172−
173−Through the API reference documentation for Rel8, you might encounter the
174−``Sql`` type class. For example, if we look at the type of ``litExpr``, we
175−have::
176−
177− litExpr :: Sql DBType a => a -> Expr a
178−
179−Here ``Sql DBType a`` means that ``a`` can either be literally a type that has
180−an instance of ``DBType`` (like ``UserId`` or ``Bool``), *or* that same type
181−wrapped in ``Maybe`` (so ``Maybe UserId`` or ``Maybe Bool``). ``Maybe`` here
182−encodes the SQL concept of ``null``.
183−
184−Some functions work regardless of whether or not a value is null, and in these
185−cases you'll see ``Sql DBType a``. ``Sql`` can be used with any ``DBType``
186−subtype. For example, the type of ``div`` is::
187−
188− div :: Sql DBIntegral a => Expr a -> Expr a -> Expr a
189−
190−Which means ``div`` works on any ``DBIntegral a``, including ``Maybe a``.
191−
192115The ``DBType`` subtypes
193−=======================
116+-----------------------
194117
195118``DBEq``
196−--------
119+^^^^^^^^
197120
198121.. todo::
199122
200123 Document this
201124
202125``DBOrd``
203−---------
126+^^^^^^^^^
204127
205128.. todo::
206129
207130 Write this
208131
209132``DBSemigroup`` and ``DBMonoid``
210−--------------------------------
133+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
211134
212135.. todo::
213136
214137 Write this
215138
216139``DBNum``, ``DBIntegral`` and ``DBFractional``
217−----------------------------------------------
140+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
218141
219142.. todo::
220143
221144 Write this
222145
223146``DBString``
224−------------
147+^^^^^^^^^^^^
225148
226149.. todo::
227150