NAME
ORLite - Extremely light weight SQLite-specific ORM
SYNOPSIS
package Foo;
use strict;
use ORLite 'data/sqlite.db';
my @awesome = Foo::Person->select(
'where first_name = ?',
'Adam',
);
DESCRIPTION
SQLite is a light single file SQL database that provides an excellent
platform for embedded storage of structured data.
However, while it is superficially similar to a regular server-side SQL
database, SQLite has some significant attributes that make using it like
a traditional database difficult.
For example, SQLite is extremely fast to connect to compared to server
databases (1000 connections per second is not unknown) and is
particularly bad at concurrency, as it can only lock transactions at a
database-wide level.
This role as a superfast internal data store can clash with the roles
and designs of traditional object-relational modules like Class::DBI or
DBIx::Class.
What this situation would seem to need is an object-relation system that
is designed specifically for SQLite and is aligned with its
idiosyncracies.
ORLite is an object-relation system specifically tailored for SQLite
that follows many of the same principles as the ::Tiny series of modules
and has a design and feature set that aligns directly to the
capabilities of SQLite.
Further documentation will be available at a later time, but the
synopsis gives a pretty good idea of how it works.
How it Works
In short, ORLite discovers the schema of a SQLite database, and then
uses code generation to build a set of packages for talking to that
database.
In the simplest form, your target root package "uses" ORLite, which will
do the schema discovery and code generation at compile-time.
When called, ORLite generates two types of package.
Firstly, it builds database connectivity, transaction support, and other
purely database level functionality into your root namespace.
Then it will create one sub-package underneath the root package for each
table contained in the database.
ROOT PACKAGE METHODS
All ORLite root packages receive an identical set of methods for
controlling connections to the database, transactions, and the issueing
of queries of various types to the database.
The example root package Foo::Bar is used in any examples.
All methods are static, ORLite does not allow the creation of a Foo::Bar
object (although you may wish to add this capability yourself).
dsn
my $string = Foo::Bar->dsn;
The "dsn" accessor returns the dbi connection string used to connect to
the SQLite database as a string.
dbh
my $handle = Foo::Bar->dbh;
To reliably prevent potential SQLite deadlocks resulting from multiple
connections in a single process, each ORLite package will only ever
maintain a single connection to the database.
During a transaction, this will be the same (cached) database handle.
Although in most situations you should not need a direct DBI connection
handle, the "dbh" method provides a method for getting a direct
connection in a way that is compatible with ORLite's connection
management.
Please note that these connections should be short-lived, you should
never hold onto a connection beyond the immediate scope.
The transaction system in ORLite is specifically designed so that code
using the database should never have to know whether or not it is in a
transation.
Because of this, you should never call the ->disconnect method on the
database handles yourself, as the handle may be that of a currently
running transaction.
Further, you should do your own transaction management on a handle
provided by the <dbh> method.
In cases where there are extreme needs, and you absolutely have to
violate these connection handling rules, you should create your own
completely manual DBI->connect call to the database, using the connect
string provided by the "dsn" method.
The "dbh" method returns a DBI::db object, or throws an exception on
error.
begin
Foo::Bar->begin;
The "begin" method indicates the start of a transaction.
In the same way that ORLite allows only a single connection, likewise it
allows only a single application-wide transaction.
No indication is given as to whether you are currently in a transaction
or not, all code should be written neutrally so that it works either way
or doesn't need to care.
Returns true or throws an exception on error.
commit
Foo::Bar->commit;
The "commit" method commits the current transaction. If called outside
of a current transaction, it is accepted and treated as a null
operation.
Once the commit has been completed, the database connection falls back
into auto-commit state. If you wish to immediately start another
transaction, you will need to issue a separate ->begin call.
Returns true or throws an exception on error.
rollback
The "rollback" method rolls back the current transaction. If called
outside of a current transaction, it is accepted and treated as a null
operation.
Once the rollback has been completed, the database connection falls back
into auto-commit state. If you wish to immediately start another
transaction, you will need to issue a separate ->begin call.
If a transaction exists at END-time as the process exits, it will be
automatically rolled back.
Returns true or throws an exception on error.
do
Foo::Bar->do('insert into table (foo, bar) values (?, ?)', {},
$foo_value,
$bar_value,
);
The "do" method is a direct wrapper around the equivalent DBI method,
but applied to the appropriate locally-provided connection or
transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectall_arrayref
The "selectall_arrayref" method is a direct wrapper around the
equivalent DBI method, but applied to the appropriate locally-provided
connection or transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectall_hashref
The "selectall_hashref" method is a direct wrapper around the equivalent
DBI method, but applied to the appropriate locally-provided connection
or transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectcol_arrayref
The "selectcol_arrayref" method is a direct wrapper around the
equivalent DBI method, but applied to the appropriate locally-provided
connection or transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectrow_array
The "selectrow_array" method is a direct wrapper around the equivalent
DBI method, but applied to the appropriate locally-provided connection
or transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectrow_arrayref
The "selectrow_arrayref" method is a direct wrapper around the
equivalent DBI method, but applied to the appropriate locally-provided
connection or transaction.
It takes the same parameters and has the same return values and error
behaviour.
selectrow_hashref
The "selectrow_hashref" method is a direct wrapper around the equivalent
DBI method, but applied to the appropriate locally-provided connection
or transaction.
It takes the same parameters and has the same return values and error
behaviour.
prepare
The "prepare" method is a direct wrapper around the equivalent DBI
method, but applied to the appropriate locally-provided connection or
transaction
It takes the same parameters and has the same return values and error
behaviour.
In general though, you should try to avoid the use of your own prepared
statements if possible, although this is only a recommendation and by no
means prohibited.
pragma
# Get the user_version for the schema
my $version = Foo::Bar->pragma('user_version');
The "pragma" method provides a convenient method for fetching a pragma
for a datase. See the SQLite documentation for more details.
TABLE PACKAGE METHODS
The example root package Foo::Bar::TableName is used in any examples.
TO BE COMPLETED
TO DO
- Support for intuiting reverse relations from foreign keys
- Document the 'create' and 'table' params
SUPPORT
Bugs should be reported via the CPAN bug tracker at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=ORLite>
For other issues, contact the author.
AUTHOR
Adam Kennedy <adamk@cpan.org>
SEE ALSO
ORLite::Mirror, ORLite::Migrate
COPYRIGHT
Copyright 2008 - 2009 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.