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

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;
        }
      }

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.

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/

  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.

  Prerequisites

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

  Tested Platforms

    This release has been tested succesfully on the following platforms:

      5.6.1 on darwin
      5.005_03 on i386-freebsd

VERSION
    This is version 0.005 of DBIx::DBO2.

  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

  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.

  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.

SEE ALSO
    See the DBIx::SQLEngine manpage for information about the underlying
    database interface.

    See the DBIx::DBO2::Record manpage, the DBIx::DBO2::Fields manpage, the
    DBIx::DBO2::Table manpage, and the DBIx::DBO2::TableSet manpage for key
    interfaces.

  Similar Modules

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

    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:

    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.

    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.

    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.

    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.)

    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.

    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.)

    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.)

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

    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.)

    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.

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

    License
        GPL/Artistic disjunction. The same as Perl itself.

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

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

CREDITS AND COPYRIGHT
  Developed By

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

  Contributors

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

  Copyright

    Copyright 2002 Matthew Simon Cavalletto.

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

  License

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

