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

THIS CODE IS EXPERIMENTAL AND SUBJECT TO CHANGE WITHOUT NOTICE

YOU HAVE BEEN WARNED!

SQLite is a light weight 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 for SQLite that follows many of the same principles as the ::Tiny series of modules and has a design 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 will work.

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.