Establishing a connection¶

DR::Tarantool::AsyncClient

        DR::Tarantool::AsyncClient->connect(
                host    => $host,
                port    => $port,
                spaces  => { ... },
                sub {
                        my ($tnt) = @_;
                        ...
                }
        );

The callback passed to connect() gets invoked after a connection is established. The only argument of the callback is the newly established connection handle. The handle's type is DR::Tarantool::AsyncClient.

DR::Tarantool::CoroClient and DR::Tarantool::SyncClient

        my $tnt = DR::Tarantool::SyncClient->connect(
                host    => $host,
                port    => $port,
                spaces  => { ... }
        );
        my $tnt = DR::Tarantool::CoroClient->connect(
                host    => $host,
                port    => $port,
                spaces  => { ... }
        );

The only difference of synchronous versions from the asynchronous one is absence of a callback. The created connection handle is returned directly from connect(). In this spirit, the only difference of any synchronous API all from the asynchronous counterpart is also in absence of the callback.

Working with tuples¶

Querying

        my $user123 = $tnt->select('users' => 123);
        my $users_by_roles = $tnt->select('users' => 'admins' => 'role_index');

It is possible to select data by a primary key (expects a Perl scalar), secondary, multi-part key (expects an array).

The default index used for selection is the primary one, a non-default index can be set by providing index name.

The contents of the result set is interpreted in accordance with schema description provided in DR::Tarantool::Spaces. Supported data types are numbers, Unicode strings, JSON, fixed-point decimals.

Insertion

        $tnt->insert('users' => [ 123, 'vasya', 'admin' ]);

Insert a tuple into space 'users', defined in spaces hash on connect.

Deletion

        $tnt->delete(users => 123);

Delete a tuple from space 'users'. The deletion is always performed by the primary key.

Update

        $tnt->update(users => 123 => [[ role => set => 'not_admin' ]]);

It is possible to modify any field in a tuple. A field can be accessed by field name or number. A set of modifications can be provided in a Perl array.

The following update operations are supported:

set

Assign a field

add, and, or, xor

Arithmetic and bitwise operations for integers.

substr

Replace a substring with a paste (similar to Perl splice).

insert

Insert a field before the given field.

delete

Delete a field.

push

Append a field at the tail of the tuple.

pop

Pop a field from the tail of the tuple.

Lua

        $tnt->call_lua(my_proc_name => [ arguments, ...]);

Invoke a Lua stored procedure by name.

Supported data types¶

The driver supports all Tarantool types (NUM, NUM64, STR), as well as some client-only types, which are converted to the above server types automatically on the client:

UTF8STR

A unicode string.

MONEY

Fixed decimal currency. Stores the value on the server in NUM type, by multiplying the given amount by 100. The largest amount that can be stored in this type is, therefore, around 20 000 000. Can store negative values.

BIGMONEY

The same as above, but uses NUM64 as the underlying storage.

JSON

An arbitrary Perl object is automatically serialized to JSON with JSON::XS on insertion, and deserialized on selection.

The basic data transfer unit in Tarantool protocol is a single tuple. A selected tuple is automatically wrapped into an instance of class DR::Tarantool::Tuple. An object of this class can be used as an associative container, in which any field can be accessed by field name:

        my $user = $tnt->select(users => 123);
        printf("user: %s, role: %s\n", $user->name, $user->role);

To run driver tests, the following Perl modules are also necessary: AnyEvent, Coro, Test::Pod, Test::Spelling, Devel::GlobalDestruction, JSON::XS.

To run tests, do:
perl Makefile.PL
make
make test

The test suite attempts to find the server and start it, thus make sure tarantool_box is available in the path, or export TARANTOOL_BOX=/path/to/tarantool_box.

tarantool¶

connects to Tarantool <http://tarantool.org> in synchronous mode using DR::Tarantool::SyncClient.

rsync_tarantool¶

connects to Tarantool <http://tarantool.org> in synchronous mode using DR::Tarantool::RealSyncClient.

async_tarantool¶

connects to tarantool <http://tarantool.org> in async mode using DR::Tarantool::AsyncClient.

coro_tarantol¶

connects to tarantool <http://tarantool.org> in async mode using DR::Tarantool::CoroClient.

:constant¶

Exports constants to use in a client request as flags:

TNT_FLAG_RETURN

With this flag on, each INSERT/UPDATE request returns the new value of the tuple. DELETE returns the deleted tuple, if it is found.

TNT_FLAG_ADD

With this flag on, INSERT returns an error if an old tuple with the same primary key already exists. No tuple is inserted in this case.

TNT_FLAG_REPLACE

With this flag on, INSERT returns an error if an old tuple for the primary key does not exist. Without either of the flags, INSERT replaces the old tuple if it doesn't exist.

:all¶

Exports all functions and constants.