FlatDB

FlatDB is a lua library that implements a serverless, zero-configuration, NoSQL database engine.
It provides a key-value storage system using plain Lua tables.

When To Use FlatDB

When you want to use SQLite to store data, just take a glance at FlatDB.
When Lua acts in your program as the major language or the embedded scripting language, just try using FlatDB.

Concept

FlatDB	Disk	Lua
Database	Directory	Table
Book	File	Table
Key-value pair	File content	Key-value pair

Keys and values can be all Lua types except coroutines, userdata, cdata and C functions.

Usage

Copy flatdb.lua file to your project or where your lua libraries stored.
Then write this in any Lua file where you want to use it:

local flatdb = require 'flatdb'

1. Bind a directory as a database

   local db = flatdb('./db')
   

2. Open or create a book

   if not db.book then
   	db.book = {}
   end
   

3. Store key-value items

   db.book.key = 'value'
   -- equivalent to db.book['key'] = 'value'
   

4. Retrieve items

   print(db.book.key) -- prints 'value'
   

5. Save to file

   db:save()
   -- 'book' will be saved to './db/book'
   

More usage can be found in the cli.lua(a Redis-like command line interface example using FlatDB).

Quick Look

local flatdb = require("flatdb")

-- open a directory as a database
-- 'db' is just a plain empty Lua table that can contain books
local db = flatdb("./db")

-- open or create a book named "default"
-- it is also a plain empty Lua table where key-value pair stored in
if not db.default then
	db.default = {}
end

-- extend db methods for getting values from 'default' book
flatdb.hack.get = function(db, key)
	return db.default[key]
end

-- extend db methods for setting values to 'default' book
flatdb.hack.set = function(db, key, value)
	db.default[key] = value
end

-- extend db methods for watching new key
flatdb.hack.guard = function(db, f)
	setmetatable(db.default, {__newindex = f})
end

-- get key-value data from 'default' book
print(db:get("hello"))

-- set key-value data to 'default' book
db:set("hello", "world")

-- get key-value data from 'default' book
print(db:get("hello"))

-- set guard function
db:guard(function(book, key, value)
	print("CREATE KEY permission denied!")
end)

-- try creating new key-value pair to 'default' book
db:set("key1", 1)
db:set("key2", 2)

-- update an existing key-value pair
db:set("hello", "bye")

print(db:get("key1")) -- prints nil
print(db:get("key2")) -- prints nil
print(db:get("hello")) -- prints 'bye'

-- store 'default' book to './db/default' file
db:save()

API

• Functions

  • flatdb(dir) --> db

    Bind a directory as a database, returns nil if 'dir' doesn't exists. Otherwise, it returns a 'db' obeject.

  • db:save([book])

    Save all books or the given book(if specified) contained in db to file. The 'book' argument is a string, the book's name.

• Tables

  • flatdb.hack

    The 'hack' table contains db's methods. There is only one method 'save(db, book)' in it by default. It is usually used to extend db methods.

Dependencies

• pp
• lfs

All above libraries can be found in LuaPower.

License

FlatDB is distributed under the MIT license.