3.7 KiB

Raw Blame History

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
Page	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'

Bind a directory as a database
```
local db = flatdb('./db')
```
Open or create a page
```
if not db.page then
	db.page = {}
end
```

Store key-value items

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

Retrieve items
```
print(db.page.key) -- prints 'value'
```

Save to file

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

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 pages
local db = flatdb("./db")

-- open or create a page 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' page
flatdb.hack.get = function(db, key)
	return db.default[key]
end

-- extend db methods for setting values to 'default' page
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' page
print(db:get("hello"))

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

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

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

-- try creating new key-value pair to 'default' page
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' page 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([page])
  
  Save all pages or the given page(if specified) contained in db to file. The 'page' argument is a string, the page's name.
Tables
- flatdb.hack
  
  The 'hack' table contains db's methods. There is only one method 'save(db, page)' in it by default. It is usually used to extend db methods.

Dependencies

All above libraries can be found in LuaPower.

License

FlatDB is distributed under the MIT license.

3.7 KiB Raw Blame History