NAME

XAO::DO::FS::Glue::Connect_DBI - DBI/DBD base for XAO::FS drivers

SYNOPSIS

 use XAO::Objects;
 use base XAO::Objects->load(objname => 'FS::Glue::SQL_DBI');

 sub foo {
    my $self=shift;
    $self->sql_connect(
        dsn      => 'DBI:mysql:test_fs',
        user     => 'test',
        password => 'test',
    );
 }

DESCRIPTION

This module provides a base for all XAO::FS SQL drivers that choose to be based on DBI/DBD foundation.

METHODS

sql_connect (%)

Establishes a connection to the database engine given. Arguments are:

 dsn        => standard DBI data source
 user       => optional user name
 password   => optional password

sql_connected ()

Checks and returns true if the database connection is currently established.

sql_disconnect ()

Closes connection to the database.

sql_do ($;@)

Sends a single query to the database with no anticipation of any results. Can take arguments just the way prepare/execute do.

It is allowed to call sql_do() with an array reference in the second argument.

sql_execute ($;@)

Executes a previously prepared statement optionally substituting some values, see sql_prepare(). Example:

 my $pq=$self->sql_prepare("SELECT a,b FROM c WHERE d=?");
 foreach my $value (1..10) {
     $self->sql_execute($pq,$i);
     ...
 }

As a shortcut it can also accept a text query in the first argument instead of manually calling sql_prepare() first. It is suggested to do so whenever you plan to call sql_execute() just once.

It is allowed to call sql_execute() with an array reference in the second argument.

Returns a piece of data that should be passed into sql_fetch_row() method.

When done sql_finish() should be called with the return value of sql_execute() as a parameter.

sql_fetch_row ($)

Returns a reference to an array containing next retrieved row. Example:

 my $qr=$self->sql_execute("SELECT a,b FROM c");
 my $row=$self->sql_fetch_row($qr);

Don't forget to call sql_finish() when you're done.

sql_finish ($)

Frees up whatever internal structures might be occupied as a result of the previous call to sql_execute(). Example:

 my $qr=$self->sql_execute("SHOW TABLES");
 ...
 $self->sql_finish($qr);

sql_first_column ($)

An optimisation method -- returns a reference to the array containing all first elements of each row of the results set. Example:

 my $qr=$self->sql_execute("SELECT unique_id FROM a");
 my $ids=$self->sql_first_column($qr);

There is no need to call sql_finish() after sql_first_column().

sql_first_row ($)

An optimisation method -- returns a reference to the first row and finished the query.

 my $qr=$self->sql_execute("SELECT a,b,c FROM t WHERE d=?",$uid);
 my $row=$self->sql_first_row($qr);

There is no need to call sql_finish() after sql_first_row().

sql_prepare ($)

Prepares a query for subsequent execution using sql_execute() method. Guaranteed to return a reference of some sort. Example:

 my $pq=$self->sql_prepare("SELECT a,b FROM c WHERE d=?");
 $self->sql_execute($pq,123);

AUTHORS

Copyright (c) 2005 Andrew Maltsev

Copyright (c) 2001-2004 Andrew Maltsev, XAO Inc.

<am@ejelta.com> -- http://ejelta.com/xao/

SEE ALSO

Further reading: XAO::FS, XAO::DO::FS::Glue.