Irmin is a distributed database that follows the same design principles as Git
OCaml Other
Latest commit ea9cfad Feb 24, 2017 @samoht samoht committed on GitHub Merge pull request #413 from samoht/master
Fix regression in `irmin tree` and make irmin available on at least 4.03
Permalink
Failed to load latest commit information.
bin unix: fix regression in `irmin tree` Feb 23, 2017
doc Fix doc generation after the split into 5 packages Feb 16, 2017
examples Expose nicer commit info functions Feb 20, 2017
pkg Fix META file for irmin-mirage Feb 23, 2017
src-git Merge pull request #410 from samoht/docs Feb 21, 2017
src-http Add a simplified KV functor to build a store by only providing contents Feb 20, 2017
src-mirage mirage: remove dead/unused code Feb 21, 2017
src-unix Merge pull request #410 from samoht/docs Feb 21, 2017
src Fix doc generation Feb 21, 2017
test rename owner into author Feb 20, 2017
.gitignore Split the packages into 5: irmin, irmin-git, irmin-mirage, irmin-http… Feb 16, 2017
.merlin Add jsonm in .merlin Feb 16, 2017
.travis.yml ci: fix version pinning in TravisCI Feb 16, 2017
CHANGES.md Update CHANGES Feb 21, 2017
LICENSE.md Update Copyright years Feb 16, 2017
Makefile Add mulit-release runes Feb 21, 2017
README.md Update Copyright years Feb 16, 2017
_tags Fix doc generation Feb 21, 2017
appveyor.yml Run the tests on Windows Feb 16, 2017
irmin-git.descr Add opam description files Feb 23, 2017
irmin-git.opam update to ocaml-git 0.10.0 Feb 16, 2017
irmin-http.descr Add opam description files Feb 23, 2017
irmin-http.opam http: add unit tests for irmin-http Feb 16, 2017
irmin-mirage.descr Add opam description files Feb 23, 2017
irmin-mirage.opam update to ocaml-git 0.10.0 Feb 16, 2017
irmin-unix.descr Add opam description files Feb 23, 2017
irmin-unix.opam update to ocaml-git 0.10.0 Feb 16, 2017
irmin.descr Add opam description files Feb 23, 2017
irmin.opam irmin compiles on >= 4.03 Feb 24, 2017
prepare-exe.sh Add a small script to prepare the final .exe on windows Apr 4, 2016

README.md

Irmin -- A distributed database that follows the same design principles as Git

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.

Build Status docs

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
open Irmin_unix
module Store =
  Irmin_git.FS (Irmin.Contents.String)(Irmin.Ref.String)(Irmin.Hash.SHA1)

let config = Irmin_git.config ~root:"/tmp/irmin/test" ~bare:true ()
let prog =
  Store.Repo.create config >>= Store.master task >>= fun t ->
  Store.update (t "Updating foo/bar")  ["foo"; "bar"] "hi!" >>= fun () ->
  Store.read_exn (t "Reading foo/bar") ["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.