NAME

Database::Sophia - Sophia is a modern embeddable key-value database designed for a high load environment (XS for Sophia)

SYNOPSIS

 use Database::Sophia;
 
 my $env = Database::Sophia->sp_env();
 
 my $err = $env->sp_ctl(SPDIR, SPO_CREAT|SPO_RDWR, "./db");
 die $env->sp_error() if $err == -1;
 
 my $db = $env->sp_open();
 die $env->sp_error() unless $db;
 
 $err = $db->sp_set("login", "lastmac");
 print $db->sp_error(), "\n" if $err == -1;
 
 my $value = $db->sp_get("login", $err);
 
 if($err == -1) {
        print $db->sp_error(), "\n";
 }
 elsif($err == 0) {
        print "Key not found", "\n";
 }
 elsif($err == 1) {
        print "Key found", "\n";
        print "login: ", $value, "\n";
 }
 
 $db->sp_destroy();
 $env->sp_destroy();
 

DESCRIPTION

It has unique architecture that was created as a result of research and rethinking of primary algorithmic constraints, associated with a getting popular Log-file based data structures, such as LSM-tree.

See http://sphia.org/

METHODS

sp_env

create a new environment handle

 my $env = Database::Sophia->sp_env();

sp_ctl

configurate a database

SPDIR

Sets database directory path and it's open flags to use by sp_open().

 $env->sp_ctl(SPDIR, SPO_CREAT|SPO_RDWR, "./db");

Possible flags are:

SPO_RDWR - open repository in read-write mode (default)

SPO_RDONLY - open repository in read-only mode

SPO_CREAT - create repository if it is not exists.

SPCMP

Sets database comparator function to use by database for a key order determination.

 my $sub_cmp = sub {
        my ($key_a, $key_b, $arg) = @_;
 }
 
 $env->sp_ctl(SPCMP, $sub_cmp, "arg to callback");

SPPAGE

Sets database max key count in a single page. This option can be tweaked for performance.

 $env->sp_ctl(SPPAGE, 1024);

SPGC

Sets flag that garbage collector should be turn on.

 $env->sp_ctl(SPGC, 1);

SPGCF

Sets database garbage collector factor value, which is used to determine whether it is time to start gc.

 $env->sp_ctl(SPGCF, 0.5);

SPGROW

Sets new database files initial new size and resize factor. This values are used while database extend during merge.

 $env->sp_ctl(SPGROW, 16 * 1024 * 1024, 2.0);

SPMERGE

Sets flag that merger thread must be created during sp_open().

 $env->sp_ctl(SPMERGE, 1);

SPMERGEWM

Sets database merge watermark value.

 $env->sp_ctl(SPMERGEWM, 200000);

sp_open

Open or create a database

 my $db = $env->sp_open();

On success, return database object; On error, it returns undef.

sp_error

Get a string error description

 $env->sp_error();

sp_destroy

Free any handle

 $ptr->sp_destroy();

sp_begin

Begin a transaction

 $db->sp_begin();

sp_commit

Apply a transaction

 $db->sp_commit();

sp_rollback

Discard a transaction changes

 $db->sp_rollback();

sp_set

Insert or replace a key-value pair

 $db->sp_set("key", "value");

sp_get

Find a key in a database

 my $error;
 $db->sp_get("key", $error);

sp_delete

Delete key from a database

 $db->sp_delete("key");

sp_cursor

create a database cursor

 my $cur = $db->sp_cursor(SPGT, "key");

Possible order are:

SPGT - increasing order (skipping the key, if it is equal)

SPGTE - increasing order (with key)

SPLT - decreasing order (skippng the key, if is is equal)

SPLTE - decreasing order

After a use, cursor handle should be freed by $cur->sp_destroy() function.

sp_fetch

Iterate a cursor

 $cur->sp_fetch();

sp_key

Get current key

 $cur->sp_key()

sp_keysize

 $cur->sp_keysize()

sp_value

 $cur->sp_value()

sp_valuesize

 $cur->sp_valuesize()

Example

sp_open

 use Database::Sophia;
 
 my $env = Database::Sophia->sp_env();
 
 my $err = $env->sp_ctl(SPDIR, SPO_CREAT|SPO_RDWR, "./db");
 die $env->sp_error() if $err == -1;
 
 my $db = $env->sp_open();
 die $env->sp_error() unless $db;

sp_error

 my $db = $env->sp_open();
 die $env->sp_error() unless $db;

sp_destroy

 $db->sp_destroy();
 $cur->sp_destroy();
 $env->sp_destroy();

sp_begin

 my $rc = $db->sp_begin();
 print $env->sp_error(), "\n" if $rc == -1;
 
 $rc = $db->sp_set("key", "value");
 print $env->sp_error(), "\n" if $rc == -1;
 
 $rc = $db->sp_commit();
 print $env->sp_error(), "\n" if $rc == -1;

sp_commit

See sp_begin

sp_rollback

 my $rc = $db->sp_begin();
 print $env->sp_error(), "\n" if $rc == -1;
 
 $rc = $db->sp_set("key", "value");
 print $env->sp_error(), "\n" if $rc == -1;
 
 $rc = $db->sp_rollback();
 print $env->sp_error(), "\n" if $rc == -1;

sp_set

 $rc = $db->sp_set("key", "value");
 print $env->sp_error(), "\n" if $rc == -1;

sp_get

 my $error;
 my $value = $db->sp_get("key", $error);
 
 if($error == -1) {
        print $db->sp_error(), "\n";
 }
 elsif($error == 0) {
        print "Key not found", "\n";
 }
 elsif($error == 1) {
        print "Key found", "\n";
        print "key: ", $value, "\n";
 }

sp_fetch

 my $cur = $db->sp_cursor(SPGT, "key");
 
 while($cur->sp_fetch()) {
        print $cur->sp_key(), ": ", $cur->sp_value();
        print $cur->sp_keysize(), ": ", $cur->sp_valuesize();
 }
 
 $cur->sp_destroy();

sp_key

See sp_fetch

sp_keysize

See sp_fetch

sp_value

See sp_fetch

sp_valuesize

See sp_fetch

DESTROY

 undef $obj;

Free mem and destroy object.

AUTHOR

Alexander Borisov <lex.borisov@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Alexander Borisov.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

See libsophia license and COPYRIGHT http://sphia.org/

cpanm Database::Sophia

perl -MCPAN -e shell
install Database::Sophia