colddb/README.md

175 lines
3.9 KiB
Markdown
Raw Normal View History

2015-04-06 17:55:11 +02:00
FlatDB
===========
FlatDB is a lua library that implements a serverless, zero-configuration, NoSQL database engine.<br>
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.<br>
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 |
2015-04-07 09:37:11 +02:00
| Page | File | Table |
2015-04-06 17:55:11 +02:00
| 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.<br>
Then write this in any Lua file where you want to use it:
```lua
local flatdb = require 'flatdb'
```
2015-04-06 15:57:17 +02:00
1. Bind a directory as a database
2015-04-06 17:55:11 +02:00
```lua
local db = flatdb('./db')
```
2015-04-07 09:37:11 +02:00
2. Open or create a page
2015-04-06 17:55:11 +02:00
```lua
2015-04-07 09:37:11 +02:00
if not db.page then
db.page = {}
2015-04-06 17:55:11 +02:00
end
```
2015-04-06 15:57:17 +02:00
3. Store key-value items
2015-04-06 17:55:11 +02:00
```lua
2015-04-07 09:37:11 +02:00
db.page.key = 'value'
-- equivalent to db.page['key'] = 'value'
2015-04-06 17:55:11 +02:00
```
2015-04-06 15:57:17 +02:00
4. Retrieve items
2015-04-06 17:55:11 +02:00
```lua
2015-04-07 09:37:11 +02:00
print(db.page.key) -- prints 'value'
2015-04-06 17:55:11 +02:00
```
2015-04-06 15:57:17 +02:00
5. Save to file
2015-04-06 17:55:11 +02:00
```lua
db:save()
2015-04-07 09:37:11 +02:00
-- 'page' will be saved to './db/page'
2015-04-06 17:55:11 +02:00
```
More usage can be found in the *cli.lua*(a Redis-like command line interface example using FlatDB).
Quick Look
==========
```lua
2015-04-07 11:40:55 +02:00
-- This is an logging system example using FlatDB
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
local flatdb = require("flatdb")
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
local logger = flatdb("./log")
local count = 0
local function common_log(logger, level, message)
local today = os.date("%Y-%m-%d")
if logger[today] == nil then logger[today] = {} end
if logger[today][level] == nil then logger[today][level] = {} end
table.insert(logger[today][level], {
timestamp = os.time(),
level = level,
message = message
})
count = (count+1)%10
if count == 0 then
logger:save()
end
2015-04-06 17:55:11 +02:00
end
2015-04-07 11:40:55 +02:00
flatdb.hack.debug = function(logger, msg)
common_log(logger, "debug", msg)
2015-04-06 17:55:11 +02:00
end
2015-04-07 11:40:55 +02:00
flatdb.hack.info = function(logger, msg)
common_log(logger, "info", msg)
2015-04-06 17:55:11 +02:00
end
2015-04-07 11:40:55 +02:00
flatdb.hack.warn = function(logger, msg)
common_log(logger, "warn", msg)
2015-04-06 17:55:11 +02:00
end
2015-04-07 11:40:55 +02:00
flatdb.hack.error = function(logger, msg)
common_log(logger, "error", msg)
end
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
flatdb.hack.fatal = function(logger, msg)
common_log(logger, "fatal", msg)
end
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
flatdb.hack.find = function(logger, level, date)
if logger[date or os.date("%Y-%m-%d")] then
return logger[date or os.date("%Y-%m-%d")][level]
end
end
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
for i = 1, 10 do
logger:debug("This is a debug message.")
logger:info("This is an info message.")
logger:warn("This is a warn message.")
logger:error("This is an error message.")
logger:fatal("This is a fatal message.")
end
2015-04-06 17:55:11 +02:00
2015-04-07 11:40:55 +02:00
local pp = require("pp")
pp(logger:find("error"))
2015-04-06 17:55:11 +02:00
```
API
==========
- **Functions**
- **flatdb(dir) --> db**
Bind a directory as a database, returns nil if 'dir' doesn't exists. Otherwise, it returns a 'db' obeject.
2015-04-07 09:37:11 +02:00
- **db:save([page])**
2015-04-06 17:55:11 +02:00
2015-04-07 09:37:11 +02:00
Save all pages or the given page(if specified) contained in db to file. The 'page' argument is a string, the page's name.
2015-04-06 17:55:11 +02:00
- **Tables**
2015-04-07 11:40:55 +02:00
- **flatdb**
When a db is loaded, there is two relations below:
*flatdb[dir] --> db*
*flatdb[db] --> dir*
2015-04-06 17:55:11 +02:00
- **flatdb.hack**
2015-04-07 09:37:11 +02:00
The 'hack' table contains db's methods. There is only one method 'save(db, page)' in it by default.
2015-04-06 17:55:11 +02:00
It is usually used to extend db methods.
Dependencies
=======
- [pp](https://github.com/luapower/pp)
- [lfs](http://keplerproject.github.io/luafilesystem/)
All above libraries can be found in [LuaPower](https://luapower.com/).
License
=======
FlatDB is distributed under the MIT license.