Skip to content
Irmin is a distributed database that follows the same design principles as Git
OCaml PHP Other
Branch: master
Clone or download

Latest commit

Latest commit 38eb429 Jun 3, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add comments warning about manual testing of the README example Apr 13, 2020
src Merge pull request #970 from CraigFe/strengthen-ppx-tests May 14, 2020
test ppx_irmin: avoid duplicate definitions of types in test May 11, 2020
.gitignore Ignore macos generated files Dec 16, 2019
.ocamlformat Use ocamlformat.0.14.2 May 29, 2020
.ocamlformat-ignore irmin: update README to 2.0 interface Aug 7, 2019
.travis.yml Require OCaml 4.07 Mar 23, 2020
CHANGES.md Add a CHANGES entry for Store.Tree.concrete_t May 11, 2020
LICENSE.md LICENSE.md: add title Aug 30, 2017
Makefile irmin-http: make the concurrent tests work a bit more reliably Aug 31, 2019
README.md Add comments warning about manual testing of the README example Apr 13, 2020
README_PPX.md Fix the [@nobuiltin] example in the README Apr 17, 2020
appveyor.yml Temporarily disable Appveyor CI Mar 10, 2020
dune-project Use correct fmt version in dune-project Apr 16, 2020
irmin-chunk.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-fs.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-git.opam Fix irmin-git -> irmin constraint Mar 23, 2020
irmin-graphql.opam irmin-graphql: add irmin-unix as a test dependency Apr 16, 2020
irmin-http.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-mem.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-mirage-git.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-mirage-graphql.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-mirage.opam Require dune 1.8 for let+ syntax Jan 12, 2020
irmin-pack.opam Better reporting for integrity_check Feb 27, 2020
irmin-test.opam Update irmin-test.opam Feb 14, 2020
irmin-unix.opam Fix irmin-unix dependency Mar 2, 2020
irmin.opam Merge pull request #961 from CraigFe/void-generic Mar 23, 2020
ppx_irmin.opam ppx_irmin: add Irmin as a test dependency May 14, 2020

README.md

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

OCaml-CI Build Status Travis-CI 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, derivable via ppx_irmin
  • 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-graphql - GraphQL server
  • irmin-http - a simple REST interface
  • irmin-mem - in-memory storage implementation
  • 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)

For more information about an individual package consult the online documentation.

Development version

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 .

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

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'

The examples/ directory also contains more advanced examples, which can be executed in the same way.

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 on a per-directory basis. You can also set flags globally using $HOME/.irmin/config.yml. 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.

You can’t perform that action at this time.