NAME

DBIx::ActiveRecord - rails3 ActiveRecord like O/R Mapper

SYNOPSIS

define Model

package MyApp::Model::User;
use base 'DBIx::ActiveRecord::Model';
__PACKAGE__->table('users'); # table name is required
__PACKAGE__->columns(qw/id name created_at updated_at/); # required
__PACKAGE__->primary_keys(qw/id/); # required

# scope
__PACKAGE__->default_scope(sub{ shift->ne(deleted => 1) });
__PACKAGE__->scope(adult => sub{ shift->ge(age => 20) });
__PACKAGE__->scope(latest => sub{ shift->desc('created_at') });

# association
__PACKAGE__->belongs_to(group => 'MyApp::Model::Group');
__PACKAGE__->has_many(posts => 'MyApp::Model::Post');

1;

initialize

use DBIx::ActiveRecord;
# same args for 'DBI::connect'
DBIx::ActiveRecord->connect($data_source, $username, $auth, \%attr);

basic CRUD

# create
my $user = MyApp::Model::User->new({name => 'new user'});
$user->save;
# or
my $user = MyApp::Model::User->create({name => 'new user'});

# update
$user->name('change user name');
$user->save;

# delete
$user->delete;

# search
my $users = MyApp::Model::User->in(id => [1..10])->eq(type => 2);

# delete_all
User->eq(deleted => 1)->delete_all;

# update_all
User->eq(type => 3)->update_all({deleted => 1});

use scope and association

my $user = MyApp::Model::User->adult->latest->first;
my $group = $user->group;
my $published_posts = $user->posts->eq(published => 1);
my $drafts = $user->posts->eq(published => 0);

DESCRIPTION

DBIx::ActiveRecord is rails3 ActiveRecord like O/R Mapper. It is lightweight, very easy use and powerful syntax.

METHODS

DBIx::ActiveRecord Methods

connect($data_source, $username, $auth, \%attr);

Connect database and initialization. arguments is same 'DBI::connect'.

example:

use DBIx::ActiveRecord;
DBIx::ActiveRecord->connect("dbi:mysql:databasename", 'root', '');

DBIx::ActiveRecord::Model Methods

This class is core class for DBIx::ActiveRecord module. Model class is extends this class.

exsample:

package My::Model::Hoge;
use base 'DBIx::ActiveRecord::Model';
__PACKAGE__->table('users');
__PACKAGE__->columns(qw/id name created_at/);
__PACKAGE__->primary_keys(qw/id/);
1;

Model->table($table_name)

setting table name for model class. this method is required for defined model.

Model->columns(@column_names)

setting table column name for model class. this method is required for defined model.

Model->primary_keys(@key_column_names)

setting table primary keys for model class. this method is required for defined model.

Model->belongs_to($name, $package, \%opt)

setting up belongs_to association.

exsample:

__PACKAGE__->belongs_to(group => 'My::Model::Group');

\%opt enable keys is

primary_key

Specify the method that returns the primary key of associated object used for the association. By default this is id.

foerign_key

Specify the foreign key used for the association. By default this is the lowermost with model packge name with an “_id” suffix.

example:

__PACKAGE__->belongs_to(group => 'My::Model::Group', {primary_key => 'id', foerign_key => 'group_id'});

Model->has_one($name, $package, \%opt)

setting up has_one association.

exsample:

__PACKAGE__->has_one(tag => 'My::Model::Tag');

\%opt enable keys is

primary_key

Specify the method that returns the primary key of associated object used for the association. By default this is id.

foerign_key

Specify the foreign key used for the association. By default this is the lowermost with model packge name with an “_id” suffix.

example:

__PACKAGE__->has_one(tag => 'My::Model::Tag', {primary_key => 'id', foerign_key => 'tag_id'});

Model->has_many($name, $package, \%opt)

setting up has_many association.

exsample:

__PACKAGE__->has_many(posts => 'My::Model::Post');

\%opt enable keys is

primary_key

Specify the method that returns the primary key of associated object used for the association. By default this is id.

foerign_key

Specify the foreign key used for the association. By default this is the lowermost with model packge name with an “_id” suffix.

example:

__PACKAGE__->has_one(posts => 'My::Model::Post', {primary_key => 'id', foerign_key => 'post_id'});

Model->default_scope($coderef)

example:

__PACKAGE__->default_scope(sub{ shift->desc('created_at')->ne(deleted => 1) });

Model->scope($name, $coderef)

example:

