=head1 NAME

DBIx::DBO2::ReadMe - Getting Started with DBIx::DBO2


=head1 SYNOPSIS

  package MyRecord;
  use DBIx::DBO2::Record '-isasubclass';
  my $sql_engine = DBIx::SQLEngine->new( $dsn, $user, $pass );
  
  MyRecord->table(
    DBIx::DBO2::Table->new(name=>'myrecords', datasource=>$sql_engine)
  );
  
  package main;
  my $results = MyRecord->fetch_all;
  foreach my $record ( $results->records ) {
    if ( $record->{age} > 20 ) {
      $record->{status} = 'adult';
      $record->save_row;
    }
  }


=head1 DESCRIPTION

DBIx::DBO2 is an object-relational mapping framework (or perhaps a relational-object mapping framework, if I understand the distinction correctly) that facilitates the development of Perl classes whose objects are stored in a SQL database table.


=head1 INSTALLING

You should be able to install this module using the CPAN shell interface:

  perl -MCPAN -e 'install DBIx::DBO2'

If this module has not yet been posted to your local CPAN mirror,
you may also retrieve the current distribution from the below
address and follow the normal "gunzip", "tar xf", "cd", "perl Makefile.PL && make test && sudo make install" procedure or your local equivalent:

  http://www.evoscript.org/DBIx-DBO2/

=head2 Getting Started

You may want to take a look at the test.pl and test-lib/ classes included with this distribution for a short example of how to use this framework to create your own classes.

=head2 Prerequisites

Requires DBIx::SQLEngine and Class::MakeMethods, both available on CPAN.

=head2 Tested Platforms

This release has been tested succesfully on the following platforms:

  5.6.1 on darwin
  5.005_03 on i386-freebsd


=head1 VERSION

This is version 0.005 of DBIx::DBO2. 

=head2 Distribution Summary

This module's summary in the CPAN DSLIP is intended to read:

  Name            DSLIP  Description
  --------------  -----  ---------------------------------------------
  DBIx::
  ::DBO2          bdpOp  Objects mapping to SQL relational structures

=head2 Beta Release

Although it based on earlier code that was extensively tested over
several years of production use, this code has recently been majorly
refactored, and has not yet been sufficiently tested in its new
form.

=head2 Discussion and Support

There is not currently any offical discussion and support forum for this pacakage. 

Further information and support for this module is available at http://www.evoscript.org.

If you have questions or feedback about this module, please feel
free to contact the author at the below address.

I would be particularly interested in any suggestions towards
improving the documentation, correcting any Perl-version or platform
dependencies, as well as general feedback and suggestions.


=head1 SEE ALSO

See L<DBIx::SQLEngine> for information about the underlying database interface.

See L<DBIx::DBO2::Record>, L<DBIx::DBO2::Fields>, L<DBIx::DBO2::Table>, and L<DBIx::DBO2::TableSet> for key interfaces.

=head2 Similar Modules

Numerous modules on CPAN provide some type of system to map objects to and from SQL databases, including L<Class::DBI>, L<Alzabo>, and L<Tangram>.

See the Poop Group summary at http://poop.sourceforge.net/ for a review of several other CPAN modules which provide a similar RDBMS-to-OO mapping layer. 

For comparison purposes, here are some of the questions asked by the Poop Group summary and their answers for this module:

=over 4

=item Supported Databases

Currently supports DBD::AnyData, DBD::CSV, DBD::MySQL, and DBD::Pg.

Providing support for other drivers involves creating a DBD-specific subclass of DBIx::SQLEngine (which will be loaded via DBIx::AnyDBD when appropriate), and should only require a limited amount of coding.

=item SQL Abstraction

This module supports moderately complex selects, inserts, updates, and deletes, based on the DBIx::SQLEngine abstraction layer. It is possible to apply order by and group by clauses to operations, as well as limits.

Inserts with sequences are supported, with DBIX::SQLEngine providing a workaround using its own sequence table logic for DBDs which don't have native sequence/auto_increment equivalents.

Joins are not supported, although it is possible to pass in snippets of SQL to accomplish this, or to provide your own logic in a subclass. 

=item Invalid SQL

The automated SQL generation should produce valid SQL, but if you pass in incorrect information, such as explicitly requesting a column name which does not exist in the database, or if you pass in a SQL snippet as part of a query, there is no way to validate this prior to actually executing the query and receiving an error from the DBMS.

=item Deferred/Preloaded data retrieval

There is not yet any way to defer the loading of given columns for a select. However, it always possible to easily specify only those columns which are needed at a given point in your code. (Deferred loading of additional columns is expected in an upcomming release.)

=item Table Relationships

DBIx::DBO2 supports both many-to-one (foreign key) and one-to-many (reverse foreign key) relationships. Support for one-to-many relationships includes your choice of cascading delete, nullify after delete, and restrict delete rules. You can establish relationships between classes regardless of whether their data is actually stored in the same underlying SQL database.

=item Multiple rows and cursors

DBIx::DBO2 currently returns multiple rows all at once. A RecordSet object similar to a cursor is used by it does not yet handle incremental retrieval. (Support for cursors and automatic iteration with closures is expected in an upcomming release.)

=item Caching

There is no built in caching support. (Support for LRU caching and ensuring that there is only a single instance of a given object in memory at any time are both expected in an upcomming release.)

=item Transactions

DBIx::DBO2 does not support transactions. (Basic transactions for DBDs which support them are expected in an upcomming release.)

=item Auto-generated methods

The included DBIx::DBO2::Fields package can generate a wide variety of methods, including customized accessors for each type of field or relationship. (These currently require explicit declarations, but support for automatic detection of database columns and subsequent method generation is expected in an upcomming release.)

=item Other

A callback mechanism allows you to specify method names or arbitrary subroutines to be called immediately before or after each record is retrieved, inserted, updated, or deleted. You can add these callbacks to all record classes, to a particular class, or even to a particular object instance.

=item Documentation

The documentation for this module is still fairly rough, although efforts are continuing to improve this.

=item License

GPL/Artistic disjunction. The same as Perl itself.

=item Support

Support for this module is available from the author (simonm@cavalletto.org). (The author is also available for support contracts or consulting engagements.)

=item Status

Recently released to CPAN after several years of in-house use. Actively developed and supported by the author.

=back


=head1 CREDITS AND COPYRIGHT

=head2 Developed By

  M. Simon Cavalletto, simonm@cavalletto.org
  Evolution Softworks, www.evoscript.org

=head2 Contributors

  Piglet / EJ Evans, piglet@piglet.org
  Eric Schneider, roark@evolution.com
  Chaos / Matthew Sheahan

=head2 Copyright

Copyright 2002 Matthew Simon Cavalletto. 

Portions copyright 1997, 1998, 1999, 2000, 2001 Evolution Online Systems, Inc.

=head2 License

You may use, modify, and distribute this software under the same terms as Perl.


=cut

1;
