Irmin is an OCaml library for building mergeable, branchable distributed data stores.

Built-in snapshotting

Built-in snapshotting

Backup and restore your data at any point in time.

Storage agnostic

Storage agnostic

You can use Irmin on top of your own storage layer.

Custom datatypes

Custom datatypes

Automatic (de)serialization for custom data types.

Highly portable

Highly portable

Runs anywhere from Linux to web browsers and Xen unikernels.

Git compatibility

Git compatibility

Bi-directional compatibility with the Git on-disk format. Irmin state can be inspected and modified using the Git command-line tool.

Dynamic behavior

Dynamic behavior

Allows users to define custom merge functions and create event-driven workflows using a notification mechanism.

Installation

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 implementations
  • irmin-chunk - chunked storage
  • irmin-fs - filesystem-based storage using bin_prot
  • irmin-git - Git compatible storage
  • irmin-http - a simple REST interface
  • irmin-mem - in-memory storage implementation
  • irmin-mirage - mirage compatibility
  • irmin-unix - unix compatibility

For more information about an individual package consult the online documentation.

Examples

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 "

(* 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_exn 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

To compile the example above, save it to a file called example.mland run:

$ ocamlfind ocamlopt example.ml -o example -package irmin-unix,lwt.unix -linkpkg
$ ./example
foo/bar => 'testing 123'

The examples directory contains some more advanced examples. The build them, run:

$ dune build examples/trees.exe
$ _build/default/examples/trees.exe

Command-line

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.

Explore further

Tutorial Issues License

Irmin is part of the MirageOS project and is supported by Tarides, Robur and OCaml Labs.