Dmitry E. Oboukhov

NAME

DR::Tnt - driver/connector for tarantool

SYNOPSIS

    use DR::Tnt;    # exports 'tarantool'

    my $tnt = tarantool
                    host                => '1.2.3.4',
                    port                => 567,
                    user                => 'my_tnt_user',
                    password            => '#1@#$JHJH',
                    hashify_tuples      => 1,
                    driver              => 'sync',  # default
                    lua_dir             => '/path/to/my/luas',
                    reconnect_interval  => 0.5
    ;

    my $tuple = $tnt->get(space => 'index', [ 'key' ]);
    my $tuples = $tnt->select(myspace => 'myindex', [ 'key' ], $limit, $offset);

    my $updated = $tnt->update('myspace', [ 'key' ], [ [ '=', 1, 'name' ]]);
    my $inserted = $tnt->insert(myspace => [ 1, 2, 3, 4 ]);
    my $replaced = $tnt->replace(myspace => [ 1, 3, 4, 5 ]);

    my $tuples = $tnt->call_lua('box.space.myspace:select', [ 'key' ]);
    my $hashified_tuples =
        $tnt->call_lua([ 'box.space.myspace:select' => 'myspace' ], ['key' ]);


    my $removed = $tnt->delete(myspace => [ 'key' ]);
   
    my $tuples = $tnt->eval_lua('return 123');
    my $hashify_tuples = $tnt->eval_lua(['return 123' => 'myspace' ]);

DESCRIPTION

This module provides a synchronous and asynchronous driver for Tarantool.

The driver supports three work flow types:

DR::Tnt::Client::AE

The primary type, provides an asynchronous, callback-based API. Requires a running AnyEvent machine.

DR::Tnt::Client::Sync

Synchronous driver (based on IO::Socket::INET/IO::Socket::UNIX).

DR::Tnt::Client::Coro

Coro's driver, uses DR::Tnt::Client::AE.

The module does require and makes instance of selected driver.

METHODS

tarantool

Loads selected driver and returns connector.

You can choose one driver:

sync

DR::Tnt::Client::Sync will be loaded and created.

ae or async

DR::Tnt::Client::AE will be loaded and created.

coro

DR::Tnt::Client::Coro will be loaded and created.

Attributes

host, port

Connection point for tarantool instance. If host contains unix/, port have to contain valid unix path to opened socket.

user, password

Auth arguments.

lua_dir

Directory that contains some lua files. After connecting, the driver sends $tnt-eval_lua> for each file in the directory. So You can use the mechanizm to store some values to box.session.storage.

hashify_tuples

If the option is set to TRUE, then the driver will extract tuples to hash by box.space._space schema.

reconnect_interval

Internal to reconnect after disconnect or fatal errors. Undefined value disables the mechanizm.

raise_error

The option is actual for coro and sync drivers (DR::Tnt::Client::Coro and DR::Tnt::Client::Sync).

utf8

Default value is TRUE. If TRUE, driver will unpack all strings as utf8-decoded strings.

Information attributes

last_error

Contains array of last error. If there was no errors, the attrubute contains undef.

The array can contain two or three elements:

  • String error identifier. Example: ER_SOCKET or ER_REQUEST.

  • Error message. Example: 'Connection timeout'

  • Tarantool code. Optional parameter. Example 0x806D. The code is present only for tarantool errors (like lua error, etc).

CONNECTORS METHODS

All connectors have the same API. AnyEvent's connector has the last argument - callback for results.

If raise_error is false, coro and sync drivers will return undef and store last_error. Any successfuly call clears last_error attribute.

auth
    # auth by $tnt->user and $tnt->password
    if ($tnt->auth) {

    }

    if ($tnt->auth($user, $password) {

    }

Auth user in tarantool. Note: The driver uses <$tnt-user>> and <$tnt-password>> attributes after reconnects.

select
    my $list = $tnt->select($space, $index, $key);
    my $list = $tnt->select($space, $index, $key, $limit, $offset, $iterator);

Select tuples from space. You can use space/index's names or numbers.

Default values for $iterator is 'EQ', for $limit is 2**32, for $offset is 0.

get
    my $tuple = $tnt->get($space, $index, $key);

The same as select, but forces $limit to 1, $offset to 0, $iterator to 'EQ' and returns the first tuple of result list.

update
    my $updated = $tnt->update($space, $key, [[ '=', 3, 'name' ]]);

Update tuple in database.

insert
    my $inserted = $tnt->insert($space, [ $name, $value ]);
replace
    my $replaced = $tnt->replace($space, [ $name, $value ]);
delete
    my $deleted = $tnt->delete($space, $key);
call_lua
    my $tuples = $tnt->call_lua('my.lua.name', $arg1, $arg2);
    
    my $hashified_tuples = $tnt->call_lua(['box.space.name:select' => 'name'], 123);

If proc_name is ARRAYREF, result tuples will be hashified as tuples of selected space.

eval_lua
    my $tuples = $tnt->eval_lua('return {{1}}');
    my $hashified_tuples = $tnt->eval_lua(['return {{1}}' => 'name');
ping
    if ($tnt->ping) {
        # connection established.
    }