colddb/README.md

ColdDB

ColdDB is a minetest mod that implements a serverless, asynchronous, NoSQL database engine.
It provides a key or key-value storage system using plain Lua tables, also it can iterate through the keys.

Usage

Copy both colddb.lua and async files to your minetest mod or game. Copy the code from colddb's init file to your mods init file
Write this code in your lua file.

1. create a directory and link it as a database.

coldbase = colddb.get_db("mydb")

2. add an extra folder to the directory. every new file will be added to the global tag(folder).

colddb.add_global_tag(coldbase,"ips")

3. store key item(this key has no value)

colddb.set_key(coldbase,"MyKey")

4. store key-value item

colddb.set(coldbase,"MyKeyAndValue","Hello world")

5. retrieve items (get_key's callback(arg) will return true, false, or nil)

colddb.get(coldbase,"MyKeyAndValue",nil,function(arg)
	if arg then
		minetest.log(string.format("value:%s",arg))
	end
end)
colddb.get_key(coldbase,"MyKey",nil,function(arg)
	if arg then
		minetest.log("Found key")
	else
		minetest.log("Key not found")
	end
end)

6. delete key(file) this function works on both keys and key-value keys.

colddb.remove(coldbase,"MyKeyAndValue")

7. if add_to_mem_pool is true(true by default). keys are stored in a weak lua table(memory) it will be removed by the gc if its not in-use. Storing data in memory is to prevent the database from constantly loading up data from files.

coldbase.add_to_mem_pool = true

8. if indexes is true(false by default). When a key file is created an indexing file stores the key for look-ups. this makes it possible to iterate through keys.

coldbase.indexes = true

9. only if coldbase.indexes is true. returns the amount of keys that are in the indexing file.

colddb.get_count(coldbase)

10. only if coldbase.indexes is true. iterates through the indexing file(breaks and ends if it reaches the end of the file).

colddb.iterate_index_table(coldbase,nil,func_list_keys,nil)

11. adds a folder which can be used in other functions that have tag_name arg.

colddb.add_tag(coldbase,"Extra_Folder",{"Extra","Folder"})

12. returns the tag name if the tag does not exists it creates one.

colddb.get_or_add_tag(coldbase,"Extra_Folder",{"Extra","Folder"})

13. remove tag by name.

colddb.remove_tag(coldbase,"Extra_Folder")

Quick Look

-- create an directory(watchlist) and link it as a database.
ip_db = colddb.get_db("watchlist")
-- add an extra folder to the directory.
colddb.add_global_tag(ip_db,"ips")

-- return a recorded ip address from the data base.
function ip_db.find(player,callback)
	colddb.get(ip_db,player,nil,callback)
end

-- Key is the file and file name. Value is the content's within the file.
-- global tag(ips)--->key(Player name)--->value(ip address)
function ip_db.record_ip(player,ip)
	colddb.set(ip_db,player,ip)
end

function ip_db.delete(player)
	colddb.remove(db,player)
end

-- When ever a player join's his/her ip address is recorded to the database by player name.
minetest.register_on_prejoinplayer(function(name, ip)
	ip_db.record_ip(name,ip)
end)

minetest.register_chatcommand("ip", {
	params = "<player>",
	description = "Get an player's ip address.",
    func = function(name, param)
		-- Get the ip record asynchronously.
		colddb.get(ip_db,param,nil,function(record)
			-- If database contains the record data then send it to the player.
			if record then
				minetest.chat_send_player(name,string.format("%s:%s",param,record))
			else
				-- No record was found.
				minetest.chat_send_player(name,"Can not find ip record.")
			end
		end)
    end
})

Quick Look Notes

In the example above we could also create a more complex ip database using tags. Creating tags named after the player then assigning the ip files to them.
This way we could store many ips associated with the player instead of just one ip.

API

• Functions

  • colddb.get_db(directory) --> db

  Creates an directory and links it as a database. Returns a 'db' obeject.

  • colddb.add_global_tag(db,tag)

  Adds an extra folder to the directory and advance the database to the added folder.

  • colddb.add_tag(db,name,tag)

  • Creates a folder from the given table in tag.

  • colddb.get_or_add_tag(db,name,tag) --> tag_name

  Returns a tag or creates a new one if does not exist.

  • colddb.remove_tag(db,name)

  Removes a tag.

  • colddb.get_count(db,tag_name) --> count

  Returns the count from the index table file.

  • colddb.iterate_index_table(db,begin_func,func_on_iterate,end_func,args,tag_name)

  • function iterates through the index table file.

    • begin_func(args) --> args

    • function that is ran before the loop begins.

    • func_on_iterate(key,index,args)

    • function that is ran in the for loop.

    • end_func(args)

    • end function that is ran after the for loop ends.

  • colddb.set(db,name,_table,tag_name)

  • Writes data to the database. Key-Value.

  • colddb.set_key(db,name,tag_name)

  • Writes data to the database. Key-nil.

  • colddb.get(db,name,tag_name,callback(arg))

  • Returns specified data from the database in a callback function.

  • colddb.get_key(db,name,tag_name,callback(arg))

  • Returns if the key exist in the database.

  • colddb.remove(db,name,tag_name)

  • Deletes the specified data from the database.

• Database object fields

  • indexes

  • If truth the database makes a indexing file for keys.

  • add_to_mem_pool

  • If truth when you get keys or values it gets cached in the memory for faster access next time.

License

ColdDB is distributed under the LGPLv2.1+ license.