Irmin is an OCaml library for building mergeable, branchable distributed data stores.
- 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 Git - Dynamic 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 can be found online at https://mirage.github.io/irmin
To install Irmin, the command-line tool and all optional dependencies using opam:
opam install irmin-unix
A minimal installation, with no storage backends can be installed by running:
opam install irmin
To only install the in-memory storage backend:
opam install irmin-mem
The following packages have been made available on opam
:
irmin
- the base package, no storage implementationsirmin-chunk
- chunked storageirmin-fs
- filesystem-based storage usingbin_prot
irmin-git
- Git compatible storageirmin-graphql
- GraphQL serverirmin-http
- a simple REST interfaceirmin-mem
- in-memory storage implementationirmin-mirage
- mirage compatibilityirmin-mirage-git
- Git compatible storage for mirageirmin-mirage-graphql
- mirage compatible GraphQL serverirmin-unix
- unix compatibilityirmin-pack
- compressed, on-disk, posix backendppx_irmin
- PPX deriver for Irmin content types (see README_PPX.md)
For more information about an individual package consult the online documentation.
Below is a simple example of setting a key and getting the value out of a Git based, filesystem-backed store.
open Lwt.Infix
(* Irmin store with string contents *)
module Store = Irmin_unix.Git.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_unix.info ~author fmt
let main =
(* Open the repo *)
Store.Repo.v config >>=
(* Load the master branch *)
Store.master >>= fun t ->
(* Set key "foo/bar" to "testing 123" *)
Store.set t ~info:(info "Updating foo/bar") ["foo"; "bar"] "testing 123" >>= fun () ->
(* Get key "foo/bar" and print it to stdout *)
Store.get t ["foo"; "bar"] >|= fun x ->
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.
The same thing can also be accomplished using irmin
, the command-line application installed with irmin-unix
, by running:
$ echo "root: ." > irmin.yml
$ irmin init
$ irmin set foo/bar "testing 123"
$ irmin get foo/bar
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.
Feel free to to report any issues using the Github bugtracker.
See the LICENSE file.
Development of Irmin was supported in part by the EU FP7 User-Centric Networking project, Grant No. 611001.