colddb/README.md

125 lines
3.8 KiB
Markdown
Raw Normal View History

2018-11-06 03:05:04 +01:00
ColdDB
===========
2018-11-11 04:40:49 +01:00
ColdDB is a minetest mod that implements a serverless, asynchronous, NoSQL database engine.<br>
2018-11-12 06:48:15 +01:00
It provides a key or key-value storage system using plain Lua tables, also it can iterate through the keys.<br>
2018-11-06 05:13:37 +01:00
Usage
===========
2018-11-12 06:48:15 +01:00
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<br>
2018-11-06 05:13:37 +01:00
Write this code in your lua file.
1. create a directory and link it as a database.
```lua
2019-01-08 07:32:34 +01:00
coldbase = colddb.Colddb("mydb")
2018-11-06 05:13:37 +01:00
```
2018-11-12 06:48:15 +01:00
2. add an extra folder to the directory. every new file will be added to the global tag(folder).
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.add_global_tag("ips")
2018-11-06 05:13:37 +01:00
```
3. store key item(this key has no value)
```lua
2019-01-08 07:32:34 +01:00
coldbase.set_key("MyKey")
2018-11-06 05:13:37 +01:00
```
4. store key-value item
```lua
2019-01-08 07:32:34 +01:00
coldbase.set("MyKeyAndValue", "Hello world")
2018-11-06 05:13:37 +01:00
```
2018-11-11 04:40:49 +01:00
5. retrieve items (get_key's callback(arg) will return true, false, or nil)
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.get("MyKeyAndValue", nil, function(arg)
2018-11-11 04:40:49 +01:00
if arg then
2019-01-08 07:32:34 +01:00
minetest.log(string.format("value:%s", arg))
2018-11-11 04:40:49 +01:00
end
end)
2019-01-08 07:32:34 +01:00
coldbase.get_key("MyKey", nil, function(arg)
2018-11-11 04:40:49 +01:00
if arg then
minetest.log("Found key")
else
minetest.log("Key not found")
end
end)
2018-11-06 05:13:37 +01:00
```
6. delete key(file) this function works on both keys and key-value keys.
```lua
2019-01-08 07:32:34 +01:00
coldbase.remove("MyKeyAndValue")
2018-11-06 05:13:37 +01:00
```
2018-11-11 04:40:49 +01:00
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.
2018-11-06 05:13:37 +01:00
```lua
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.
```lua
coldbase.indexes = true
```
2018-11-12 06:48:15 +01:00
9. only if coldbase.indexes is true. returns the amount of keys that are in the indexing file.
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.get_count()
2018-11-06 05:13:37 +01:00
```
2018-11-12 06:48:15 +01:00
10. only if coldbase.indexes is true. iterates through the indexing file(breaks and ends if it reaches the end of the file).
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.iterate_index_table(nil, func_list_keys, nil)
2018-11-06 05:13:37 +01:00
```
2018-11-12 06:48:15 +01:00
11. adds a folder which can be used in other functions that have tag_name arg.
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.add_tag("Extra_Folder", {"Extra", "Folder"})
2018-11-06 05:13:37 +01:00
```
2018-11-06 06:55:07 +01:00
12. returns the tag name if the tag does not exists it creates one.
2018-11-06 05:13:37 +01:00
```lua
2019-01-08 07:32:34 +01:00
coldbase.get_or_add_tag("Extra_Folder", {"Extra", "Folder"})
2018-11-06 05:13:37 +01:00
```
13. remove tag by name.
```lua
2019-01-08 07:32:34 +01:00
coldbase.remove_tag("Extra_Folder")
2018-11-06 05:13:37 +01:00
```
Quick Look
===========
```lua
-- create an directory(watchlist) and link it as a database.
2019-01-08 07:32:34 +01:00
ip_db = colddb.Colddb("watchlist")
2018-11-06 05:13:37 +01:00
-- 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)
2019-01-08 07:32:34 +01:00
ip_db.set(name, ip, ip_db.get_or_add_tag("ips", "ips"))
2018-11-06 05:13:37 +01:00
end)
2018-11-11 04:40:49 +01:00
minetest.register_chatcommand("ip", {
params = "<player>",
description = "Get an player's ip address.",
func = function(name, param)
-- Get the ip record asynchronously.
2019-01-08 07:32:34 +01:00
ip_db.get(param, ip_db.get_or_add_tag("ips", "ips"), function(record)
-- If record is contains data send it to the player.
2018-11-11 04:40:49 +01:00
if record then
2019-01-08 07:32:34 +01:00
minetest.chat_send_player(name, string.format("%s:%s", param, record))
2018-11-11 04:40:49 +01:00
else
-- No record was found.
2019-01-08 07:32:34 +01:00
minetest.chat_send_player(name, "Can not find ip record.")
2018-11-11 04:40:49 +01:00
end
end)
end
})
2019-01-08 07:32:34 +01:00
minetest.register_chatcommand("clear", {
params = "<player>",
description = "Clear out the ip database.",
func = function(name, param)
ip_db.remove_tag(ip_db.get_or_add_tag("ips", "ips"))
minetest.chat_send_player(name, "Ip Database Cleared!")
end
})
2018-11-06 05:13:37 +01:00
```
Quick Look Notes
===========
2018-11-06 06:55:07 +01:00
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.<br>
2018-11-06 05:13:37 +01:00
This way we could store many ips associated with the player instead of just one ip.
License
===========
ColdDB is distributed under the LGPLv2.1+ license.