package irmin
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=922836116c30ec68068a38694a09bba521cf47edd0e4ae44e076b9b4963da180
sha512=30f6833157cab53cc285093d7f6a82492b9a3709c860160278b1e7b665a7640a0a4c6a0415df0c8127b3967a60146a6cbb99f1151476736afde6e2cf50a56890
Description
Irmin is a library for persistent stores with built-in snapshot, branching and reverting mechanisms. It is designed to use a large variety of backends. Irmin is written in pure OCaml and does not depend on external C stubs; it aims to run everywhere, from Linux, to browsers and Xen unikernels.
Published: 08 Sep 2022
README
README.md
About
Built-in Snapshotting - backup and restore
Storage Agnostic - you can use Irmin on top of your own storage layer
Custom Datatypes - (de)serialization for custom data types, derivable via
ppx_irmin
Highly Portable - runs anywhere from Linux to web browsers and Xen unikernels
Git Compatibility -
irmin-git
uses an on-disk format that can be inspected and modified using GitDynamic Behavior - allows the users to define custom merge functions, use in-memory transactions (to keep track of reads as well as writes) and to define event-driven workflows using a notification mechanism
Documentation
API documentation can be found online at https://mirage.github.io/irmin
Installation
Prerequisites
Please ensure to install the minimum opam
and ocaml
versions. Find the latest version and install instructions on ocaml.org.
To install Irmin with the command-line tool and all unix backends using opam
:
opam install irmin-cli
A minimal installation containing the reference in-memory backend can be installed by running:
opam install irmin
The following packages have are available on opam
:
irmin
- the base package, plus an in-memory storage implementationirmin-chunk
- chunked storageirmin-cli
- a simple command-line toolirmin-fs
- filesystem-based storage usingbin_prot
irmin-git
- Git compatible storageirmin-graphql
- GraphQL serverirmin-http
- a simple REST interfaceirmin-mirage
- mirage compatibilityirmin-mirage-git
- Git compatible storage for mirageirmin-mirage-graphql
- mirage compatible GraphQL serverirmin-pack
- compressed, on-disk, posix backendppx_irmin
- PPX deriver for Irmin content types (see README_PPX.md)irmin-containers
- collection of simple, ready-to-use mergeable data structures
To install a specific package, simply run:
opam install <package-name>
Development Version
To install the development version of Irmin in your current opam switch
, clone this repository and opam install
the packages inside:
git clone https://github.com/mirage/irmin
cd irmin/
opam install .
Usage
Example
Below is a simple example of setting a key and getting the value out of a Git-based, filesystem-backed store.
open Lwt.Syntax
(* Irmin store with string contents *)
module Store = Irmin_git_unix.FS.KV (Irmin.Contents.String)
(* Database configuration *)
let config = Irmin_git.config ~bare:true "/tmp/irmin/test"
(* Commit author *)
let author = "Example <example@example.com>"
(* Commit information *)
let info fmt = Irmin_git_unix.info ~author fmt
let main =
(* Open the repo *)
let* repo = Store.Repo.v config in
(* Load the main branch *)
let* t = Store.main repo in
(* Set key "foo/bar" to "testing 123" *)
let* () =
Store.set_exn t ~info:(info "Updating foo/bar") [ "foo"; "bar" ]
"testing 123"
in
(* Get key "foo/bar" and print it to stdout *)
let+ x = Store.get t [ "foo"; "bar" ] in
Printf.printf "foo/bar => '%s'\n" x
(* Run the program *)
let () = Lwt_main.run main
The example is contained in examples/readme.ml It can be compiled and executed with dune:
$ dune build examples/readme.exe
$ dune exec examples/readme.exe
foo/bar => 'testing 123'
The examples directory also contains more advanced examples, which can be executed in the same way.
Command-line
The same thing can also be accomplished using irmin
, the command-line application installed with irmin-cli
, by running:
$ echo "root: ." > irmin.yml
$ irmin init
$ irmin set foo/bar "testing 123"
$ irmin get foo/bar
testing 123
irmin.yml
allows for irmin
flags to be set on a per-directory basis. You can also set flags globally using $HOME/.irmin/config.yml
. Run irmin help irmin.yml
for further details.
Also see irmin --help
for list of all commands and either irmin <command> --help
or irmin help <command>
for more help with a specific command.
Issues
Feel free to report any issues using the GitHub bugtracker.
License
See the LICENSE file.
Acknowledgements
Development of Irmin was supported in part by the EU FP7 User-Centric Networking project, Grant No. 611001.
Dependencies (16)
Dev Dependencies (7)
-
bisect_ppx
dev & >= "2.5.0"
-
odoc
(< "2.0.1" | > "2.0.2") & with-doc
-
vector
with-test
-
qcheck-alcotest
with-test
-
alcotest-lwt
with-test
-
alcotest
>= "1.1.0" & with-test
-
hex
with-test
Used by (13)
-
irmin-chunk
= "3.4.1"
-
irmin-cli
= "3.4.1"
-
irmin-containers
= "3.4.1"
-
irmin-fs
= "3.4.1"
-
irmin-git
= "3.4.1"
-
irmin-graphql
= "3.4.1"
-
irmin-http
= "3.4.1"
-
irmin-mirage
= "3.4.1"
-
irmin-pack
= "3.4.1"
-
irmin-test
= "3.4.1"
-
irmin-tezos
>= "3.0.0" & < "3.4.2"
-
libirmin
= "3.4.1"
-
tezos-context
>= "11.0" & < "13.0"
Conflicts (1)
-
result
< "1.5"