git.iko.soy/project-m36
on 144_proxy_tupleable help sign in
project-m36/docs/simple_api.markdown
42 lines 1.7 kB history raw
1# The Project:M36 Simple Client Interface
3## Introduction
5For 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` (see [documentation](projectm36_client_library.markdown)).
7As 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.
9## Usage
11 1. Create a `DbConn` to connect to the database:
13 ```haskell
14 import ProjectM36.Client.Simple
15 ...
16 let connInfo = InProcessConnectionInfo (CrashSafePersistence "my.db") emptyNotificationCallback []
17 eDbconn <- simpleConnectProjectM36 connInfo
18 ```
20 The result is `Either` a `DbError` or a connection linked to the `"master"` branch of the database.
22 1. Run the `Db` monad using `withTransaction`:
24 ```haskell
25 withTransaction dbconn $ do
26 execute $ Assign "x" (ExistingRelation relationTrue)
27 query $ RelationVariable "x" ()
28 ```
30 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`.
32 `query` is used with `RelationalExpr` queries which read the current database state.
34 `execute` is used with `DatabaseContextExpr` values which write the current database state.
36 To execute a query without cancelling the transaction on an error, use the `queryOrErr` and `executeOrErr` variants.
38 1. Close the connection:
40 ```haskell
41 close dbconn
42 ```