docs/projectm36_client_library.markdown · project-m36

git.iko.soy/project-m36

project-m36/docs/projectm36_client_library.markdown

51 lines 2.4 kB history raw

1# Project:M36 Client Library

3The Project:M36 client library is the preferred method for interacting with Project:M36 databases. It supports all features of the DBMS while other interfaces may not.

5**Note:** A less featureful but more convenient client API also is available: see [documentation](simple_api.markdown).

7The client supports both in-process and remote Project:M36 access.

9## Setup

111. Import the library's symbols

12```haskell

13import ProjectM36.Client

14```

152. Create a Connection with a `ConnectionInfo` in the Either monad

16```haskell

17conn <- connectProjectM36 (InProcessConnectionInfo NoPersistence)

18```

20## Executing Expressions

221. Execute relational expression queries

23```haskell

24result <- executeRelationalExpr conn (Union (RelationVariable "x") (RelationVariable "y"))

25```

262. Execute database context expressions which modify the current, mutable database context

27```haskell

28maybeErr <- executeDatabaseContextExpr conn (Define "person" (attributesFromList [Attribute "name" StringAtomType, Attribute "age" IntAtomType, Attribute "id" StringAtomType]))

29```

303. Execute a transaction graph expression

31```haskell

32maybeErr <- executeGraphExpr conn (JumpToHead "branch2")

33```

35## Dealing with Concurrency

37As in all databases, transactions contend concurrently for access to the the latest database state. Unlike most DBMSs, Project:M36 features multiple heads to reduce contention. Still, at a high transaction rate, Project:M36 clients would still be likely to receive lots of ```TransactionIsNotAHeadError```s because the server's head has received additional commits by the time a client wants to commit its own transaction. To reduce the incidence of this error, the server offers an ```autoMergeToHead``` function which:

391. creates a temporary branch

401. commits the current disconnected transaction to the temporary branch

411. attempts a merge back to the original branch

43The operations above occur atomically on the server. The purpose of this "automerge" is to reduce reliance on repeated client attempts to commit when head contention is high. The trade-off is that the client must handle any merge errors or use a different merge strategy.

45This feature is similar to git's ```rebase``` functionality except that the merge occurs server side and is fully validated and committed, if possible.

47## Cleanup

491. Close the connection

50```haskell

51close conn