The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Arango-Tango-0.011
River stage zero No dependents
++
/ Arango::Tango

NAME

Arango::Tango - A simple interface to ArangoDB REST API

VERSION

version 0.011

SYNOPSYS

    use Arango::Tango;

    my $server = Arango::Tango->new( host     => '127.0.0.1',
                                     username => 'root',
                                     password => '123123123');

    my $new_database = $server->create_database("mydb");
    my $collection = $server->create_collection("mycollection");
    $collection->create_document( { 'Hello' => 'World'} );

DISCLAIMER

The module is VERY incomplete. It is being written accordingly with my personal needs. While I tried ArangoDB2 it didn't work out of the box as I expected, and decided to write a simple strightforward solution.

Patches and suggestions are VERY welcome.

USAGE

The distribution is divided in different modules, namely:

Arango::Tango

This is the main module and hopefully the unique one you need to import in your code. It performs basic operations with the server, and returns objects of different kinds when needed.

Arango::Tango::Database

Represents a specific database. A simple object to keep track of the database you are working with, so you do not need to specify it everytime.

Arango::Tango::Collection

Represents a collection from a specific database. Again, it just keeps track of the collection name and the database where it resided.

METHODS

Constructor

new
      my $db = Arango::Tango->new( %options );

To start using the module you need a Arango::Tango instance. Use the new method to create one. Supported options are:

host

Host name. Defaults to localhost.

port

ArangoDB Port. Defaults to 8529.

username

Username to be used to connect to ArangoDB. Defaults to root.

password

Password to be used to connect to ArangoDB. Default to the empty string.

Database Manipulation

list_databases
    my $databases = $db->list_databases;

Retrieves the list of all databases the current user can access without specifying a different username or password.

create_database
    my $new_db = $db->create_database("new_db");

Creates a new database, and returns a reference to a Arango::Tango::Database representing it.

database
    my $system_db = $db->database("_system");

Opens an existing database, and returns a reference to a Arango::Tango::Database representing it.

delete_database
    $db->delete_database("some_db");

Deletes an existing database.

current_database
    $db->current_database;

Returns information about the current database. At the moment, to obtain an object representing it, use the database method.

User Management

create_user
    $db->create_user('username', passwd => "3432rfsdADF");

Creates an user. Optional parameters are passwd, active and extra.

update_user
    $db->update_user('username', extra => { email => 'me@there.com' } );

Updates an existing user. Optional parameters are passwd, active and extra.

replace_user
    $db->replace_user('username', extra => { email => 'me@there.com' } );

Replace an existing user. Optional parameters are passwd, active and extra.

delete_user
    $db->delete_user('username');

Deletes an user.

list_users
    $users = $db->list_users;

Fetches data about all users. You need the Administrate server access level in order to execute this REST call. Otherwise, you will only get information about yourself.

user
    $user = $db->user("john");

Fetches data about the specified user. You can fetch information about yourself or you need the Administrate server access level in order to execute this REST call.

user_databases
    $dbs = $db->user_databases("john", full => 1);

Fetch the list of databases available to the specified user. You need Administrate for the server access level in order to execute this REST call.

get_access_level
    $perms = $db->get_access_level("john", "myDatabase");
    $perms = $db->get_access_level("john", "myDatabase", $collection );

Fetch the database or the collection access level for a specific user.

set_access_level
    $perms = $db->set_access_level("john", "rw", "myDatabase");
    $perms = $db->set_access_level("john", "ro", "myDatabase", $collection);

Sets the database or the collection access level for a specific user.

clear_access_level
    $db->clear_access_level("john", "myDatabase");
    $db->clear_access_level("john", "myDatabase", $collection);

Clears the database or the collection access level for a specific user.

Querying Server Metadata

target_version
    my $ans = $db->target_version;
    $target_version = $ans->{target_version};   # might change in the future...

Returns the database version that this server requires. The version is returned in the version attribute of the result.

log
    my $logs = $db-a>log(upto => "warning");

Returns fatal, error, warning or info log messages from the server’s global log.

log_level
    my $log_levels = $db->log_level();

Returns the server’s current log level settings.

server_availability
    my $info = $db->server_availability();

Return availability information about a server.

server_id
    my $id = $db->server_id();

Returns the id of a server in a cluster. The request will fail if the server is not running in cluster mode.

server_mode
    my $mode = $db->server_mode();

Return mode information about a server.

server_role
    my $mode = $db->server_role();

Returns the role of a server in a cluster.

cluster_endpoints
    my $endpoints = $db->cluster_endpoints;

Returns an object with an attribute endpoints, which contains an array of objects, which each have the attribute endpoint, whose value is a string with the endpoint description. There is an entry for each coordinator in the cluster. This method only works on coordinators in cluster mode. In case of an error the error attribute is set to true.

version
    my $version_info = $db->version;
    my $detailed_info = $db->version( 'details' => 1 );

Returns a hash reference with basic server info. Detailed information can be requested with the details option.

engine
   my $engine = $db->engine;

Returns the storage engine the server is configured to use.

statistics
   my $stats = $db->statistics;

Read the statistics of a server.

statistics_description
   my $stats_desc = $db->statistics_description;

Statistics description

status
   my $status = $db->status;

Return status information

time
   my $time = $db->time;

Return system time

CAVEATS

Options Validation

Most optional options are validated and fitted using JSON::Scheme::Fit. This means that the module will try to remove invalid options and adapt values from valid options to valid values. While this can make some mistakes silently, it was preferred to dying at any structure problem.

In future versions there might be an option to activate strict schema check making the module to die on an invalid options.

Exceptions

This module is written to die in any exception. Please use a try/catch module or eval, to detect them.

AUTHOR

Alberto Simões <ambs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019-2020 by Alberto Simões.

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