Module sophia
lua-sophia, a Lua binding to the Sophia embeddable key-value database.
The database stores only Lua string keys and values, for storing more complex types use a serialization library, such as MessagePack.
Usage:
local sophia = require "sophia"
local env = sophia.env() -- create a new environment
env:ctl("dir", "db") -- set the directory where the database is/will be stored
local db = ctl:open() -- open the database handle
-- store and retrieve a value
db:set("greeting", "Hello world!")
print(db:get("greeting")) --> Hello world!
Info:
- Author: Michal Kottman
Functions
env () | Create a new Sophia environment handle. |
Class environment
environment:ctl (option, ...) | Configure a database. |
environment:open () | Open a database. |
Class database
database:begin () | Begin a transaction. |
database:commit () | Commit a transaction. |
database:rollback () | Rollback a transaction. |
database:get (key) | Retrieve a value from the database. |
database:set (key, value) | Set or delete a value in the database. |
database:cursor () | Iterate over the keys and values in the database. |
Functions
- env ()
-
Create a new Sophia environment handle. This can be used to open database handles.
Returns:
-
environment
A new environment
Class environment
- environment:ctl (option, ...)
-
Configure a database.
Currently only
"dir"
option is supported. This needs to be run beforeenvironment:open()
to set the directory where data is stored. Example:env:ctl("dir", "db-directory")
Parameters:
- option string An option to configure
- ... Additional data for the given option
Returns:
-
true on success, nil, message on error
- environment:open ()
-
Open a database. You need to set the database directory by using
environment:ctl("dir")
before opening the database.Returns:
-
database
on success, nil, message on error
Class database
- database:begin ()
-
Begin a transaction.
During transaction, all updates are not written to the database files until a database:commit is called. All updates made during transaction are available through database:get or by using cursor.
Returns:
-
true on success, nil, message on error
- database:commit ()
-
Commit a transaction.
This function is used to apply changes of a multi-statement transaction. All modifications made during the transaction are written to the log file in a single batch. If commit failed, transaction modifications are discarded.
Returns:
-
true on success, nil, message on error
- database:rollback ()
-
Rollback a transaction.
This function is used to discard a changes of a multi-statement transaction. All modifications made during the transaction are not written to the log file.
Returns:
-
true on success, nil, message on error
- database:get (key)
-
Retrieve a value from the database.
If the
key
is not in the database, it return nil, as in standard Lua table lookup. In case of error while retrieving the value, it returns an extra error message.Parameters:
- key string The key to lookup in the database
Returns:
-
string
value of
key
if found in database - nil if the value is not in the database
- nil, message in case there was an error retrieving the value
- database:set (key, value)
-
Set or delete a value in the database.
The
value
is stored in the database underkey
. Ifvalue
is nil, the given key is deleted from the database.Parameters:
Returns:
- true if the value was stored
- nil, message in case there was an error retrieving the value
- database:cursor ()
-
Iterate over the keys and values in the database.
This function returns values necessary for the
for
Lua iterator. Example:for k, v in db:cursor() do print(k, v) end
Returns:
-
values necessary for the
for
iterator