The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DBIx-StORM-0.11
++
/ DBIx::StORM

NAME

DBIx::StORM - Perl extension for object-relational mapping

SYNOPSIS

  use DBIx::StORM;

  my $connection = DBIx::StORM->connect($dbi_dsn, $user, $password);
  my $table = $connection->{table_name};

DESCRIPTION

DBIx::StORM is an object-relational mapper designed to provide easy database-vendor-independent access to a DBI-accessible database by allowing you to access a relational database in an object-oriented fashion, using perl expressions to specify your criteria.

If you'd like to know what makes DBIx::StORM different from other ORMs then please see "DESIGN PRINCIPLES" below.

If you're after a quick-start guide please see DBIx::StORM::Tutorial.

DESIGN PRINCIPLES

  • Gets to work quickly with your database

    DBI::StORM is designed to work around your database. You don't have to follow any naming conventions on your tables or columns. The module will find out the primary and foreign keys in your database, and will help you walk the foreign keys.

    If your database schema is lacking the necessary metadata you can point the module in the right direction with the $dbix_storm->add_hint method.

  • Connection-centric, not class-centric

    Tables are accessed via the connection object and not via a specific class, which makes it easy to access new tables. If you want to set up a class that maps to a given table, you can use the helper class to do this.

  • Finding and sorting should follow perl

    DBIx::StORM provides the grep and sort methods which like the perl operators accept a subroutine reference that can do whatever you want them to. No passing round chunks of SQL, custom pseudo-code or lists of string operators. Your perl subs are syntax-checked at compile time just as normal.

  • But this shouldn't come at the cost of performance

    DBIx::StORM will examine your subroutines and understand what it is trying to do. It can then turn it into SQL and use the power of the database to your advantage. This gives you the best of both worlds - the portability of perl code to query the database, but the performance of the native database query. Judicious use of caching means that the subroutine should only be compiled when needed.

  • Objects should feel like corresponding perl datatypes

    Using perl's overloading, you can examine the tables in a connection by treating it like a hash reference, a result set works like an array reference and a record works like a hash reference. You get the power of standard perl functions to access your data.

THE DBIx::StORM OBJECT

This class is the base of the StORM ORM system. This class represents a database connection.

You can dereference this object to access a hash. The hash keys are the string names of the tables available on this connection, and the values are the corresponding DBIx::StORM::Table objects.

METHODS

CONNECT

  DBIx::StORM->connect($dsn, $user, $password)

Build a new DBIx::StORM by establishing a DBI connection to $dsn using username $user and password $password. Returns a new object on success or undef on failure.

CONNECT_CACHED

  DBIx::StORM->connect($dsn, $user, $password)

Build a new DBIx::StORM by establishing a DBI connection to $dsn using username $user and password $password. This uses DBI's connect_cached() call that will re-use an existing database connection if appropriate, instead of unconditionally creating a new one. Returns a new object on success or undef on failure.

DBI

  $dbix_StORM->dbi()

Retrieve the DBI object underpinning this connection object.

GET

  $dbix_StORM->get($tablename)

Access a DBIx::StORM::Table object for table $tablename on this connection. Returns undef on failure or if no such table exists.

ADD_HINT

  $dbix_StORM->add_hint($type => $hint [, $type => $hint ... ])

Add a hint to the StORM's metadata. This is typically used to add foreign key information for database systems that don't natively support them.

VARIABLES

$DEBUG

If set to a true value the DBIx::StORM framework will emit additional messages to STDERR which may be useful in debugging issues.

SEE ALSO

  L<DBI>
  L<DBIx::StORM::Table>

AUTHOR

Luke Ross, <luke@lukeross.name>

COPYRIGHT AND LICENSE

Copyright (C) 2006-2008 by Luke Ross

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.