colddb/README.md

ColdDB

ColdDB is a minetest mod that implements a serverless, NoSQL database engine.
It provides a key or key-value storage system using plain Lua tables. It also can iterate through the keys.
It is not required to add this mod to secure.trusted_mods this mod will still work.

Usage

Copy colddb.lua file to your minetest mod or game. Copy the code from colddb's init file to your mods init file
Then create a lua file for handling database's or any file you like.
Write this code in your lua file.

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

coldbase = colddb.get_db("mydb")

2. added 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 will return true, false, or nil)

local key_and_value = colddb.get(coldbase,"MyKeyAndValue")
local key = colddb.get_key(coldbase,"MyKey")

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 lua table(memory) for 30 seconds or more depending on its use. This is to prevent the database from constantly loading up the data file.

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 == true. returns the amount of keys are in the indexing file.

colddb.get_count(coldbase)

10. only if coldbase.indexes == true. iterates through the indexing file 50 times per game tick(breaks and ends if it reached the end of the file).

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

11. adds folders 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)
	local f = colddb.get(ip_db,player)
	if f then
		return f
	end
	return nil
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)

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)

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

  • colddb.add_tag(db,name,tag)

  • colddb.get_or_add_tag(db,name,tag)

  • colddb.remove_tag(db,name)

  • colddb.get_count(db,tag_name)

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

    • begin_func(args)

    • func_on_iterate(key,index,args)

    • end_func(args)

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

  • colddb.set_key(db,name,tag_name)

  • colddb.get(db,name,tag_name)

  • colddb.get_key(db,name,tag_name)

  • colddb.remove(db,name,tag_name)

• Database object fields

  • indexes

  • add_to_mem_pool

License

ColdDB is distributed under the LGPLv2.1+ license.