colddb/README-zh.md

FlatDB

FlatDB是一个Lua扩展库，实现一个无服务器的零配置的NoSQL数据引擎。
它提供一个由Lua表构成的键值对存储系统。

FlatDB的使用情境

当您想使用SQLite存储一些数据，而不必用到SQL查询的时候，可以考虑使用FlatDB代替之。
如果您的程序使用的语言恰好是Lua，或者嵌入了Lua作为扩展脚本的话，那么就尝试使用FlatDB来存储数据吧。

概念

FlatDB	磁盘	Lua
数据库	目录	表
页（Page）	文件	表
键值对	文件内容	键值对

该表反映的是FlatDB、磁盘和Lua三个层面的对应关系。
FlatDB将一个目录看作数据库，映射到一个Lua表上。 该Lua表的下级也是一些Lua表，对应FlatDB的页（Page），它将被存储到数据库目录下同名的文件中。 这些文件的内容正是页（Page）中的键值对，即Lua表序列化后的字符串。 键值对中的键和值可以是Lua中所有能够被序列化的类型，即除了协程、用户数据、C数据和C函数外的类型。

用法

将flatdb.lua文件复制到你的项目所在或存储Lua扩展库的目录中。
然后在用到它的Lua文件中写上这句话：

local flatdb = require 'flatdb'

1. 将目录作为数据库映射到Lua表中

   local db = flatdb('./db')
   

2. 打开或创建一个页（Page）

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

3. 往页（Page）中写入键值对数据

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

4. 读取页（Page）中的数据

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

5. 将所有页（Page）数据保存在同名的文件中

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

更多用法可参考另一个项目Ledis（一个使用FlatDB作为存储后端的Redis实现）。

范例概览

-- 这是一个以FlatDB作为存储引擎的日志系统例子

local flatdb = require("flatdb")

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
end

local levels = {"debug", "info", "warn", "error", "fatal"}

for _, level in ipairs(levels) do
	flatdb.hack[level] = function(logger, msg)
		common_log(logger, level, msg)
	end
end

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

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

local pp = require("pp") -- https://github.com/luapower/pp
pp(logger:find("error"))

API

• 函数

  • flatdb(dir) --> db

    将一个目录dir映射成数据库对象。若目录不存在，返回nil。否则，返回一个数据库对象db（Lua表）。

  • db:save([page])

    将指定的页（Page）保存在文件中，若不指定则保存数据库对象中所有的页。参数page是指页的名称。

• 表

  • flatdb

    当数据库载入后，flatdb表的键值对有以下关系：

    flatdb[dir] --> db

    flatdb[db] --> dir

  • flatdb.hack

    hack表包含了数据库对象的所有方法。默认情况下，目前数据库对象只有一个db:save([page])方法。 该表一般用于扩展数据库对象方法。

依赖项

• lua-MessagePack

许可证

FlatDB是在MIT许可证下发布的。