DESCRIPTION

KiokuDB is a Moose based frontend to various data stores, somewhere in between Tangram and Pixie.

Its purpose is to provide persistence for "regular" objects with as little effort as possible, without sacrificing control over how persistence is actually done, especially for harder to serialize objects.

KiokuDB is also non-invasive: it does not use ties, AUTOLOAD, proxy objects, sv_magic or any other type of trickery.

Many features important for proper Perl space semantics are supported, including shared data, circular structures, weak references, tied structures, etc.

Collapsing is explained in detail in KiokuDB::Collapser. The way an entry is created varies with the object's class.

Linking

When objects are loaded, entries are retrieved from the backend using their UIDs.

When a UID is already loaded (in the live object set of a KiokuDB instance, see KiokuDB::LiveObjects) the live object is used. This way references to shared objects are shared in memory regardless of the order the objects were stored or loaded.

Lastly, root set membership may also be specified explicitly by the typemap.

A root set member must be explicitly removed using delete or by removing it from the root set. Only non-members of the root set will be purged with any garbage collection scheme.

TRANSACTIONS

On supporting backends the txn_do method will execute a block and commit the transaction at its end.

Nesting of txn_do blocks is always supported, though rolling back a nested transaction may produce different results on different backends.

If the backend does not support transactions txn_do simply executes the code block normally.

CONCURRENCY

Most transactional backends are also concurrent.

KiokuDB::Backend::BDB and KiokuDB::Backend::CouchDB default to serializable transaction isolation and do not suffer from deadlocks, but serialization errors may occur, aborting the transaction (in which case the transaction should be tried again).

Concurrency support in KiokuDB::Backend::DBI depends on the database. SQLite defaults to serializable transaction isolation out of the box, wheras MySQL and PostgreSQL default to read committed.

Depending on your application read committed isolation may be sufficient, but due to the graph structure nature of the data repeatable reads or serializable level isolation is highly recommended. Read committed isolation generally works well when each row in the database is more or less independent of others, and various constraints ensure integrity. Unfortunately this is not the case with the graph layout.

METHODS

$dsn represents some sort of backend (much like DBI dsns map to DBDs).

An example DSN is:

my $dir = KiokuDB->connect("bdb:dir=path/to/data/");

The backend moniker name is extracted by splitting on the colon. The rest of the string is passed to new_from_dsn, which is documented in more detail in KiokuDB::Backend.

Typically DSN arguments are separated by ;, with = separating keys and values. Arguments with no value are assumed to denote boolean truth (e.g. jspon:dir=foo;pretty means dir => "foo", pretty => 1). However, a backend may override the default parsing, so this is not guaranteed.

Extra arguments are passed both to the backend constructor, and the KiokuDB constructor.

Note that if you need a typemap you still need to pass it in:

KiokuDB->connect( $dsn, typemap => $typemap );

The DSN can also be a valid JSON string taking one of the following forms:

This allows more complicated arguments to be specified accurately, or arbitrary options to be specified when the backend has nonstandard DSN parsing (for instance KiokuDB::Backend::DBI simply passes the string to DBI, so this is necessary in order to specify options on the command line).