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 is to run everywhere, from Linux to Xen unikernels.
Irmin provides an API to built version-controlled applications.
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, allow in-memory transactions (to keeps tracks of reads as well as writes) and a notification mechanism. These abstractions allow to define concurrent applications which are both efficient and safe.
Here a list of Irmin users:
- 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-arp, a distributed ARP cache.
- Irmin+Xenstore, the Xenstore deamon rewritten to use Irmin to persist its data.
- dog, a synchronisation tool.
- irminFS prototype of version-controlled file-system using Fuse.
- Cuekeeper a version-controlled TODO list in the browser.
- merge-queues and merge-ropes are high-level version-controlled data-structures
- diff-datatypes is a collection of automatic merge functions based on edit scripts.
What a Distributed, Version-Controlled ARP Cache Gets You. Blog post describing how Irmin can be used with Mirage to store the network stack's ARP cache, which allows the history to be viewed using the git tools.
Using Irmin to add fault-tolerance to the Xenstore database. Porting the Xen hypervisor toolstack to support Git persistence via Irmin.
Introducing Irmin: Git-like distributed, branchable storage. This is the first post that describes Irmin, the new Git-like storage layer for Mirage OS 2.0.
Irmin is packaged with opam:
opam install irmin-unix # install all the optional depencies
Irmin comes with a command-line tool called
--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 let store = Irmin.basic (module Irmin_git.FS) (module Irmin.Contents.String) let config = Irmin_git.config ~root:"/tmp/irmin/test" ~bare:true () let prog = Irmin.create store config task >>= fun t -> Irmin.update (t "Updating foo/bar") ["foo"; "bar"] "hi!" >>= fun () -> Irmin.read_exn (t "Reading foo/bar") ["foo"; "bar"] >>= fun x -> Printf.printf "Read: %s\n%!" x; 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
git) and run
$ ocamlfind ocamlopt example.ml -o example -package irmin.unix,lwt.unix -linkpkg $ ./example Read: hi!
examples directory contains more examples. To build them, run
$ ./configure --enable-examples $ make
Tutorials are available on the wiki.
To report any issues please use the bugtracker on Github.
Copyright (c) 2013-2015 Thomas Gazagnaire email@example.com
Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.