/ 
Dancer-Plugin-ORMesque-0.0100
/ Dancer::Plugin::ORMesque

NAME

Dancer::Plugin::ORMesque - Simple Object Relational Mapping for Dancer

VERSION

version 0.0100

SYNOPSIS

Dancer::Plugin::ORMesque is NOT a full-featured object relational mapper but is an ORM none the less whereby it creates and provides a database connection to the database of your choice and automatically creates objects and accessors for use in your application code without the need of having to write SQL. Dancer::Plugin::ORMesque uses SQL::Abstract querying syntax. This module uses DBIx::Simple as a base class but only the query and iquery methods are made available.

Connection details will be taken from your Dancer application config file, and should be specified as, for example:

plugins:
  Database:
    driver: 'mysql'
    database: 'test'
    host: 'localhost'
    username: 'myusername'
    password: 'mypassword'
    connectivity-check-threshold: 10
    dbi_params:
        RaiseError: 1
        AutoCommit: 1
    on_connect_do: ["SET NAMES 'utf8'", "SET CHARACTER SET 'utf8'" ]

The connection functionality is imported from Dancer::Plugin::Database, please look into that plugin for more information. Please note that even if you use supply a DSN directly in your configuration file you need to also specify a driver directive.

# Use the dbi (database interface) keyword to establish a new connection to
# the database then access users (the users table) and store the reference in
# local variable $users

my $user = dbi->users;

# Grab the first record, not neccessary if operating on only one record

$user->read;

# SQL::Abstract where clause passed to the "read" method

$user->read({
    'column' => 'query'
});

$user->first;
$user->last;

# How many records in collection

$user->count

for (0..$user->count) {
    print $user->column;
    $user->column('new stuff');
    $user->update($user->current, $user->id);
    $user->next;
}

# The database objects main accessors are CRUD (create, read, update, and delete)

$user->create;
  $user->read;
    $user->update;
      $user->delete;

# Also, need direct access to the resultset?

$user->collection; # returns an array of hashrefs
$user->current;    # return a hashref of the current row in the collection

METHODS

dbi

The dbi method/keyword instantiates a new Dancer::Plugin::ORMesque instance
which uses the datasource configuration details in your configuration file
to create database objects and accessors.

my $db = dbi;

EXPERIMENTAL

This plugin is highly **experimental** and subject to radical design changes based on random flights-of-fancy. Currently the only databased supported are MySQL and SQLite but more support will be added once I have a stable model to with with. Please give feedback.

next

The next method instructs the database object to continue to the next
row if it exists.

dbi->table->next;

while (dbi->table->next) {
    ...
}

first

The first method instructs the database object to continue to return the first
row in the resultset.

dbi->table->first;

last

The last method instructs the database object to continue to return the last
row in the resultset.

dbi->table->last;

collection

The collection method return the raw resultset object.

dbi->table->collection;

current

The current method return the raw row resultset object of the position in
the resultset collection.

dbi->table->current;

clear

The clear method empties all resultset containers. This method should be used
when your ready to perform another operation (start over) without initializing
a new object.

dbi->table->clear;

key

The key method finds the database objects primary key if its defined.

dbi->table->key;

return

The return method queries the database for the last created object(s).

my $new_record = dbi->table->create(...)->return;

count

The count method returns the number of items in the resultset of the
object it's called on.

my $count = dbi->table->read->count;

create

Caveat 1: The create method will remove the primary key if the column
is marked as auto-incremented ...

The create method creates a new entry in the datastore.
takes 1 arg: hashref (SQL::Abstract fields parameter)

dbi->table->create({
    'column_a' => 'value_a',
});

# create a copy of an existing record
my $user = dbi->users;
$user->read->first;
$user->full_name('Copy of ' . $user->full_name);
$user->user_name('foobarbaz');
$user->create($user->current);

# get newly created record
$user->return;

print $user->id; # new record id
print $user->full_name;

read

The read method fetches records from the datastore.
Takes 2 arg.

arg 1: hashref (SQL::Abstract where parameter) or scalar
arg 2: arrayref (SQL::Abstract order parameter) - optional

dbi->table->read({
    'column_a' => 'value_a',
});

or

dbi->table->read(1);

# return arrayref from read (select) method
my $records = dbi->table->read->collection

update

The update method alters an existing record in the datastore.
Takes 2 arg.

arg 1: hashref (SQL::Abstract fields parameter)
arg 2: arrayref (SQL::Abstract where parameter) or scalar - optional

dbi->table->update({
    'column_a' => 'value_a',
},{
    'where_column_a' => '...'
});

or

dbi->table->update({
    'column_a' => 'value_a',
}, 1);

delete

The delete method is prohibited from deleting an entire database table and
thus requires a where clause. If you intentionally desire to empty the entire
database then you may use the delete_all method.

dbi->table->delete({
    'column_a' => 'value_a',
});

or

dbi->table->delete(1);

delete

The delete_all method is use to intentiionally empty the entire database table.

dbi->table->delete_all;

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by awncorp.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.