Irmin is a distributed database that follows the same design principles as Git
OCaml Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
doc Fix doc generation after the split into 5 packages Feb 16, 2017
examples Add a jbuild file for the examples Apr 23, 2018
pkg remove unused META files May 26, 2017
src Merge pull request #507 from samoht/doc May 24, 2018
test More fixes to tests May 21, 2018
.gitignore Add opam2 local switch to gitignore May 17, 2018
.travis.yml CI: pin dev version of ocaml-git May 22, 2018
CHANGES.md Update CHANGES Jan 3, 2018
LICENSE.md LICENSE.md: add title Aug 30, 2017
Makefile Add a test target in the Makefile Jul 17, 2017
README.md Fix typo in README, add short comment to read_config_file function May 19, 2018
appveyor.yml CI: disable irmin-unix builds on windows until ocaml-yaml is fixed May 22, 2018
irmin-chunk.opam Update opam self-constraints Nov 22, 2017
irmin-fs.descr Use jbuilder May 11, 2017
irmin-fs.opam Update opam self-constraints Nov 22, 2017
irmin-git.descr Add opam description files Feb 23, 2017
irmin-git.opam Update opam constraints Jan 3, 2018
irmin-http.descr Add opam description files Feb 23, 2017
irmin-http.opam irmin-http: Change to new webmachine API of version 0.6.0 May 22, 2018
irmin-mem.descr Use jbuilder May 11, 2017
irmin-mem.opam Update opam self-constraints Nov 22, 2017
irmin-mirage.descr Add opam description files Feb 23, 2017
irmin-mirage.opam Update opam constraints Jan 3, 2018
irmin-unix.descr Add opam description files Feb 23, 2017
irmin-unix.opam Parse config using yaml May 18, 2018
irmin.descr Add opam description files Feb 23, 2017
irmin.opam Import updates in opam files from opam-repository Nov 22, 2017
prepare-exe.sh Add a small script to prepare the final .exe on windows Apr 4, 2016

README.md

Irmin - A distributed database built on the same principles as Git

Build Status docs

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

Features

  • 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
  • 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

Documentation can be found online at https://mirage.github.io/irmin

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 <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

To compile the example above, save it to a file called example.ml and 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:

$ jbuilder 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 globally on a per-directory basis. 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.

Issues

Feel free to to report any issues using the Github bugtracker.

Conditions

See the LICENSE file.

Acknowledgements

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