NAME

Rose::DBx::CannedQuery::Glycosylated - Some sugar for Rose::DBx::CannedQuery

SYNOPSIS

  use Rose::DBx::CannedQuery::Glycosylated;
  my $qry = Rose::DBx::CannedQuery::Glycosylated->new(
              rdb_class => 'My::DB',
              rdb_params => { type => 'real', domain => 'some' },
              sql => 'SELECT * FROM table WHERE attr = ?',
              verbose => 3, logger => $my_debug_logsink,
              name => "$table scan"
            );

  # Typical CannedQuery execution, with trace messages built in
  foreach my $row_hash ( $qry->do_one_query(@bind_vals) ) {
    do_something($row_hash);
  }

  # Resultset too big to copy?  Fetch just a chunk, and use array
  # references rather than hash references
  foreach my $row ( $qry->do_one_query_ref($bind_ref, [ [], 2000 ]) ) {
    do_something($row);
  }

  # Package up several query executions, again with trace messages
  my %conditions = assemble_query_criteria();
  generate_result_table($qry->do_many_queries(\%conditions));
    

DESCRIPTION

This class provides a lightly sweetened flavor of Rose::DBx::CannedQuery, intended to simplify the job of running multiple instances of a particular query, while providing feedback to the user. It doesn't (much) alter the way the query interacts with the database, but is intended to abstract out some of the "chrome" often repeated in code that tried to keep the user informed as the queries execute.

ATTRIBUTES

Instances of Rose::DBx::CannedQuery::Glycosylated have all of the attributes supplied by Rose::DBx::CannedQuery and MooX::Role::Chatty. In addition, one new attribute is added:

name

A string identifying this particular query; it is used in log messages to help you figure out which query is executing.

If you do not provide a value, it defaults to the start of the SQL used to build the query.

METHODS

do_one_query([@bind_values])

Execute the query, passing the list of bind values specified in @bind_values, analogously to Rose::DBx::CannedQuery::results. Returns the list of resultant rows in array context, or the number of rows returned in scalar context.

If the "verbose" in MooX::Role::Chatty attribute is 3 or higher, an informational message is output (showing the bind values, if any) prior to execution, and a second message showing the result count is output after execution.

do_one_query_ref([$bind_values, $query_opts])

Execute the query, passing the bind values specified in $bind_values, which must be a reference to an array of bind values, as documented in "resultref" in Rose::DBx::CannedQuery. Returns the array reference containng the results of the query.

If query_opts is an array reference, it is passed unchanged to "resultref" in Rose::DBx::CannedQuery. If it is a simple (non-reference) scalar, the value is passed to "fetchall_arrayref" in DBI as the $max_rows parameter. If you want resultset rows as array references for efficiency, or want to actually retrieve a slice of the results for each row, you need to supply query_opts as an array reference that provides $slice, and optionally $max_rows.

If the verbose attribute is 3 or higher, an informational message is output (showing the bind values, if any) prior to execution, and a second message showing the result count is output after execution.

do_many_queries([$param_sets])

Execute the query several times via "do_one_query", using different bind values (and possibly query options) each time, and collect the results.

The $param_sets parameter is typically a hash reference, where the keys are strings naming each set of parameters. If you don't care to name your sets of bind values, you may also simply pass in a reference to an array of (array references containing) query parameters.

The value of each element in $param_sets is an array reference. If the array contains simple sclars, they are treated as a list of bind parameter values. If the first element is itself an array reference, then that element is used as $bind_vals and the next element as $query_opts (as taken by "do_one_query_ref").

If you pass in $param_sets as a hash reference, the return value is a hash reference, with the keys again being the names of the parameter sets, and the values being array references containing the results for that set of bind values. If you pass in an array reference, an array reference is returned, which contains array references holding the results for each parameter set; unsurprisingly, resultset elements are in the same order as the bind value sets you passed in.

Trace messages are output as described above for "do_one_query". In addition, if the verbose attribute is 2 or higher, an informational message is output for each bind set.

EXPORT

None.

SEE ALSO

Rose::DBx::CannedQuery and MooX::Role::Chatty for more information on specific behavior.

Rose::DBx::MoreConfig (or Rose::DB) for more information on managing the underlying DBI conncetions.

BUGS AND CAVEATS

Are there, for certain, but have yet to be cataloged.

VERSION

version 1.01

AUTHOR

Charles Bailey <cbail@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Charles Bailey

This software may be used under the terms of the Artistic License or the GNU General Public License, as the user prefers.