The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Anansi::Database - A manager for database interaction.

SYNOPSIS

    my $OBJECT = Anansi::Database->new();
    my $component = $OBJECT->addComponent(
        undef,
        DRIVER => 'MySQL',
    );
    if(defined($component)) {
        if($OBJECT->channel(
            'CONNECT',
            $component,
            DATABASE => 'someDatabase',
            PASSWORD => 'somePassword',
            USERNAME => 'someUser',
        )) {
            my $records = $OBJECT->channel(
                'STATEMENT',
                $component,
                INPUT => [
                    {
                        DEFAULT => '0',
                        NAME => 'yetAnotherField',
                    }
                ],
                SQL => 'SELECT some_field, another_field FROM some_table WHERE yet_another_field = ?;',
                yetAnotherField => 123,
            );
            if(defined($records)) {
                if(ref($records) =~ /^ARRAY$/i) {
                    my $record = 0;
                    foreach my $record (@{$records}) {
                        next if(ref($record) !~ /^HASH$/i);
                        print "\n" if(0 < $record);
                        my $field = 0;
                        foreach my $key (keys(%{$record})) {
                            print ', ' if(0 < $field);
                            print '"'.$key.'" = "'.${record}{$key}.'"';
                            $field++;
                        }
                        $record++;
                    }
                    print "\n";
                }
            }
        }
    }

DESCRIPTION

Manages database interactions allowing the creation, interrogation, modification and removal of database structures and table records.

METHODS

Anansi::Class

See Anansi::Class for details. A parent module of Anansi::Singleton.

DESTROY

See Anansi::Class::DESTROY for details. Overridden by Anansi::Singleton::DESTROY.

finalise

See Anansi::Class::finalise for details. A virtual method.

implicate

See Anansi::Class::implicate for details. A virtual method.

import

See Anansi::Class::import for details.

initialise

See Anansi::Class::initialise for details. Overridden by Anansi::ComponentManager::initialise. A virtual method.

new

See Anansi::Class::new for details. Overridden by Anansi::Singleton::new.

old

See Anansi::Class::old for details.

used

See Anansi::Class::used for details.

uses

See Anansi::Class::uses for details.

using

See Anansi::Class::using for details.

Anansi::ComponentManager

See Anansi::ComponentManager for details. A parent module of Anansi::Database.

Anansi::Singleton

See Anansi::Singleton for details. A parent module of Anansi::ComponentManager.

addChannel

See Anansi::ComponentManager::addChannel for details.

addComponent

See Anansi::ComponentManager::addComponent for details.

channel

See Anansi::ComponentManager::channel for details.

component

See Anansi::ComponentManager::component for details.

componentIdentification

See Anansi::ComponentManager::componentIdentification for details.

components

See Anansi::ComponentManager::components for details.

initialise

See Anansi::ComponentManager::initialise for details. Overrides Anansi::Class::initialise. A virtual method.

priorities

See Anansi::ComponentManager::priorities for details.

reinitialise

See Anansi::ComponentManager::reinitialise for details. Overrides Anansi::Singleton::reinitialise. A virtual method.

removeChannel

See Anansi::ComponentManager::removeChannel for details.

removeComponent

See Anansi::ComponentManager::removeComponent for details.

Anansi::Singleton

See Anansi::Singleton for details. A parent module of Anansi::ComponentManager.

Anansi::Class

See Anansi::Class for details. A parent module of Anansi::Singleton.

DESTROY

See Anansi::Singleton::DESTROY for details. Overrides Anansi::Class::DESTROY.

fixate

See Anansi::Singleton::fixate for details. A virtual method.

new

See Anansi::Singleton::new for details. Overrides Anansi::Class::new.

reinitialise

See Anansi::Singleton::reinitialise for details. Overridden by Anansi::ComponentManager::reinitialise. A virtual method.

connect

    my $component = Anansi::Database->addComponent();
    my $connection = Anansi::Database->connect(
        undef,
        $component,
        DATABASE => 'someDatabase',
        PASSWORD => 'somePassword',
        USERNAME => 'someUsername',
    );
    if(!defined($connection));

    my $handle = DBI->connect('DBI:mysql:someDatabase', 'someUsername', 'somePassword');
    my $component = Anansi::Database->addComponent();
    my $connection = Anansi::Database->channel(
        'CONNECT',
        $component,
        HANDLE => $handle,
    );
    if(!defined($connection));
self (Blessed Hash or String, Required)

Either an object or a string of this namespace.

channel (String, Required)

The abstract identifier of a subroutine.

component (String, Required)

The name associated with the component.

parameters (Hash, Optional)

Named parameters.

Attempts to load the appropriate database driver and connect to a database. Returns 1 (one) on success and 0 (zero) on failure. Returns an undef when an error occurs.

disconnect

    my $component = Anansi::Database->addComponent();
    my $connection = Anansi::Database->connect(undef, $component);
    if(defined($connection)) (
        Anansi::Database->disconnect(undef, $component);
    }

    my $component = Anansi::Database->addComponent();
    my $connection = Anansi::Database->channel('CONNECT', $component);
    if(defined($connection)) {
        Anansi::Database->channel('DISCONNECT', $component)
    }
self (Blessed Hash or String, Required)

Either an object or a string of this namespace.

channel (String, Required)

The abstract identifier of a subroutine.

component (String, Required)

The name associated with the component.

parameters (Hash, Optional)

Named parameters.

Attempts to disconnect from a database. Returns 1 (one) on success and 0 (zero) on failure. Returns an undef when an error occurs.

statement

    my $result = Anansi::Database::statement(
        $OBJECT,
        undef,
        INPUT => [
            'hij' => 'someParameter',
            'klm' => 'anotherParameter'
        ],
        SQL => 'SELECT abc, def FROM some_table WHERE hij = ? AND klm = ?;',
        STATEMENT => 'someStatement',
        someParameter => 123,
        anotherParameter => 456
    );

    my $result = Anansi::Database::channel(
        $OBJECT,
        'STATEMENT',
        STATEMENT => 'someStatement',
        someParameter => 234,
        anotherParameter => 'abc'
    );

    my $result = $OBJECT->statement(
        undef,
        STATEMENT => 'someStatement',
        someParameter => 345,
        anotherParameter => 789
    );

    my $result = $OBJECT->channel(
        'STATEMENT',
        STATEMENT => 'someStatement',
        someParameter => 456,
        anotherParameter => 'def'
    );
self (Blessed Hash or String, Required)

Either an object or a string of this namespace.

channel (String, Required)

The abstract identifier of a subroutine.

component (String, Required)

The name associated with the component.

parameters (Hash, Optional)

Named parameters.

INPUT (Array, Optional)

An array of hashes with each element corresponding to an equivalent ? (Question mark) found within the supplied SQL. If the number of elements is not the same as the number of ? (Question mark)s found in the statement then the statement is invalid. See the Anansi::DatabaseComponent::bind method for details.

SQL (String, Optional)

The SQL statement to execute.

STATEMENT (String, Optional)

The name associated with a prepared SQL statement. This is interchangeable with the SQL parameter but helps to speed up repetitive database interaction.

Attempts to execute the supplied SQL with the supplied named parameters. Either returns an array of retrieved record data or a 1 (one) on success and a 0 (zero) on failure as appropriate to the SQL statement. Returns an undef when an error occurs.

NOTES

This module is designed to make it simple, easy and quite fast to code your design in perl. If for any reason you feel that it doesn't achieve these goals then please let me know. I am here to help. All constructive criticisms are also welcomed.

AUTHOR

Kevin Treleaven <kevin AT treleaven DOT net>