# Module `Common.Ocsipersist`

Persistent key-value store interface for OCaml. This is a virtual library defining a unified frontend for a number of key-value storage implementations. Implementations of the following backends currently exist: SQLite, DBM, PostgreSQL. You can choose the backend you prefer by installing packages `ocsipersist-sqlite`, `ocsipersist-dbm` or `ocsipersist-pgsql`.

Library `Ocsipersist_settings`, provided by each of the backends, contain the configuration options for your stores.

Packages `ocsipersist-sqlite-config`, `ocsipersist-dbm-config` and `ocsipersist-pgsql-config` add the possibility to configure the corresponding backends from Ocsigen Server's configuration file.

Ocsipersist is used by Eliom for persistent session storages and references.

Ocsipersist defines several interfaces:

- `Ref` is the simpler the use: it provides persistent references
- `Store` is a lower level interface for persistent values
- `Polymorphic` is a polymorphic table, using Mahshal
- `Functorial` is a typed interface for your own data type
Example of use from the toplevel:

```ocaml
# #require "lwt_ppx";;
(* #thread;; if you are using OCaml < 5.0.0 *)
# #require "ocsipersist-sqlite";;
# Ocsipersist.init ();;
# let r = Ocsipersist.Ref.ref ~persistent:"r" 444;;
val r : int Ocsipersist.Ref.t = <abstr>
# Lwt_main.run (let%lwt v = Ocsipersist.Ref.get r in print_int v; Lwt.return_unit);;
444- : unit = ()
```
```ocaml
module Functorial : Ocsipersist_lib.Sigs.FUNCTORIAL
```
Functorial frontent. Allows for custom (de)serialisation functions, which keeps data human-readable in the backend.

```ocaml
module type TABLE = Ocsipersist_lib.Sigs.TABLE
```
Table representation as generated by the functor [`Functorial.Table`](./Eliom-Common-Ocsipersist-Functorial-Table.md)

```ocaml
module Polymorphic : Ocsipersist_lib.Sigs.POLYMORPHIC
```
Polymorphic frontent. Relies on [`Marshal`](./../../ocaml-compiler/stdlib/Stdlib-Marshal.md) for (de)serialisation, which means that data will be stored in the backend in a fashion that is not necessarily easily readable by non-OCaml-based life forms. If this is an issue for you, you can rely on the functorial frontend instead.

```ocaml
type 'value table = 'value Polymorphic.table
```
Table representation as generated by the function [`Polymorphic.open_table`](./Eliom-Common-Ocsipersist-Polymorphic.md#val-open_table)

```ocaml
module Ref : Ocsipersist_lib.Sigs.REF
```
Simple interface for persistent references. Relies on [`Stdlib.Marshal`](./../../ocaml-compiler/stdlib/Stdlib-Marshal.md) for (de)serialisation, which entails the same limitations as for the [`Polymorphic`](./Eliom-Common-Ocsipersist-Polymorphic.md) frontend. If this is an issue you can rely on [`Functorial`](./Eliom-Common-Ocsipersist-Functorial.md) frontend instead (see [`TABLE.Variable`](./../../ocsipersist-lib/ocsipersist-lib/Ocsipersist_lib-Sigs-module-type-TABLE-Variable.md)).

```ocaml
module Store : Ocsipersist_lib.Sigs.STORE
```
The variable store allows for the persistent storage of individual variables. Relies on [`Stdlib.Marshal`](./../../ocaml-compiler/stdlib/Stdlib-Marshal.md) for (de)serialisation, which entails the same limitations as for the [`Polymorphic`](./Eliom-Common-Ocsipersist-Polymorphic.md) frontend. If this is an issue you can rely on [`Functorial`](./Eliom-Common-Ocsipersist-Functorial.md) frontend instead (see [`TABLE.Variable`](./../../ocsipersist-lib/ocsipersist-lib/Ocsipersist_lib-Sigs-module-type-TABLE-Variable.md)).

```ocaml
type store = Store.store
```
```ocaml
type 'a variable = 'a Store.t
```
```ocaml
exception Decoding_error of string
```
Raised by the JSON frontends ([`Ref_json`](./Eliom-Common-Ocsipersist-Ref_json.md), [`Store_json`](./Eliom-Common-Ocsipersist-Store_json.md) and [`Functorial.Column.Json`](./Eliom-Common-Ocsipersist-Functorial-Column-Json.md)) when a stored value cannot be deserialised by the codec it was opened with (the type changed, or the stored data is corrupted). The argument is the decoder's error message. Backend errors are not reported through this exception, so callers can safely treat it as "the stored value is unreadable".

```ocaml
module Ref_json : Ocsipersist_lib.Sigs.REF_JSON
```
Type-safe persistent references using [`Deriving_Json`](./../../js_of_ocaml/js_of_ocaml.deriving/Deriving_Json.md) for serialisation. Unlike [`Ref`](./Eliom-Common-Ocsipersist-Ref.md), this does not rely on [`Stdlib.Marshal`](./../../ocaml-compiler/stdlib/Stdlib-Marshal.md) and is safe across OCaml versions. Requires types annotated with `[@@deriving json]` (from `js_of_ocaml-ppx_deriving_json`).

```ocaml
module Store_json : Ocsipersist_lib.Sigs.STORE_JSON
```
Type-safe variable store using [`Deriving_Json`](./../../js_of_ocaml/js_of_ocaml.deriving/Deriving_Json.md) for serialisation. Unlike [`Store`](./Eliom-Common-Ocsipersist-Store.md), this does not rely on [`Stdlib.Marshal`](./../../ocaml-compiler/stdlib/Stdlib-Marshal.md) and is safe across OCaml versions. Requires types annotated with `[@@deriving json]` (from `js_of_ocaml-ppx_deriving_json`).

```ocaml
val init : unit -> unit
```