The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Catalyst-Model-CDBI-Sweet-0.02
River stage zero No dependents
++
/ Catalyst::Model::CDBI::Sweet

NAME

    Catalyst::Model::CDBI::Sweet - Making sweet things sweeter

SYNOPSIS

    package MyApp::Model::Article;
    use base qw[Catalyst::Model::CDBI::Sweet Catalyst::Base];

    use DateTime;

    __PACKAGE__->table('article');
    __PACKAGE__->columns( Primary   => qw[ id ] );
    __PACKAGE__->columns( Essential => qw[ title created_on created_by ] );

    __PACKAGE__->has_a(
        created_on => 'DateTime',
        inflate    => sub { DateTime->from_epoch( epoch => shift ) },
        deflate    => sub { shift->epoch }
    );

    MyApp::Model::Article->connection('DBI:driver:database');

    package MyApp::Controller::Article;

    # Simple search

    MyApp::Model::Article->search( created_by => 'sri', { order_by => 'title' } );

    MyApp::Model::Article->count( created_by => 'sri' );

    MyApp::Model::Article->page( created_by => 'sri', { page => 5 } );

    MyApp::Model::Article->retrieve_all( order_by => 'created_on' );


    # More powerful search with deflating

    $criteria = {
        created_on => {
            -between => [
                DateTime->new( year => 2004 ),
                DateTime->new( year => 2005 ),
            ]
        },
        created_by => [ qw(chansen draven gabb jester sri) ],
        title      => {
            -like  => [ qw( perl% catalyst% ) ]
        }
    };

    MyApp::Model::Article->search( $criteria, { rows => 30 } );

    MyApp::Model::Article->count($criteria);

    MyApp::Model::Article->page( $criteria, { rows => 10, page => 2 } );

DESCRIPTION

Catalyst::Model::CDBI::Sweet provides convenient count, search, page, and cache functions in a sweet package. It integrates these functions with Class::DBI in a convenient and efficient way.

RETRIEVING OBJECTS

All retrieving methods can take the same criteria and attributes. Criteria is the only required parameter.

criteria

Can be a hash, hashref, or an arrayref. Takes the same options as the SQL::Abstract where method. If values contain any objects, they will be deflated before querying the database.

attributes

case, cmp, convert, and logic

These attributes are passed to SQL::Abstact's constuctor and alter the behavior of the criteria.

    { cmp => 'like' }
order_by

Specifies the sort order of the results.

    { order_by => 'created_on DESC' }
rows

Specifies the maximum number of rows to return. Currently supported RDBMs are Interbase, MaxDB, MySQL, PostgreSQL and SQLite. For other RDBMs, it will be emulated.

    { rows => 10 }
offset

Specifies the offset of the first row to return. Defaults to 0 if unspecified.

    { offest => 0 }
page

Specifies the current page in page. Defaults to 1 if unspecified.

    { page => 1 }

count

Returns a count of the number of rows matching the criteria. count will discard offset, order_by, and rows.

    $count = MyApp::Model::Article->count(%criteria);

Returns an iterator in scalar context, or an array of objects in list context.

    @objects  = MyApp::Model::Article->search(%criteria);

    $iterator = MyApp::Model::Article->search(%criteria);

page

Retuns a page object and an iterator. The page object is an instance of Data::Page.

    ( $page, $iterator ) = MyApp::Model::Article->page( $criteria, { rows => 10, page => 2 );

    printf( "Results %d - %d of %d Found\n",
        $page->first, $page->last, $page->total_entries );

retrieve_all

Same as Class::DBI with addition that it takes attributes as arguments, attributes can be a hash or a hashref.

    $iterator = MyApp::Model::Article->retrieve_all( order_by => 'created_on' );

CACHING OBJECTS

Objects will be stored deflated in cache. Only Primary and Essential columns will be cached.

cache

Class method: if this is set caching is enabled. Any cache object that has a get, set, and remove method is supported.

    __PACKAGE__->cache(
        Cache::FastMmap->new(
            share_file => '/tmp/cdbi',
            expire_time => 3600
        )
    );

cache_key

Returns a cache key for an object consisting of class and primary keys.

Overloaded methods

_init

Overrides Class::DBI's internal cache. On a cache hit, it will return a cached object; on a cache miss it will create an new object and store it in the cache.

retrieve

On a cache hit the object will be inflated by the select trigger and then served.

update

Object is removed from the cache and will be cached on next retrieval.

delete

Object is removed from the cache.

UNIVERSALLY UNIQUE IDENTIFIERS

If enabled a UUID string will be generated for primary column. A CHAR(36) column is suitable for storage.

    __PACKAGE__->sequence('uuid');

AUTHOR

Christian Hansen <ch@ngmedia.com>

THANKS TO

Danijel Milicevic, Jesse Sheidlower, Marcus Ramberg, Sebastian Riedel, Viljo Marrandi

SUPPORT

#catalyst on irc://irc.perl.org

http://lists.rawmode.org/mailman/listinfo/catalyst

http://lists.rawmode.org/mailman/listinfo/catalyst-dev

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Catalyst

Class::DBI

Data::Page

Data::UUID

SQL::Abstract

http://cpan.robm.fastmail.fm/cache_perf.html An comparison of different cahing modules for perl.