Ormlette - Light and fluffy object persistence
version 0.005
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
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.
Ormlette->init
_
foo_bar
FooBar
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.
use
require
Attaches Ormlette methods to classes corresponding to tables in the database connected to $dbh. Recognized parameters:
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.
debug
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.
isa
@ISA
use base
use 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.
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.
dbh
ignore_root
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.
ignore_tables
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.
tables
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.
init
namespace
If readonly is set to a true value, no constructors or database-altering methods will be created and generated accessors will be read-only.
readonly
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.
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.
If the ignore_root option is set when calling init, no methods will be generated in the root namespace.
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.
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.
$obj->attr('new value')
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.
Constructs an object by calling new, then uses insert to immediately store it to the database.
new
insert
This method will not be generated if readonly is set.
Returns the database handle used by Ormlette operations on this class.
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.
delete
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.
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.
mark_dirty
mark_clean
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.
DESTROY
update
_ormlette_DESTROY
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.
dirty
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.
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.
$_
select
iterate
Clears an object's dirty flag.
Sets an object's dirty flag.
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.
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.
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.
Returns the table name in which Ormlette stores this class's data.
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.
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
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.
Dave Sherohman <dsheroh@cpan.org>
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.
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head3'
=back without =over
To install Ormlette, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ormlette
CPAN shell
perl -MCPAN -e shell install Ormlette
For more information on module installation, please visit the detailed CPAN module installation guide.