/ 
DBIx-ResultSet-0.10
River stage zero No dependents
/ DBIx::ResultSet

NAME

DBIx::ResultSet - Lightweight SQL query building and execution.

SYNOPSIS

my $connector = DBIx::ResultSet::Connector->new( $dsn, $user, $pass );

my $users = $connector->resultset('users');
my $adult_users = $users->search({ age => {'>=', 18} });

print 'Users: ' . $users->count() . "\n";
print 'Adult users: ' . $adult_users->count() . "\n";

DESCRIPTION

This module provides an API that simpliefies the creation and execution of SQL queries. This is done by providing a thin wrapper around the SQL::Abstract, DBIx::Connector, DBI, Data::Page, and DateTime::Format::* modules.

I was inspired to write this module because I work in an environment where we really didn't want the heavy footprint of DBIx::Class, but instead wanted many of the features of DBIx::Class::ResultSet in a lightweight package.

Unlike DBIx::Class, this module DOES expect you to be retrieving thousands and millions of rows. It is designed for high-volume and optimized software, where the developers believe that writing effecient code and elegant code is not mutually exclusive.

METHODS

my $old_rs = $connector->resultset('users')->search({ status => 0 });
my $new_rs = $old_rs->search({ age > 18 });
print 'Disabled adults: ' . $new_rs->count() . "\n";

Returns a new result set object that overlays the passed in where clause on top of the old where clause, creating a new result set. The original result set's where clause is left unmodified.

METHODS

insert

$rs->insert(
    { user_name=>'bob2003', email=>'bob@example.com' }, # fields to insert
);

update

$rs->update(
    { phone => '555-1234' }, # fields to update
);

delete

$rs->delete();

array_row

my $user = $rs->array_row(
    ['user_id', 'created', 'email', 'phone'], # fields to retrieve
);

hash_row

my $user = $rs->hash_row(
    ['user_id', 'created'],     # fields to retrieve
);

array_of_array_rows

my $disabled_users = $rs->array_of_array_rows(
    ['user_id', 'email', 'phone'], # fields to retrieve
);
print $disabled_users->[2]->[1];

Returns an array ref of array refs, one for each row returned.

array_of_hash_rows

my $disabled_users = $rs->array_of_hash_rows(
    ['user_id', 'email', 'phone'], # fields to retrieve
);
print $disabled_users->[2]->{email};

hash_of_hash_rows

my $disabled_users = $rs->hash_of_hash_rows(
    'user_name',                   # column to index the hash by
    ['user_id', 'email', 'phone'], # fields to retrieve
);
print $disabled_users->{jsmith}->{email};

count

my $enabled_users_count = $rs->count();

column

my $user_ids = $rs->column(
    'user_id',                          # column to retrieve
);

select_sth

my ($sth, @bind) = $rs->select_sth(
    ['user_name', 'user_id'], # fields to retrieve
);
$sth->execute( @bind );
$sth->bind_columns( \my( $user_name, $user_id ) );
while ($sth->fetch()) { ... }

If you want a little more power, or want you DB access a little more effecient for your particular situation, then you might want to get at the select sth.

insert_sth

my $insert_sth;
foreach my $user_name (qw( jsmith bthompson gfillman )) {
    my $fields = {
        user_name => $user_name,
        email     => $user_name . '@mycompany.com',
    };

    $insert_sth ||= $rs->insert_sth(
        $fields, # fields to insert
    );

    $insert_sth->execute(
        $rs->bind_values( $fields ),
    );
}

If you're going to insert a *lot* of records you probably don't want to be re-generating the SQL every time you call insert().

bind_values

This mehtod is a non-modifying wrapper around SQL::Abstract's values() method to be used in conjunction with insert_sth().

ATTRIBUTES

connector

pager

my $rs = $connector->resultset('users')->search({}, {page=>2, rows=>50});
my $pager = $rs->pager(); # a pre-populated Data::Page object

A Data::Page object pre-populated based on page() and rows(). If page() has not been specified then trying to access page() will throw a fatal error.

The total_entries and last_page methods are proxied from the pager in to this class so that you can call:

print $rs->total_entries();

Instead of:

print $rs->pager->total_entries();

table

The name of the table that this result set will be using for queries.

where

The where clause hash ref to be used when executing queries.

clauses

Additional clauses, such as order_by, limit, offset, etc.