/ 
DBIx-Custom-0.1606
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 to database.

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

Insert, update, delete statement.

# 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 statement.

# 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 source.

# Execute from SQL source
$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%'})

More features.

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

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

Fetch row.

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

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

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');

User name. connect() method use this value to connect the database.

password

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

Password. connect() method use this value to connect the database.

data_source

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

Data source. connect() method use this value to connect the database.

dbh

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

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.

default_bind_filter

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

Default filter when parameter binding is executed.

default_fetch_filter

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

Default filter when row is fetched.

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.

cache

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

Enable cache of the query after parsing SQL source. 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]}
        }
    }
);

METHODS

DBIx::Custom inherits all methods from Object::Simple and implements the following new ones.

connect

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

Create a new DBIx::Custom object and connect to the database. By default, "AutoCommit" and "RaiseError" option is true, and "PrintError" option is false.

insert

$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

$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

$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

$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

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

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

Example:

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

select

my $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;
my $result = $dbi->select(table => 'books');

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

# select title, author from books where id = 1 for update;
my $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

my $result = $dbi->execute($query,  param => $params, filter => \%filter);
my $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:

my $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)
    }
);

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.