@@ -0,0 +1,41 @@
1+# The Project:M36 Simple Client Interface
2+
3+## Introduction
4+
5+For common use cases, the ```ProjectM36.Client.Simple``` API can assist in transaction management. The API is designed to be less overwhelming than the full-featured ```ProjectM36.Client```.
6+
7+As such, not all features are available through the simple API, but, because the simple API is a thin layer over the complete API, the user may dip into the complete API at any time.
8+
9+## Usage
10+
11+1. Create a ```DbConn``` to connect to the database:
12+
13+ ```haskell
14+ import ProjectM36.Client.Simple
15+ ...
16+ eDbconn <- simpleConnectProjectM36 (CrashSafePersistence (tempdir </> "db")) emptyNotificationCallback []
17+ ```
18+
19+ The result is either a ```DbError``` or the connection linked to the "master" branch of the database.
20+
21+1. Construct the ```Db``` monad using ```withTransaction```:
22+
23+ ```haskell
24+ withTransaction dbconn $ do
25+ execute $ Assign "x" (ExistingRelation relationTrue)
26+ query $ RelationVariable "x" ()
27+ ```
28+
29+ If there is an error in the above update or query, then an exception is thrown behind the scenes which cancels the transactions, rolls back any changes, and the error is returned by ```withTransaction```.
30+
31+ ```query``` is used with ```RelationalExpr``` queries which read the current database state.
32+
33+ ```execute``` is used with ```DatabaseContextExpr``` values which write the current database state.
34+
35+ To execute a query without cancelling the transaction on an error, use the ```queryOrErr``` and ```executeOrErr``` variants.
36+
37+1. Close the connection:
38+
39+ ```haskell
40+ close dbconn
41+ ```