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 before environment: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:

  1. string value of key if found in database
  2. nil if the value is not in the database
  3. 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 under key. If value is nil, the given key is deleted from the database.

Parameters:

  • key string The key under which to store the value
  • value string The value to store in database.

Returns:

  1. true if the value was stored
  2. 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
generated by LDoc 1.3.12