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.
5 POD Errors
The following errors were encountered while parsing the POD:
- Around line 197:
'=item' outside of any '=over'
- Around line 208:
You forgot a '=back' before '=head2'
- Around line 223:
'=item' outside of any '=over'
- Around line 257:
Non-ASCII character seen before =encoding in '“_id”'. Assuming UTF-8
- Around line 721:
You forgot a '=back' before '=head1'