NAME

DBIx::Thin - Lightweight ORMapper

SYNOPSIS

#-----------------------#
# Your/Model.pm
#-----------------------#
package Your::Model;

use DBIx::Thin;
DBIx::Thin->setup(
    dsn => 'DBI:SQLite:your_project.sqlite3',
    username => '',
    password => '',
);
DBIx::Thin->load_defined_schemas;

1;

#-----------------------#
# Your/Model/User.pm
# schema class for table 'user'
#-----------------------#
package Your::Model::User;
use DBIx::Thin::Schema;
use base qw(DBIx::Thin::Row);

install_table 'user' => schema {
    primary_key 'id';
    defaults string_is_utf8 => 1; # utf8 flag on
    columns 
        id    => { type => Integer },
        name  => { type => String },
        email => { type => String, utf8 => 0 }; # utf8 flag off
};

1;

#-----------------------#
# Your/Model/Status.pm
# schema class for table 'status'
#-----------------------#
package Your::Model::Status;
use DBIx::Thin::Schema;
use base qw(DBIx::Thin::Row);

install_table 'status' => schema {
    primary_key 'id',
    defaults string_is_utf8 => 1;
    columns 
        id    => { type => Integer },
        text  => { type => String },
        created_at => { type => Datetime },
};

1;

#-----------------------#
# in your script
#-----------------------#
use Your::Model;

### insert a record
my $row = Your::Model->create(
    'user',
    values => {
        name => 'oinume',
        email => 'oinume_at_gmail.com',
    }
);

### select records
my $iterator = Your::Model->search(
    'user',
    where => { name => 'oinume' },
    limit => 20,
);
while (my $row = $iterator->next) {
    ...
}

### update records
Your::Model->update(
    'user',
    values => { name => 'new_user' },
    where => { name => 'oinume' }
);

### delete records
Your::Model->delete_all(
    'user',
    where => { name => 'new_user' }
);

### delete a record with primary key
Your::Model->delete('user', 10);

SUPPORTED DATABASE

SQLite
MySQL
PostgreSQL

METHODS

setup(%)

Set up connection info.

ARGUMENTS

dsn: Datasource. SCALAR
username: connect username. SCALAR
password: connect password. SCALAR
connect_options: connect options. HASHREF

RETURNS : nothing

EXAMPLE

use DBIx::Thin;
DBIx::Thin->setup(
    dsn => 'DBI:SQLite:dbname=your_project.sqlite3',
    connect_options => {
        RaiseError => 1
    }
);

OR

use DBIx::Thin setup => {
    dsn => 'DBI:SQLite:dbname=your_project.sqlite3',
    connect_options => {
        RaiseError => 1
    }
};

load_defined_schemas(%)

Loads all defined schemas automatically. After calling load_defined_schemas, you don't need to use your schema class like 'use Your::Model::User'.

ARGUMENTS

schema_directory : directory of schema modules you created. If not given, try to find caller's package directory.

EXAMPLE

use DBIx::Thin;
DBIx::Thin->setup(...);
DBIx::Thin->load_defined_schemas();

OR

DBIx::Thin->load_defined_schemas('another/lib/Your/Model');

new(%args)

Creates an instance of DBIx::Thin. You shouldn't call DBIx::Thin's new method directly. Instead, you call Your::Model's one

ARGUMENTS

dsn: Datasource. SCALAR
username: connect username. SCALAR
password: connect password. SCALAR
connect_options: connect options. HASHREF

EXAMPLE

use Carp ();
use Your::Model;

my $model = Your::Model->new(
    dsn => 'DBI:mysql:yourdb:localhost',
    username => 'root',
    password => 'your password',
    connect_options => {
        RaiseError => 1,
        HandleError => sub { Carp::croak(shift) },
     },
);

execute_select($sql, $bind)

Executes a query for selection. This is low level API.

ARGUMENTS

sql : SQL
bind : bind parameters. ARRAYREF

RETURNS : sth object

execute_update($sql, $bind)

Executes a query for updating. (INSERT, UPDATE, DELETE or others) This is low level API.

ARGUMENTS

sql : SQL
bind : bind parameters. ARRAYREF

RETURNS : sth object

find_by_pk($table, $pk)

Returns a object of the table.

ARGUMENTS

table : Table name for searching.
pk : Primary key to find object.

RETURNS : A row object for the table. if no records, returns undef.

EXAMPLE

my $user = Your::Model->find('user', 1);
if ($user) {
    print 'name = ', $user->name, "\n";
} else {
    print 'record not found.\n';
}

find($table, %args)

Returns a object of the table.

ARGUMENTS

table : Table name for searching
args : HASH
  where : HASHREF
  order_by : ARRAYREF or HASHREF

RETURNS : A row object for the table. if no records, returns undef.

EXAMPLE

my $user = Your::Model->find(
    'user',
    where => {
        name => 'hoge'
    },
    order_by => {
        id => 'DESC'
    }
);
if ($user) {
    print "name = ", $user->name, "\n";
} else {
    print "record not found.\n";
}

find_by_sql(%args)

Returns a object of the table with a raw SQL.

ARGUMENTS

args : HASH
  sql : SQL
  bind : bind parameters. ARRAYREF
  options : options. HASHREF
    utf8 : extra utf8 columns ARRAYREF
    inflate : extra inflate columns HASHREF

RETURNS : A row object for the table. if no records, returns undef.

EXAMPLE

my $user = Your::Model->find_by_sql(
    sql => <<"EOS",
SELECT * FROM user
WHERE email LIKE ?
GROUP BY name
EOS
    bind => [ '%@gmail.com' ]
);

search($table, %args)

Returns an iterator or an array of selected records.

ARGUMENTS

