NAME

Ormlette - Light and fluffy object persistence

VERSION

version 0.002

SYNOPSIS

my $dbh = DBI->connect(...);
Ormlette->init($dbh, tables => [ 'my_table' ], namespace => Test);

my $obj = Test::MyTable->create(foo => 1, bar => 3);
print Test::MyTable->load(foo => 1)->bar; # 3

DESCRIPTION

Ormlette is a simple object persistence mechanism which is specifically designed to avoid imposing any requirements on how your code is organized or what base classes you use.

Rather than requiring your classes to inherit from it, Ormlette is initialized by passing an open database handle to Ormlette->init, at which point Ormlette will identify the tables in that database and, for each one, derive a package name by camel-casing the table name using _ in the table name as a word break (e.g., foo_bar becomes FooBar) and prepending the current package's name. It will then inject its methods (see below) into the resulting package. It will also create accessors corresponding to each of the table's fields unless these accessors already exist.

Note that, if you want to define your own methods within a package which will have methods injected by Ormlette, you should load the corresponding module (with use or require) before doing any Ormlette initializations affecting that package so that Ormlette will know what methods you've defined yourself and avoid interfering with them.

Ormlette Core Methods

init ($dbh, %params)

Attaches Ormlette methods to classes corresponding to tables in the database connected to $dbh. Recognized parameters:

debug

The debug option will cause additional debugging information to be printed to STDERR as Ormlette does its initialization. At this point, this consists solely of the generated source code for each package affected by Ormlette.

namespace

By default, Ormlette will use the name of the package which calls init as the base namespace for its generated code. If you want the code to be placed into a different namespace, use the namespace parameter to override this default.

readonly

If readonly is set to a true value, no constructors or database-altering methods will be created and generated accessors will be read-only.

tables

If you only require Ormlette code to be generated for some of the tables in your database, providing a reference to an array of table names in the tables parameter will cause all other tables to be ignored.

dbh

Returns the internal database handle used for database interaction. Can be called on the core Ormlette object, the root namespace of its generated code, or any of the persistent classes generated in that namespace.

Root Namespace Methods

dbh

Returns the database handle attached by Ormlette to the root namespace. If multiple Ormlette objects have been instantiated with the same namespace, this will return the handle corresponding to the first Ormlette initialized there.

Table Class Methods

In addition to the methods listed below, accessors will be generated for each field found in the table unless an accessor for that field already exists, providing the convenience of not having to create all the accessors yourself while also allowing for custom accessors to be used where needed. Generated accessors will be read-only if readonly is set or writable using the $obj->attr('new value') convention otherwise.

Note that the generated accessors are extremely simple and make no attempt at performing any form of data validation, so you may wish to use another fine CPAN module to generate accessors before initializing Ormlette.

create

Constructs an object by calling new, then uses insert to immediately store it to the database.

This method will not be generated if readonly is set.

dbh

Returns the database handle used by Ormlette operations on this class.

delete

delete('WHERE name = ?', 'John Doe')

As a class method, deletes all objects matching the criteria specified in the parameters. In an attempt to avoid data loss from accidentally calling delete as a class method when intending to use it as an instance method, nothing will be done if no criteria are provided.

As an instance method, deletes the object from the database. In this case, any parameters will be ignored. The in-memory object is unaffected and remains available for further use, including re-saving it to the database.

This method will not be generated if readonly is set. The instance method variant will only be generated for tables which have a primary key.

insert

Inserts the object into the database as a new record. This method will fail if the record cannot be inserted. If the table uses an autoincrement/serial primary key and no value for that key is set in the object, the in-memory object will be updated with the id assigned by the database.

This method will not be generated if readonly is set.

iterate(sub { print $_->id })

iterate(sub { print $_->name }, 'WHERE age > ?', 18)

Takes a sub reference as the first parameter and passes each object returned by the subsequent query to the referenced sub in $_ for processing. The primary difference between this method and select is that iterate only loads one record into memory at a time, while select loads all records at once, which may require unacceptable amounts of memory when dealing with larger data sets.

new

Basic constructor which accepts a hash of values and blesses them into the class. If a ->new method has already been defined, it will not be replaced. If you wish to retain the default constructor functionality within your custom ->new method, you can call $class->_ormlette_new to do so.

This method will not be generated if readonly is set.

load(1)

load(foo => 1, bar => 2)

Retrieves a single object from the database based on the specified criteria.

If the table has a single-field primary key, passing a single argument will retrieve the record with that value as its primary key.

Lookups on non-key fields or multiple-field primary keys can be performed by passing a hash of field => value pairs. If more than one record matches the given criteria, only one will be returned; which one is returned may or may not be consistent from one call to the next.

Returns undef if no matching record exists.

select

select('WHERE id = 42');

select('WHERE id > ? ORDER BY name LIMIT 5', 3);

Returns a reference to an array containing all objects matching the query specified in the parameters, in the order returned by that query. If no parameters are provided, returns objects for all records in the database's natural sort order.

As this method simply appends its parameters to "SELECT (fields) FROM (table)", arbitrarily-complex queries can be built up in the parameters, including joins and subqueries.

table

Returns the table name in which Ormlette stores this class's data.

update

Updates the object's existing database record. This method will fail if the object does not already exist in the database.

This method will not be generated if readonly is set or for tables which do not have a primary key.

TO DO

• Verify functionality with DBD back-ends other than SQLite

• Add support for multi-level package hierarchies

• Allow all Ormlette functions to be overridden, not just new and accessors

• Add transaction support

• Cache loaded objects to prevent duplication

CREDITS

Although it is not intended as a drop-in replacement, Ormlette's API and general coding style are heavily influenced by Adam Kennedy's ORLite.

AUTHOR

Dave Sherohman <dsheroh@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Dave Sherohman.

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

cpanm Ormlette

perl -MCPAN -e shell
install Ormlette