view release on metacpan or  search on metacpan

lib/DBIx/DataStore.pm  view on Meta::CPAN

This method returns a hash reference containing the following information about
the currently selected reader database: name, driver, host and database.

=item last_insert_id()

This method is a pass-through for DBI's C<last_insert_id()> function.  All the
same caveats apply to this method.  But just in case you aren't familiar with
them, basically consider this method unreliable on many database servers.  It
should only be used with care, and only if you know your underlying RDBMS's
DBD driver will do The Right Thing.

=item ping()

This method, when called, attempts to issue a very simple SQL statement
(generally "select 1") against both the primary and reader database servers (or
primary only if no reader has been selected).  A true value will be returned if
the statements were successful.

=item schemas()

If called with no arguments, returns a list of the schemas currently in the
search path for the primary server connection.  If called with a list of
scalar arguments, sets the connection's search path to those schemas (in
the order they were provided).

=item servers()

Returns a list of hash references, detailing the database servers defined in the
YAML config file. All servers defined are returned, regardless of whether they
have, or will, respond to connections.

Within each hash reference the following key/value pairs are provided: name (as
defined in the configuration file), driver, host and database.  The first hash
reference in the returned list will always be the server defined as the primary,
followed by the readers sorted by their names.

=item tables()

This method returns a list of the table names that are present within the
currently selected database (schema) on the primary server.  The list returned
will also include views (use C<base_tables()> if you don't want the views).

=item views()

This method will return a list of the views defined within your current schema.

=back

=head1 RESULT SET METHODS

Every call to the C<do()> method on a database object which contains a
read-oriented SQL query returns a result set object.  These objects can then be
used to access the data contained within the database query's results.

=over

=item Hash and Array accessors

Each time you retrieve a record (aka "result row") from a query's result set,
the values for each column in that record can be transparently accessed through
hash keys (where the keys are the column names as defined by the original query)
or array indices (in the order the columns were defined by the query).  Both
methods of accessing the record's values are available at all times (unlike the
standard DBI methods where you have to choose up front between using
C<fetchrow_array[ref]()> or C<fetchrow_hashref()>).  Thus, something like the
following is perfectly acceptable:

    my $result = $db->do(q{
        select id, name from users order by name asc
    });
    while ($result->next) {
        print sprintf("ID %d: %s\n",
            $result->[0],
            $result->{'name'}
        );
    }

=item next()

Retrieves the next row of results from the result set.  The row's data is then
directly accessible through the result set object itself (see L</"Hash and Array
accessors">).  This method also returns a reference to the result set object,
making the following two snippets of code effectively identical (though the
second is unnecessarily verbose):

    while ($result->next) {
        print $result->{'some_col_name'};
    }

or

    while (my $row = $result->next) {
        print $row->{'some_col_name'};
    }

The return value will be undef when there are no more rows to retrieve from the
database.

=item next_hashref()

Similar to a next() call, in that it moves to the next row in the result set
(or returns an undefined value when all rows have been read already).  However,
this method returns a stand-alone hash reference containing as keys the column
names from the query, and as values the contents of the current row of the
result set.

=item hashref()

Returns the exact same data structure as next_hashref(), except that it does
not move to the next row in the result set first.  You get a hash representation
of the current row from the results, not the next row.

=item all()

This method retrieves all rows from the database at once and returns a list of
result set row objects, each one containing a single row from the result set.
It is functionally equivalent to the following:

    my (@rows);
    while (my $row = $result->next) {