table : Table name for searching
args : HASH
  select : select columns. ARRAYREF
  where : HASHREF
  order_by : ARRAYREF or HASHREF
  having : HAVING
  limit : max records number
  offset : offset

RETURNS : In scalar context, an iterator(DBIx::Thin::Iterator) of row objects for the table. if no records, returns an empty iterator. (NOT undef) In list context, an array of row objects.

EXAMPLE

my $iterator = Your::Model->search(
    'user',
    select => [ 'id' ], # or select => [ { id => 'id_alias' } ]
    where => {
        name => { op => 'LIKE', value => 'fuga%' }
    },
    order_by => [
        { id => 'DESC' }
    ],
    limit => 20,
);
while (my $user = $iterator->next) {
    print "id = ", $user->id, "\n";
}

# In list context
my @users = Your::Model->search(
    'user',
    where => {
        name => 'fuga',
    }
);

search_by_sql($table, %args)

Returns an iterator or an array of selected records with a raw SQL.

ARGUMENTS

args : HASH
  sql : SQL
  bind : bind parameters. ARRAYREF
  options : HASHREF
    table : Table for selection (used for determining a mapped object)
    utf8 : extra utf8 columns. ARRAYREF
    inflate : extra inflate columns. HASHREF

RETURNS : In scalar context, an iterator(DBIx::Thin::Iterator) of row objects for the SQL. if no records, returns an empty iterator. (NOT undef) In list context, an array of row objects.

EXAMPLE

my $iterator = Your::Model->search_by_sql(
    sql => <<"EOS",
SELECT * FROM user
WHERE name LIKE ?
ORDER BY id DESC
EOS
    bind => [ '%hoge%' ]
    options => { table => 'user' },
);
while (my $user = $iterator->next) {
    print "id = ", $user->id, "\n";
}

# In list context
my @users = Your::Model->search_by_sql(
    sql => <<"EOS",
SELECT * FROM user
WHERE name LIKE ?
ORDER BY id DESC
EOS
    bind => [ '%hoge%' ]
    options => {
        table => 'user',
        utf8 => [ qw(name) ],
        inflate => {
            updated_at => sub {
                my ($column, $value) = @_;
                # inflate to DateTime object
                return DateTime::Format::MySQL->parse_datetime($value);
            }
        },
    },
);

create($table, %args)

Creates a new record.

ARGUMENTS

table : Table name
args : HASH
  values : Column values for a new record. HASHREF

RETURNS : A row object

EXAMPLE

my $new_user = Your::Model->create(
    'user',
    values => {
        name => 'testname',
        email => 'testname@hoge.com',
    }
);

create_by_sql(%args)

Executes a query for insertion. This is low level API.

ARGUMENTS

args: HASH
  sql : SQL
  bind : bind parameters. ARRAYREF
  options : HASHREF
    fetch_created_row : Boolean. Fetch a newly created row

RETURNS : A row object

create_all($table, %args)

Creates new records.

ARGUMENTS

table : Table name
args : HASH
  values : Column values for a new record. HASHREF

RETURNS : Created record number.

EXAMPLE

my $created_count = Your::Model->create_all(
    'user',
    values => [
        { name => 'test1', email => 'test1@hoge.com' },
        { name => 'test2', email => 'test2@hoge.com' },
    ],
);

update($table, %args)

Updates records.

ARGUMENTS

table : Table name
args : HASH
  values : Updating values.
  where : HASHREF

RETURNS : Updated row count

EXAMPLE

my $updated_count = Your::Mode->update(
    'user',
    values => {
        name => 'New name',
    },
    where => {
        id => 1,
    },
);

update_by_sql(%args)

Executes a query for updating. This is low level API.

ARGUMENTS

args: HASH
  sql : SQL
  bind : bind parameters. ARRAYREF
  options : HASHREF

RETURNS : Updated row count

delete($table, $primary_key_value)

Delete a new record.

ARGUMENTS

table : Table name
primary_key_value : Primary key value for a deleted record.

RETURNS : Deleted row count

EXAMPLE

my $deleted = Your::Model->delete('user', 1);

delete_all($table, %args)

Delete records.

ARGUMENTS

table : Table name
args : HASH
  where : HASHREF. REQUIRED.

RETURNS : Deleted row count

EXAMPLE

my $deleted_count = Your::Model->delete_all(
    'user',
    where => {
        name => 'oinume'
    }
);

delete_by_sql(%args)

Executes a query for deleting. This is low level API.

ARGUMENTS

args: HASH
  sql : SQL
  bind : bind parameters. ARRAYREF
  options : HASHREF

RETURNS : Deleted row count

AUTHOR

Kazuhiro Oinuma <oinume __at__ gmail.com>

THANKS

DBIx::Thin is based on DBIx::Skinny's code. thanks for nekokak.

REPOSITORY

git clone git://github.com/oinume/p5-dbix-thin.git

LICENCE AND COPYRIGHT

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

To install DBIx::Thin, copy and paste the appropriate command in to your terminal.

cpanm

cpanm DBIx::Thin

CPAN shell

perl -MCPAN -e shell
install DBIx::Thin

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

SUPPORTED DATABASE

METHODS

setup(%)

load_defined_schemas(%)

new(%args)

execute_select($sql, $bind)

execute_update($sql, $bind)

find_by_pk($table, $pk)

find($table, %args)

find_by_sql(%args)

search($table, %args)

search_by_sql($table, %args)

create($table, %args)

create_by_sql(%args)

create_all($table, %args)

update($table, %args)

update_by_sql(%args)

delete($table, $primary_key_value)

delete_all($table, %args)

delete_by_sql(%args)

AUTHOR

THANKS

REPOSITORY

LICENCE AND COPYRIGHT

Module Install Instructions