/ 
DBIx-Custom-0.1604
River stage one • 6 direct dependents • 6 total dependents
/ DBIx::Custom

NAME

DBIx::Custom - DBI with hash parameter binding and filtering system

STABILITY

This module is not stable. Method name and implementations will be changed.

SYNOPSYS

# Connect
my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=books",
                                user => 'ken', password => '!LFKD%$&');
# Insert 
$dbi->insert(table  => 'books',
             param  => {title => 'perl', author => 'Ken'},
             filter => {title => 'encode_utf8'});

# Update 
$dbi->update(table  => 'books', 
             param  => {title => 'aaa', author => 'Ken'}, 
             where  => {id => 5},
             filter => {title => 'encode_utf8'});

# Update all
$dbi->update_all(table  => 'books',
                 param  => {title => 'aaa'},
                 filter => {title => 'encode_utf8'});

# Delete
$dbi->delete(table  => 'books',
             where  => {author => 'Ken'},
             filter => {title => 'encode_utf8'});

# Delete all
$dbi->delete_all(table => 'books');

# Select
my $result = $dbi->select(table => 'books');

# Select(more complex)
my $result = $dbi->select(
    table  => 'books',
    column => [qw/author title/],
    where  => {author => 'Ken'},
    append => 'order by id limit 1',
    filter => {tilte => 'encode_utf8'}
);

# Select(Join table)
my $result = $dbi->select(
    table => ['books', 'rental'],
    column => ['books.name as book_name']
    relation => {'books.id' => 'rental.book_id'}
);

# Execute SQL
$dbi->execute("select title from books");

# Execute SQL with parameters and filter
$dbi->execute("select id from books where {= author} && {like title}",
              param  => {author => 'ken', title => '%Perl%'},
              filter => {tilte => 'encode_utf8'});

# Create query and execute it
my $query = $dbi->build_query(
    "select id from books where {= author} && {like title}"
);
$dbi->execute($query, param => {author => 'ken', title => '%Perl%'})

# Default filter
$dbi->default_bind_filter('encode_utf8');
$dbi->default_fetch_filter('decode_utf8');

# Fetch
while (my $row = $result->fetch) {
    # ...
}

# Fetch hash
while (my $row = $result->fetch_hash) {
    
}

# Get DBI object
my $dbh = $dbi->dbh;

DESCRIPTION

DBIx::Custom is useful DBI extention. This module have hash parameter binding and filtering system.

Normally, binding parameter is array. DBIx::Custom enable you to pass binding parameter as hash.

This module also provide filtering system. You can filter the binding parameter or the value of fetching row.

And have useful method such as insert(), update(), delete(), and select().

Features

  • Hash parameter binding.

  • Value filtering.

  • Provide suger methods, such as insert(), update(), delete(), and select().

ATTRIBUTES

user

my $user = $dbi->user;
$dbi     = $dbi->user('Ken');

Database user name. This is used for connect().

password

my $password = $dbi->password;
$dbi         = $dbi->password('lkj&le`@s');

Database password. This is used for connect().

data_source

my $data_source = $dbi->data_source;
$dbi            = $dbi->data_source("dbi:mysql:dbname=$database");

Database data source. This is used for connect().

dbh

my $dbh = $dbi->dbh;
$dbi    = $dbi->dbh($dbh);

Database handle. This is a DBI object. You can call all methods of DBI

my $sth    = $dbi->dbh->prepare("...");
my $errstr = $dbi->dbh->errstr;
$dbi->dbh->begin_work;
$dbi->dbh->commit;
$dbi->dbh->rollback;

filters

my $filters = $dbi->filters;
$dbi        = $dbi->filters(\%filters);

Filter functions. By default, "encode_utf8" and "decode_utf8" is registered.

$encode_utf8 = $dbi->filters->{encode_utf8};
$decode_utf8 = $dbi->filters->{decode_utf8};

default_bind_filter

my $default_bind_filter = $dbi->default_bind_filter
$dbi                    = $dbi->default_bind_filter('encode_utf8');

Default filter for value binding

default_fetch_filter

my $default_fetch_filter = $dbi->default_fetch_filter;
$dbi                     = $dbi->default_fetch_filter('decode_utf8');

Default filter for fetching.

result_class

my $result_class = $dbi->result_class;
$dbi             = $dbi->result_class('DBIx::Custom::Result');

Result class for select statement. Default to DBIx::Custom::Result.

sql_builder

my $sql_class = $dbi->sql_builder;
$dbi          = $dbi->sql_builder(DBIx::Custom::QueryBuilder->new);

SQL builder. sql_builder must be the instance of DBIx::Custom::QueryBuilder subclass Default to DBIx::Custom::QueryBuilder.

