ImmutableDB.md

ImmutableDB

An interface for immutable databases

ImmutableDB is an abstract interface for content-addressed databases that:

1. save the same blob of data to the same key every time (write)
2. return the same blob of data with the same query key every time (read)

The difference to a a traditional key-value store is that the key doesn't get specified explicitly. Instead, the key gets calculated based on the data using a hashing function. This is also called content-addressed storage.

Interface

key == db.put(value)

value == db.get(key)

Example Implementations

IPFS

IPFS creates a cryptographically secure hash from the data you give it. You can then query the data with the hash:

const db = require('immutabledb-ipfs')

const value = 'Hello world!'

hash = db.put(value)
// 'QmUbbHGqBchN3bwaqevR3bcw9KjvANRi3PbbJP54qrkbMJ'

output = db.get(hash)
// 'Hello world!'

Integrations

• immutabledb-mem
• immutabledb-ipfs
• immutabledb-redis
• immutabledb-levelup

immutabledb-ipfs would look like this:

module.exports = (ipfs) => {
  return {
    put: (data) => {
      return ipfs.object.put(data)
        .then((res) => res.toJSON().Hash)
    },
    get: (hash) => {
      return ipfs.object.get(hash, { enc: 'base58' })
        .then((res) => res.toJSON().Data)
    }
  }
}

Usage:

const IPFS = require('ipfs')
const ImmutableDB = require('immutabledb-ipfs')

const ipfs = new IPFS()
const db = ImmutableDB(ipfs)

const value = 'Hello world!'

const hash = db.put(value)
// 'QmUbbHGqBchN3bwaqevR3bcw9KjvANRi3PbbJP54qrkbMJ'

const output = db.get(hash)
// 'Hello world!'

I understand how the thin veneer can help reduce the complexity from the viewer and make it so the language is more familiar. I'm not sure why we have to brand it differently though, unless you want to handle object sharding for IDB users.

I'm assuming by different brand you refer to abstract-blob-store? There's a subtle but huge difference from abstract-blob-store: you don't handle the keys explicitly, but rather the DB handles the keys for you, ie. content-addressed vs. custom keys.

The rationale, and why I got to think this, is that in case of https://github.com/haadcode/ipfs-log IPFS is only used for object.put/get. If we can extract the common interface, we can enable ipfs-log to have any data storage backend (implementation) and as such allow the same append-only-log functionality with other DBs (as opposed to being locked in to IPFS). You could even do a immutabledb-leveldb wrapper that uses levelDB as the data storage.

I was really referencing IPFS itself, IPFS is a Immutable Store. In IPFS, you can add:

• Raw data - block API
• Graphs - object API
• Data that doesn't fit in a unit (block/object) and needs to be sharded - files API

It is true that these API don't have a strictly common interface (because of specific needs), but a thin veneer can be added on top to give it a clean get/put, releasing the user from having to thing "do I have to shard this" and delivering the key for fetching after adding.

Got it, makes sense. I think this (the lack of high-level common interface) is one of the reason for 🚲 🏠 we've had around the interface-core API. And while I start to see the benefit of the chances we (you) did for the common (programming) API, I feel this could push the very simple core idea of IPFS further, and make it "available" to other systems to implement.

Actually, Immutable Store as you put it, would probably be a better name. Or perhaps Immutable Storage?

Or ImmutableKV?