fskv - kv Database, power failure does not lose data

Adapted Air780E/Air700E Air780EP Air601 Air101/Air103 Air105 ESP32C3 ESP32S3

Note

This page document is automatically generated by this file. If there is any error, please submit issue or help modify pr, thank you！

Tip

This library has its own demo,click this link to view the demo example of fskv

Example

-- The goal of this library is to replace the fdb library
-- 1. Fdb-compatible functions
-- 2. Use fdb's flash space and replace the fdb library when enabled.
-- 3. Functionally similar to EEPROM
fskv.init()
fskv.set("wendal", 1234)
log.info("fskv", "wendal", fskv.get("wendal"))

--[[ 
fskv differences caused by the implementation mechanism with fdb

                    fskv          fdb
1. value Length        4096           255
2. key Length          63             64
3. Space utilization (comparison) Lower Higher
4. Read speed constant dirty data affect speed, non-constant
5. Write data constant dirty data affects speed, non-constant
6. Equalizing Erase Automatic
]]

fskv.init()

Initialize the kv database

Parameters

None

Return Value

return value type	explanation
boolean	Returns true on success, otherwise false

Examples

if fskv.init() then
    log.info("fdb", "kv Database initialization successful")
end

-- About emptying the fdb library
-- The download tool does not provide a way to directly clear fdb data, but there are ways to solve it.
-- Write a main.lua, execute fskv.kvdb_init and then execute fskv.clear() to clear fdb data.

---

fskv.set(key, value)

set a pair of kv data

Parameters

Incoming Value Type	Explanation
string	key Name of, required, cannot be empty string
string	User data, required, cannot be nil, supports string/value/table/boolean, data length up to 4095 bytes

Return Value

return value type	explanation
boolean	Returns true on success, otherwise false

Examples

-- Set data, string, value, table, Boolean value, can be
-- But it can't be nil, function, userdata, task
log.info("fdb", fskv.set("wendal", "goodgoodstudy"))
log.info("fdb", fskv.set("upgrade", true))
log.info("fdb", fskv.set("timer", 1))
log.info("fdb", fskv.set("bigd", {name="wendal",age=123}))

---

fskv.sett(key, skey, value)

Set the key-value pair data in the table.

Parameters

Incoming Value Type	Explanation
string	key Name of, required, cannot be empty string
string	table The key name of the, required, cannot be an empty string
string	User data, required, supports string/value/table/boolean, data length up to 4095 bytes

Return Value

return value type	explanation
boolean	Returns true on success, otherwise false/nil

Examples

-- This API was added on July 26, 2023.26. Note the difference with the set function.
-- Set data, string, value, table, Boolean value, can be
-- But it can't be function, userdata, task
log.info("fdb", fskv.sett("mytable", "wendal", "goodgoodstudy"))
log.info("fdb", fskv.sett("mytable", "upgrade", true))
log.info("fdb", fskv.sett("mytable", "timer", 1))
log.info("fdb", fskv.sett("mytable", "bigd", {name="wendal",age=123}))

-- The following statement will print out 4 elements of table
log.info("fdb", fskv.get("mytable"), json.encode(fskv.get("mytable")))
-- Note: If the key does not exist or the original value is not of the table type, it will be completely overwritten.
-- For example, in the following way, the final result is table instead of the string in the first line.
log.info("fdb", fskv.set("mykv", "123"))
log.info("fdb", fskv.sett("mykv", "age", "123")) -- The saved will be {age:"123"}


-- If the set data is filled with nil, it means that the corresponding key
log.info("fdb", fskv.sett("mykv", "name", "wendal"))
log.info("fdb", fskv.sett("mykv", "name")) -- Equivalent to delete
-- 

---

fskv.get(key, skey)

Obtain the corresponding data according to the key.

Parameters

Incoming Value Type	Explanation
string	key Name of, required, cannot be empty string
string	Optional secondary key, valid only when the original value is table, equivalent fskv.get(key)[skey]

Return Value

return value type	explanation
any	Returns data if it exists, otherwise nil

Examples

if fskv.init() then
    log.info("fdb", fskv.get("wendal"))
end

-- If "default value" is required, corresponding to a non-bool Boolean value, it can be written as follows
local v = fskv.get("wendal") or "123"

---

fskv.del(key)

Delete data based on key

Parameters

Incoming Value Type	Explanation
string	key Name of, required, cannot be empty string

Return Value

return value type	explanation
bool	Returns true on success, otherwise false

Examples

log.info("fdb", fskv.del("wendal"))

---

fskv.clear()

empty the entire kv database

Parameters

None

Return Value

return value type	explanation
bool	Returns true on success, otherwise false

Examples

-- Empty
fskv.clear()

---

fskv.iter()

kv Database Iterators

Parameters

None

Return Value

return value type	explanation
userdata	Returns an iterator pointer on success, otherwise nil

Examples

-- Empty
local iter = fskv.iter()
if iter then
    while 1 do
        local k = fskv.next(iter)
        if not k then
            break
        end
        log.info("fdb", k, "value", fskv.kv_get(k))
    end
end

---

fskv.next(iter)

kv Iterator to get the next key

Parameters

Incoming Value Type	Explanation
userdata	fskv.iter()Pointer returned

Return Value

return value type	explanation
string	Returns the string key value on success, otherwise nil

Examples

-- Empty
local iter = fskv.iter()
if iter then
    while 1 do
        local k = fskv.next(iter)
        if not k then
            break
        end
        log.info("fskv", k, "value", fskv.get(k))
    end
end

---

fskv.status()

obtain kv database status

Parameters

None

Return Value

return value type	explanation
int	Space used in bytes
int	Total available space in bytes
int	total number of kv key-value pairs, units

Examples

local used, total,kv_count = fskv.status()
log.info("fdb", "kv", used,total,kv_count)

---