NAME

Ormlette - Light and fluffy object persistence

VERSION

version 0.005

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.

isa

Specifies that all Ormlette-generated classes should be made subclasses of the isa package. This is done by directly setting @ISA, not via use base or use parent, so you are responsible for ensuring that the specified class is available to use as a parent.

If Ormlette is adding to a class which already exists and already has a parent in @ISA, the existing parent will be untouched and the isa option will have no effect on that class.

ignore_root

Ormlette will normally inject a dbh method into the base namespace of its generated code, providing access to the source database. This is not always desirable. In such cases, setting ignore_root will prevent Ormlette from making any modifications to that package.

ignore_tables

Ormlette will normally generate classes corresponding to all tables found in the database. If there are tables which should be skipped over, a reference to an array of table names to skip can be passed in the ignore_tables parameter.

If you prefer to list the tables to include rather than the tables to exclude, use tables. There should never be a reason to specify both tables and ignore_tables, but, if this is done, tables will take precedence and ignore_tables will be silently ignored.

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.

If you prefer to list the tables to exclude rather than those to include, use ignore_tables.

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 (unless the ignore_root option is set when calling init), or any of the persistent classes generated in that namespace.

Root Namespace Methods

If the ignore_root option is set when calling init, no methods will be generated in the root namespace.

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.

dirty

Read-only flag indicating whether an object is "dirty" (i.e., has unsaved changes). This flag is not maintained automatically; code using the object must use its mark_dirty method to set the flag and mark_clean to clear it.

If an object is destroyed while dirty, a DESTROY handler will automatically call its update method to write changes to the database. If the class already has a DESTROY handler prior to Ormlette initialization, this check is instead placed into an _ormlette_DESTROY method, which the other DESTROY should call if autoupdate functionality is desired.

The dirty attribute, mark_dirty and mark_clean methods, and DESTROY handler will not be generated if readonly is set or for tables which do not 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.

mark_clean

Clears an object's dirty flag.

mark_dirty

Sets an object's dirty flag.

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 implicitly call insert 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) 2012 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