irmin

Irmin, a distributed database that follows the same design principles as Git
README

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.


Description

Irmin is a library to version-control application data. It has the following
features:

  • on-disk format various formats are supported, including the Git format:
    Irmin on-disk repositories can be inspected and modified using the classic
    Git command-line tools.

  • wire format various formats are supported, including the Git protocol
    (only in client mode) or a simple JSON-based REST API (client and server).

  • dynamic behaviour Irmin allows the users to define custom merge functions,
    to use in-memory transactions (to keep track of reads as well as writes) and
    to define event-driven workflows using a notification mechanism.

These abstractions allow developers to create applications with concurrent
behaviors which are both efficient and safe.

Bindings to other languages

Backends

Irmin ships with various backends. It provides the following OCamlfind pacakges:

  • irmin.mem is an in-memory backend.

  • irmin.git uses the Git format to persist data on disk.

  • irmin.fs uses bin_prot to persist
    data on disk.

  • irmin.http uses JSON over HTTP to speak with an Irmin server.

Other external backends are available as external OPAM packages
(use opam install <pkg> to install):

  • irmin-chunk stores raw contents into
    a well-balanced rope where leafs are chunks of all the same size.

  • irmin-indexdb is a backend
    for a web browser's IndexedDB store.

Datastructures

  • merge-queues is an implementation
    of mergeable queues.

  • merge-ropes is an implementation
    of mergeable ropes.

  • diff-datatypes is a collection
    of automatic merge functions based on edit scripts. It is fairly generic but
    contains specific implementation for mergeable trees, stacks and queues.

  • irmin-datatypes is a
    collection of mergeable datatypes, including LWW registers, queues and sets.

Use-Cases

Here a list of Irmin users:

  • Cuekeeper a
    version-controlled TODO list in the browser.

  • imaplet, a version-controlled
    IMAP server and client.

  • jitsu, a DNS server that automatically
    starts unikernels on demand. The database is persisted with Irmin.

  • Irmin+Xenstore, the
    Xenstore deamon rewritten to use Irmin to persist its data.

  • irmin-arp, a distributed ARP cache.

  • dog, a synchronisation tool.

  • irminFS, a prototype version-controlled
    file-system using Fuse.

Further Reading

Getting Started

Install

Irmin is packaged with opam:

opam install irmin-unix # install all the optional depencies
Usage

Irmin comes with a command-line tool called irmin. See irmin --help for further reading. Use either irmin <command> --help or
irmin help <command> for more information on a specific command.

To get the full capabilites of Irmin, use the API:

open Lwt.Infix
open Irmin_unix
module Store = Irmin_unix.Git.FS.KV (Irmin.Contents.String)

let config = Irmin_git.config ~bare:true "/tmp/irmin/test"
let info fmt = Irmin_unix.info ~author:"me <me@moi.com>" fmt

let prog =
  Store.Repo.v config >>= Store.master >>= fun t ->
  Store.set t ~info:(info "Updating foo/bar") ["foo"; "bar"] "hi!" >>= fun () ->
  Store.get t ["foo"; "bar"] >>= fun x ->
  Printf.printf "Read: %s\n%!" x;
  Lwt.return_unit

let () = Lwt_main.run prog

To compile the example above, save it to a file called
example.ml. Install irmin and git with opam (opam install irmin-unix) and
run

$ ocamlfind ocamlopt example.ml -o example -package irmin.unix,lwt.unix -linkpkg
$ ./example
Read: hi!

The examples directory contains more examples. To build them, run

$ ./configure --enable-examples
$ make
Tutorial

Tutorials are available on the
wiki.

Issues

To report any issues please use the bugtracker on
Github
.

Conditions

See the LICENSE file.

Acknowledgements

Development of Irmin was supported in part by the EU FP7 User-Centric Networking
project, Grant No. 611001.

Install
Published
11 Jun 2018
Sources
irmin-1.4.0.tbz
md5=e214dd3832bbe7b83df6c77263ac525b
Dependencies
logs
>= "0.5.0"
hex
>= "0.2.0"
lwt
>= "2.4.7"
jsonm
>= "1.0.0"
cstruct
>= "1.6.0"
uri
>= "1.3.12"
fmt
>= "0.8.0"
result
< "1.5"
jbuilder
>= "1.0+beta10"
ocaml
>= "4.03.0"
Reverse Dependencies
datakit
>= "0.12.2"
imaplet-lwt
>= "0.1.8" & < "0.1.10"
irmin-git
= "1.3.0"
irmin-http
< "2.0.0"
irmin-mirage
>= "1.2.0" & < "2.0.0"
irmin-unix
>= "1.3.0" & < "2.0.0"