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