@@ -83,3 +83,27 @@ definition using ``ReadShow`` is::
83 data OrderStatus = PaymentPending | Paid | Packed | Shipped
83 data OrderStatus = PaymentPending | Paid | Packed | Shipped
84 deriving stock (Read, Show)
84 deriving stock (Read, Show)
85 deriving DBType via ReadShow OrderStatus
85 deriving DBType via ReadShow OrderStatus
87+Storing structured data with ``JSONEncoded``
88+--------------------------------------------
90+It can occasionally be useful to treat PostgreSQL more like a document store,
91+storing structured documents as JSON objects. Rel8 comes with support for
92+serializing values into structured representations through the ``JSONEncoded``
93+and ``JSONBEncoded`` deriving-via helpers.
95+There usage is very similar to ``ReadShow`` - simply derive ``DBType via
96+JSONEncoded``, and Rel8 will use ``ToJSON`` and ``FromJSON`` instances (from
97+``aeson``) to serialize the given type.
99+For example, a project might use event sourcing with a table of events. Each row
100+in this table is an event, but this event is stored as a JSON object. We can use
101+this type with Rel8 by writing::
103+ data Event = UserCreated UserCreatedData | OrderCreated OrderCreatedData
104+ deriving stock Generic
105+ deriving anyclass (ToJSON, FromJSON)
106+ deriving DBType via JSONBEncoded Event
108+Here we used ``JSONBEncoded``, which will serialize to PostgreSQL ``jsonb``
109+(binary JSON) type, which is generally the best choice.