diff --git a/ocsipersist.opam b/ocsipersist.opam index 1375b92..adb213f 100644 --- a/ocsipersist.opam +++ b/ocsipersist.opam @@ -4,8 +4,8 @@ version: "2.0.0" authors: "The Ocsigen team " maintainer: "Jan Rochel " license: "LGPL-2.1-only with OCaml-LGPL-linking-exception" -synopsis: "Persistent key/value storage for OCaml using multiple backends" -description: "This is an virtual library defining a unified frontend for a number of key/value storage implementations. Ocsipersist is used pervasively in Eliom/Ocsigen to handle sessions and references. It can be used as an extension for ocsigenserver or as a library. Implementations of the following backends currently exist: DBM, PostgreSQL, SQLite." +synopsis: "Persistent key-value storage for OCaml using multiple backends" +description: "This is an virtual library defining a unified frontend for a number of key-value storage implementations. Implementations of the following backends currently exist: DBM, PostgreSQL, SQLite." homepage: "https://github.com/ocsigen/ocsipersist" bug-reports: "https://github.com/ocsigen/ocsipersist/issues" diff --git a/src/dbm/dune b/src/dbm/dune index 6619c45..4129756 100644 --- a/src/dbm/dune +++ b/src/dbm/dune @@ -38,6 +38,7 @@ (name ocsipersist_dbm_config) (public_name ocsipersist-dbm-config) (modules ocsipersist_config) + (wrapped false) (libraries xml-light ocsipersist_dbm ocsigenserver)) ; DBM server: diff --git a/src/dbm/index.mld b/src/dbm/index.mld index fd03773..9aab666 100644 --- a/src/dbm/index.mld +++ b/src/dbm/index.mld @@ -1,29 +1,19 @@ {0 ocsipersist-dbm} +DBM backend for Ocsipersist. +For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}. +This page describes how to configure the DBM backend. The DBM backend uses a server process [ocsidbm]. {1 Using as a library} -For the API documentation see OPAM package [ocsipersist]. -If you are not using Ocsigen Server, you can configure with -{[ -Ocsipersist_settings.set_delay_loading -Ocsipersist_settings.set_store -Ocsipersist_settings.set_ocsidbm -Ocsipersist_settings.set_error_log_path -]} +If you are not using Ocsigen Server's configuration file, +add library [ocsipersist-dbm.settings] in your Dune file, and +use module {!Ocsipersist_settings} +to configure the storage file. {1 Using with Ocsigen Server: ocsipersist-dbm-config} -For the API documentation see OPAM package [ocsipersist]. - -Here we document the configuration options of the ocsigenserver extension. -All sub-tags of the [extension] tag are optional. - -{[ - - - - - -]} +If you want to configure Ocsipersist-dbm from Ocsigen Server's +configuration file, use package +{{:../ocsipersist-dbm-config/Ocsipersist_config/index.html}ocsipersist-dbm-config}. diff --git a/src/dbm/ocsipersist_config.mli b/src/dbm/ocsipersist_config.mli index e69de29..14355b8 100644 --- a/src/dbm/ocsipersist_config.mli +++ b/src/dbm/ocsipersist_config.mli @@ -0,0 +1,16 @@ +(** + +If you are using the DBM backend of Ocsipersist +with Ocsigen Server with a configuration file, +install package [ocsipersist-dbm-config] and +use the following configuration tags. +All sub-tags of the [extension] tag are optional. + +{@xml[ + + + + + +]} +*) diff --git a/src/ocsipersist.mli b/src/ocsipersist.mli index 372056c..3bd6cac 100644 --- a/src/ocsipersist.mli +++ b/src/ocsipersist.mli @@ -1,6 +1,38 @@ -(** Library (and extension for ocsigenserver) for storing and retrieving - key/value data in a persistent manner. This module defines a unified - frontend for a number of different backends. *) +(** Persistent key-value store interface for OCaml. + This is an 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: + +{[ +# #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 = +# Lwt_main.run (let%lwt v = Ocsipersist.Ref.get r in print_int v; Lwt.return_unit);; +444- : unit = () +]} +*) module Functorial : Ocsipersist_lib.Sigs.FUNCTORIAL (** Functorial frontent. Allows for custom (de)serialisation functions, which diff --git a/src/pgsql/dune b/src/pgsql/dune index 3acd717..a795067 100644 --- a/src/pgsql/dune +++ b/src/pgsql/dune @@ -19,6 +19,7 @@ (name ocsipersist_pgsql_config) (public_name ocsipersist-pgsql-config) (modules ocsipersist_config) + (wrapped false) (libraries xml-light ocsigenserver ocsipersist_pgsql)) (documentation diff --git a/src/pgsql/index.mld b/src/pgsql/index.mld index 75dc81e..f5b2860 100644 --- a/src/pgsql/index.mld +++ b/src/pgsql/index.mld @@ -1,47 +1,18 @@ {0 ocsipersist-pgsql} -{1 Using as a library} -For the API documentation see OPAM package [ocsipersist]. - -If you are not using Ocsigen Server, you can configure with: -{[ -Ocsipersist_settings.set_host -Ocsipersist_settings.set_port -Ocsipersist_settings.set_database -Ocsipersist_settings.set_user -Ocsipersist_settings.set_password -Ocsipersist_settings.set_connexion_pool_size -Ocsipersist_settings.set_unix_domain_socket_dir -]} +PostgreSQL backend for Ocsipersist. +For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}. +This page describes how to configure the PostgreSQL backend. -{1 Using with Ocsigen Server: ocsipersist-psql-config} - -For the API documentation see OPAM package [ocsipersist]. +{1 Using as a library} -Here we document the configuration options of the ocsigenserver extension. -All attributes of the [database] tag are optional. +If you are not using Ocsigen Server's configuration file, +add library [ocsipersist-pgsql.settings] in your Dune file, and +use module {!Ocsipersist_settings} +to configure the storage file. -One can either define a host to connect to: -{[ - - - -]} +{1 Using with Ocsigen Server: ocsipersist-pgsql-config} -Or a UNIX domain socket: -{[ - - - -]} +If you want to configure Ocsipersist-pgsql from Ocsigen Server's +configuration file, use package +{{:../ocsipersist-pgsql-config/Ocsipersist_config/index.html}ocsipersist-pgsql-config}. diff --git a/src/pgsql/ocsipersist_config.mli b/src/pgsql/ocsipersist_config.mli index e69de29..78db0a4 100644 --- a/src/pgsql/ocsipersist_config.mli +++ b/src/pgsql/ocsipersist_config.mli @@ -0,0 +1,33 @@ +(** +If you are using the PostgreSQL backend of Ocsipersist +with Ocsigen Server with a configuration file, +install package [ocsipersist-pgsql-config] and +use the following configuration tags. +All attributes of the [database] tag are optional. + +One can either define a host to connect to: +{@xml[ + + + +]} + +Or a UNIX domain socket: +{@xml[ + + + +]} + +*) diff --git a/src/sqlite/dune b/src/sqlite/dune index 4d649ac..4ef220a 100644 --- a/src/sqlite/dune +++ b/src/sqlite/dune @@ -19,6 +19,7 @@ (name ocsipersist_sqlite_config) (public_name ocsipersist-sqlite-config) (modules ocsipersist_config) + (wrapped false) (libraries xml-light ocsigenserver ocsipersist_sqlite)) (documentation diff --git a/src/sqlite/index.mld b/src/sqlite/index.mld index 8a3307b..afc3590 100644 --- a/src/sqlite/index.mld +++ b/src/sqlite/index.mld @@ -1,22 +1,18 @@ {0 ocsipersist-sqlite} + +SQLite backend for Ocsipersist. +For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}. +This page describes how to configure the SQLite backend. + {1 Using as a library} -For the API documentation see OPAM package [ocsipersist]. +If you are not using Ocsigen Server's configuration file, +add library [ocsipersist-sqlite.settings] in your Dune file, and +use module {!Ocsipersist_settings} to configure the storage file. -If you are not using Ocsigen Server, you can configure the storage file with -{[ -Ocsipersist_settings.set_db_file -]} {1 Using with Ocsigen Server: ocsipersist-sqlite-config} -If you are using Ocsipersist with Ocsigen Server with a configuration file, -install package [ocsipersist-sqlite-config] and -use the following configuration tags. -All sub-tags of the [extension] tag are optional. - -{[ - - - -]} +If you want to configure Ocsipersist-sqlite from Ocsigen Server's +configuration file, use package +{{:../ocsipersist-sqlite-config/Ocsipersist_config/index.html}ocsipersist-sqlite-config}. diff --git a/src/sqlite/ocsipersist_config.mli b/src/sqlite/ocsipersist_config.mli index e69de29..2b509fa 100644 --- a/src/sqlite/ocsipersist_config.mli +++ b/src/sqlite/ocsipersist_config.mli @@ -0,0 +1,12 @@ +(** +If you are using the SQLite backend of Ocsipersist with Ocsigen Server +with a configuration file, install package [ocsipersist-sqlite-config] and +use the following configuration tags. +All sub-tags of the [extension] tag are optional. + +{@xml[ + + + +]} +*)