DBIx::Thin - Lightweight ORMapper

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

METHODS

setup(%)

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'.

new(%args)

Creates an instance of DBIx::Thin.

ARGUMENTS

  dsn: Datasource
  username: connect username
  password: connect password
  connect_options: connect options

EXAMPLE

  use Carp ();
  use Your::Model;
  
  my $model = Your::Model->new({
      dsn => 'DBI:mysql:yourdb:localhost',
      username => 'root',
      password => 'your password',
      connect_options => {
          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(the DBIx::Thin::Iterator manpage) 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',
      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(the DBIx::Thin::Iterator manpage) 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 the DBIx::Skinny manpage's code. thanks for nekokak.

REPOSITORY

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

LICENCE AND COPYRIGHT

Copyright (c) 2009, Kazuhiro Oinuma <oinume __at__ gmail.com>. All rights reserved.

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

 DBIx::Thin - Lightweight ORMapper