/ 
Arango-Tango-0.019
River stage zero No dependents
/ Arango::Tango

NAME

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

VERSION

version 0.019

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 straightforward 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.

scheme

HTTP scheme to use. Defaults to http.

Error Checking

http_status

Returns the last HTTP status code.

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.

CONTRIBUTORS

  • João Miguel Ferreira

AUTHOR

Alberto Simões <ambs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019-2023 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.