Irmin - A distributed database built on the same principles as Git
Irmin is an OCaml library for building mergeable, branchable distributed data stores.
- 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, derivable via
- Highly portable - runs anywhere from Linux to web browsers and Xen unikernels
- Git compatibility -
irmin-gituses 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 can be found online at https://mirage.github.io/irmin
Please ensure to install the minimum Opam and Ocaml versions which are 2 and 4.07 respectively.
opam list // listing the installed packages
To install Irmin, the command-line tool and all optional dependencies using opam:
opam install irmin-unix
Note : If you face installation issues due to pinned packages. Run the below commands to unpin and try to install again,
Unpinning irmin-unix package,
opam info irmin-unix // to get available versions opam pin -s | grep irmin | xargs opam unpin
A minimal installation, containing the reference in-memory backend, can be installed by running:
opam install irmin
The following packages have been made available on
irmin- the base package, plus an in-memory storage implementation
irmin-chunk- chunked storage
irmin-fs- filesystem-based storage using
irmin-git- Git compatible storage
irmin-graphql- GraphQL server
irmin-http- a simple REST interface
irmin-mirage- mirage compatibility
irmin-mirage-git- Git compatible storage for mirage
irmin-mirage-graphql- mirage compatible GraphQL server
irmin-unix- unix compatibility
irmin-pack- compressed, on-disk, posix backend
ppx_irmin- PPX deriver for Irmin content types (see README_PPX.md)
irmin-containers- collection of simple, ready-to-use mergeable data structures
For more information about an individual package consult the online documentation.
To install the development version of Irmin, clone this repository and
opam install the packages inside:
git clone https://github.com/mirage/irmin cd irmin/ opam install .
Below is a simple example of setting a key and getting the value out of a Git based, filesystem-backed store.
open Lwt.Syntax (* 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 <firstname.lastname@example.org>" (* Commit information *) let info fmt = Irmin_unix.info ~author fmt let main = (* Open the repo *) let* repo = Store.Repo.v config in (* Load the master branch *) let* t = Store.master repo in (* Set key "foo/bar" to "testing 123" *) let* () = Store.set_exn t ~info:(info "Updating foo/bar") ["foo"; "bar"] "testing 123" in (* Get key "foo/bar" and print it to stdout *) let+ x = Store.get t ["foo"; "bar"] in Printf.printf "foo/bar => '%s'\n" x (* Run the program *) let () = Lwt_main.run main
The example is contained in
examples/readme.ml. It can be compiled and executed with dune:
$ dune build examples/readme.exe $ dune exec examples/readme.exe foo/bar => 'testing 123'
examples/ directory also contains more advanced examples, which can be executed in the same way.
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
irmin help irmin.yml for further details.
irmin --help for list of all commands and either
irmin <command> --help or
irmin help <command> for more help with a specific command.
Feel free to to report any issues using the Github bugtracker.
See the LICENSE file.
Development of Irmin was supported in part by the EU FP7 User-Centric Networking project, Grant No. 611001.