__PACKAGE__->scope(type1 => sub{ shift->eq(type => 1 });

or has args.

__PACKAGE__->scope(type_of => sub{ shift->eq(type => shift) });

# use example for
# Model->type_of(1)->all;

Model->transaction($coderef)

do transactional block

example:

Model->transaction(sub {
    # transactional code
});

Model->new($hash)

build model instance.

example:

my $m = Model->new({name => 'hoge', type => 1});

Model->create(\%hash)

build and save.

example:

my $m = Model->create({name => 'hoge', type => 1});

this is same

my $m = Model->new({name => 'hoge', type => 1});
$m->save;

Model->all()

execute select query.

example:

my $list = Model->all;

or

my $list = Model->eq(type => 2)->all;

Model->first()

execute select query append LIMIT 1 return value is model instance or undef

example:

my $m = Model->first;

or

my $m = Model->eq(type => 2)->first;

Model->last()

execute select query append LIMIT 1 and reverse order. return value is model instance or undef this method is do not work if not call asc or desc method.

example:

my $m = Model->asc("id")->last;

or

my $m = Model->asc("id")->eq(type => 2)->last;

Model->scoped()

get relation instance. will not use normally.

example:

my $m = Model->scoped->eq(id => 1)->first;

this is same

my $m = Model->eq(id => 1)->first;

Model->unscoped()

get relation instance of not apply default_scope.

example:

my $all = Model->unscoped->all;

Model->to_sql()

get sql statement.

example:

my $sql = Model->eq(type => 2)->eq(deleted => 1)->to_sql;
# $sql => 'SELECT * FROM models WHERE type = ? AND deleted = ?'

Model->update_all($hash)

do update

example:

Model->eq(type => 2)->update_all({type => 3});
# UPDATE models SET type = 3 WHERE type = 2

Model->delete_all()

do delete

example:

Model->eq(type => 2)->delete_all;
# DELETE FROM models WHERE type = 2

Model->joins(@$relations)

join other table

example:

User->joins('group')->all;

# nested
User->joins('posts', 'comments')->all;

# combine
User->joins('group')->joins('posts', 'comments')->all;

Model->merge($relation)

merge other model relation instance

example:

User->joins('group')->merge(Group->eq(type => 2))->all;

Model->includes(@$relations)

Early binding associations.

example:

User->includes('group')->all;

# nested
User->includes('posts', 'comments')->all;

# combine
User->includes('group')->includes('posts', 'comments')->all;

Model->eq($column, $value)

add '=' condition

Model->ne($column, $value)

add '!=' condition

Model->in($column, \@value)

add 'IN' condition

Model->not_in($column, \@value)

add 'NOT IN' condition

Model->null($column)

add 'IS NULL' condition

Model->not_null($column)

add 'IS NOT NULL' condition

Model->gt($column, $value)

add '>' condition

Model->lt($column, $value)

add '<' condition

Model->ge($column, $value)

add '>=' condition

Model->le($column, $value)

add '<=' condition

Model->like($column, $value)

add 'LIKE' condition

Model->contains($column, $value)

add 'LIKE' condition value will be added to the conditions as "%$value%".

Model->starts_with($column, $value)

add 'LIKE' condition value will be added to the conditions as "$value%".

Model->ends_with($column, $value)

add 'LIKE' condition value will be added to the conditions as "%$value".

Model->between($column, $value1, $value2)

this is same

Model->ge($column, $value1)->lt($column, $value2)

Model->where($condition, @bind_values)

add condition

example:

Model->where('type = ? OR id < ?', 2, 1000)->all
# SELECT * from models WHERE type = 2 OR id < 1000

Model->select(@columns)

set select columns

example:

Model->select('id', 'name')->all;
# SELECT id, name from models;

Model->limit($value)

set limit

Model->offset($value)

set offset

Model->lock()

search query added 'FOR UPDATE'

example:

Model->transaction(sub {
    my $w = Wallet->eq(user_id => 1)->lock->first;
    $w->deposite($w-deposite - 100);
    $w->save;
});

Model->group(@columns)

set group by

example:

Model->select('type')->group('type')->all;

Model->asc(@columns)

add 'ASC' order by

Model->asc('id', 'name')->all;

Model->desc(@columns)

add 'DESC' order by

Model->desc('id', 'name')->all;

Model->reorder()

reset order by

example:

my $s = Model->asc('id');
$s = $s->reorder->desc('id');
$s->all;

Model->reverse()

reverse order by

example:

my $s = Model->asc('id');
$s->reverse->all;

# this is same
Model->desc('id')->all

$model->get_column($column)

get a column value.

example:

my $v = $model->get_column('name');

defined helper method for 'columns' method arguments.

example:

__PACKAGE__->columns(qw/id name/);
...

my $id = $model->name;
# this is same
my $id = $model->get_column('name');

$model->set_column($column, $value)

set a column value.

example:

$model->set_column('name', 'fuga');

defined helper method for 'columns' method arguments.

example:

__PACKAGE__->columns(qw/id name/);
...

$model->name('fuga');
# this is same
my $id = $model->set_column('name', 'fuga');

$model->to_hash()

translate hash value.

example:

my $m = Model->new({name => 'hoge'});
$m->type(2);

my $h = $m->to_hash;
# $h is {name => 'hoge', type => 2}

$model->in_storage()

saved instance is return 1. not saved instance is return 0.

$model->save()

do insert or update.

$model->insert()

do insert.

$model->update()

do update.

$model->delete()

do delete.

BUGS AND LIMITATIONS

This module is alpha version. Please give me feedback. Please PullRequest with github If you have more better idea.

AUTHOR

Toshiyuki Saito

REPOSITORY

git clone git://github.com/toshi-saito/perl-dbix-activerecord.git

LICENCE AND COPYRIGHT

Copyright (C) 2012 by Toshiyuki Saito All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

cpanm DBIx::ActiveRecord

perl -MCPAN -e shell
install DBIx::ActiveRecord