Getting Started

This is a brief tutorial to start playing with Irminsule and its command-line tool.

Using the In-Memory Backend

Let's start by creating a new Irminsule instance, which stores its data in memory. To do this, we can use the irmin command-line tool, which is an easy-way to access the Irminsule libraries and APIs.

$ mkdir /tmp/irmin-mem && cd /tmp/irmin-mem
$ irmin init -d -m -v # Start a server (-d) in-memory (-m) and display some events (-v)
2014-01-21 17:24:26.525        INFO : source: in-memory
2014-01-21 17:24:26.526        INFO : daemon: http://127.0.0.1:8080
Server started on port 8080.

You can now open a new terminal, tell irminsule to use by defaut a remote store located on http://127.0.0.1:8080 and start writing few things in the database.

$ export IRMIN=r:http://127.0.0.1:8080
$ irmin write a/b foo
$ irmin write a/c bar

You can then inspect the database contents:

$ irmin tree
/a/b..............................................................................."foo"
/a/c..............................................................................."bar"
$ irmin read a/b
foo

This state looks good, so we want to keep track of it if later something bad happens to the database.

$ STATE=`irmin snapshot`
$ irmin write a/b notfoo
# [...]
$ irmin revert $STATE
$ irmin tree
/a/b..............................................................................."foo"
/a/c..............................................................................."bar"

Under the hood there are three different kind of objects that are stored in the database. First the raw objects (or blobs) are the one that are directly provided by the user (or the application). That's foo and bar here. There are tree objects, which are similar to filesystem inodes, which are used by Irminsule to keep track of directories. Finally, there are commit objects, which are used to keep track of the state history (and are useful to snapshot and rollback).

You can see the relation between this objects by dumping the database state in a .dot file.

$ irmin dump thestate
$ cat thestate.dot
# [..] A graphivz graph
$ open thestate.png`

TODO: insert a diagram and explain how to read it

You can also access the daemon state by opening your browser to http://127.0.0.1:8080 directly which is a classical JSON CRUD interface. It will list the possible operations. For instance, you can read the store contents directy:

$ curl http://127.0.0.1:8080/read/a/b
{"result":"foo"}

Now you can switch back to the first terminal (where you started the Irminsule daemon). You will see a lot of activity has been going on in there as it was busy dealing with the requests you just made. If you kill the daemon and restart it again, you will notice that all the state is lost. This is expected, as you run the daemon using -m (i.e. backing the database store in memory). If you want to persist it using a custom binary format (which is optimized for reading and writing, not much for space usage) you can simply remove -m when you start the daemon: every write operation will be directly flushed to disk and you will be able to restart the server seamlessly.

The Git Backend

Now the really cool think about Irminsule is that it speaks Git fluently. This means that you can replace -m by -g and do exactly the same thing as in the previous section. But, then, you will be able to use the usual git command-line tool to inspect, modify and add new elements to the store.

For instance, let's start a new Irminsule instance.

$ mkdir /tmp/irmin-git && cd /tmp/irmin-git
$ git init
Initialized empty Git repository in /tmp/irmin-git/.git/
$ irmin init -g -d -v

You can the add some data in a new terminal:

$ export IRMIN=r:http://127.0.0.1:8080
$ irmin write a/b foo
$ irmin write a/c bar

It's now really easy to inspect the history using the usual Git worklow:

$ cd /tmp/irmin-git
$ git log
commit 87866c90c99fbbd0b029a95ef4354a6cb47656c1
Author: Irminsule (piana.mac.cl.cam.ac.uk[37101])
<[email protected]>
Date:   Tue Jan 21 17:59:57 2014 +0000

    Autogenerated by Irminsule

commit 5954683338c43d73c5589ce1c2dc09c2a4fac1ec
Author: Irminsule (piana.mac.cl.cam.ac.uk[37100])
<[email protected]>
Date:   Tue Jan 21 17:59:55 2014 +0000

    Autogenerated by Irminsule

$ git show 5954
commit 5954683338c43d73c5589ce1c2dc09c2a4fac1ec
Author: Irminsule (piana.mac.cl.cam.ac.uk[37100])
<[email protected]>
Date:   Tue Jan 21 17:59:55 2014 +0000

    Autogenerated by Irminsule

diff --git a/a/b b/a/b
new file mode 100644
index 0000000..1910281
--- /dev/null
+++ b/a/b
@@ -0,0 +1 @@
+foo
\ No newline at end of file

That translation is bidirectional. That means that any change you make in the repository will be reflected in the Irminsule world.

$ git reset HEAD --hard # Extract the files from the bare Git repo
$ tree
.
├── a
    ├── b
    └── c

1 directory, 2 files
$ echo "Hello world" >> a/b
$ git commit -a -m "Test"
[master ed406fe] Test
 1 file changed, 1 insertion(+), 1 deletion(-)
$ irmin tree
/a/b..............................................................................."fooHello world\n"
/a/c............................................................................................"bar"
$ git rev-parse HEAD
ed406fe7854317f511b746439f6f25adb89d3dd8
$ irmin snapshot
ed406fe7854317f511b746439f6f25adb89d3dd8

This enables an application to pull/push the state of its database.

TODO: more next