METHODS

This class is Object::Simple subclass. You can use all methods of Object::Simple

connect

my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=books",
                                user => 'ken', password => '!LFKD%$&');

Connect to database. "AutoCommit" and "RaiseError" option is true, and "PrintError" option is false by default.

insert

$affected = $dbi->insert(table  => $table, 
                         param  => \%param,
                         append => $append,
                         filter => \%filter);

Insert row. Retrun value is the count of affected rows.

Example:

$dbi->insert(table  => 'books', 
             param  => {title => 'Perl', author => 'Taro'},
             append => "some statement",
             filter => {title => 'encode_utf8'})

update

$affected = $dbi->update(table  => $table, 
                         param  => \%params,
                         where  => \%where,
                         append => $append,
                         filter => \%filter)

Update rows. Retrun value is the count of affected rows.

Example:

$dbi->update(table  => 'books',
             param  => {title => 'Perl', author => 'Taro'},
             where  => {id => 5},
             append => "some statement",
             filter => {title => 'encode_utf8'});

update_all

$affected = $dbi->update_all(table  => $table, 
                             param  => \%params,
                             filter => \%filter,
                             append => $append);

Update all rows. Retrun value is the count of affected rows.

Example:

$dbi->update_all(table  => 'books', 
                 param  => {author => 'taro'},
                 filter => {author => 'encode_utf8'});

delete

$affected = $dbi->delete(table  => $table,
                         where  => \%where,
                         append => $append,
                         filter => \%filter);

Delete rows. Retrun value is the count of affected rows.

Example:

$dbi->delete(table  => 'books',
             where  => {id => 5},
             append => 'some statement',
             filter => {id => 'encode_utf8'});

delete_all

$affected = $dbi->delete_all(table => $table);

Delete all rows. Retrun value is the count of affected rows.

Example:

$dbi->delete_all(table => 'books');

select

$result = $dbi->select(table    => $table,
                       column   => [@column],
                       where    => \%where,
                       append   => $append,
                       relation => \%relation,
                       filter   => \%filter);

Select rows. Return value is the instance of DBIx::Custom::Result.

Example:

# select * from books;
$result = $dbi->select(table => 'books');

# select * from books where title = 'Perl';
$result = $dbi->select(table => 'books', where => {title => 1});

# select title, author from books where id = 1 for update;
$result = $dbi->select(
    table  => 'books',
    column => ['title', 'author'],
    where  => {id => 1},
    appned => 'for update'
);

# select books.name as book_name from books, rental 
# where books.id = rental.book_id;
my $result = $dbi->select(
    table    => ['books', 'rental'],
    column   => ['books.name as book_name']
    relation => {'books.id' => 'rental.book_id'}
);

build_query

my $query = $dbi->build_query(
    "select * from authors where {= name} and {= age};"
);

Build the instance of DBIx::Custom::Query using DBIx::Custom::QueryBuilder.

execute

$result = $dbi->execute($query,  param => $params, filter => \%filter);
$result = $dbi->execute($source, param => $params, filter => \%filter);

Execute the instace of DBIx::Custom::Query or the string written by SQL template. Return value is the instance of DBIx::Custom::Result.

Example:

$result = $dbi->execute("select * from authors where {= name} and {= age}", 
                        param => {name => 'taro', age => 19});

while (my $row = $result->fetch) {
    # do something
}

register_filter

$dbi->register_filter(%filters);
$dbi->register_filter(\%filters);

Resister filter.

Example:

$dbi->register_filter(
    encode_utf8 => sub {
        my $value = shift;
        
        require Encode;
        
        return Encode::encode('UTF-8', $value);
    },
    decode_utf8 => sub {
        my $value = shift;
        
        require Encode;
        
        return Encode::decode('UTF-8', $value)
    }
);

cache

$dbi   = $dbi->cache(1);
$cache = $dbi->cache;

Cache the result of parsing SQL template. Default to 1.

cache_method

$dbi          = $dbi->cache_method(\&cache_method);
$cache_method = $dbi->cache_method

Method for cache.

Example:

$dbi->cache_method(
    sub {
        my $self = shift;
        
        $self->{_cached} ||= {};
        
        if (@_ > 1) {
            $self->{_cached}{$_[0]} = $_[1] 
        }
        else {
            return $self->{_cached}{$_[0]}
        }
    }
);

BUGS

Please tell me bugs.

<kimoto.yuki at gmail.com>

http://github.com/yuki-kimoto/DBIx-Custom

AUTHOR

Yuki Kimoto, <kimoto.yuki at gmail.com>

COPYRIGHT & LICENSE

Copyright 2009 Yuki Kimoto, all rights reserved.

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