view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    These are thin aliases through to the DBI's commit() and rollback()
    commands to commit or rollback all changes to this object.

  Localised Transactions
    A nice idiom for turning on a transaction locally (with AutoCommit
    turned on globally) (courtesy of Dominic Mitchell) is:

      sub do_transaction {
        my $class = shift;
        my ( $code ) = @_;
        # Turn off AutoCommit for this scope.
        # A commit will occur at the exit of this block automatically,
        # when the local AutoCommit goes out of scope.
        local $class->db_Main->{ AutoCommit };

        # Execute the required code inside the transaction.
        eval { $code->() };
        if ( $@ ) {
          my $commit_error = $@;
          eval { $class->dbi_rollback }; # might also die!
          die $commit_error;
        }
      }

      And then you just call:

      Music::DBI->do_transaction( sub {
        my $artist = Music::Artist->insert({ name => 'Pink Floyd' });
        my $cd = $artist->add_to_cds({ 
          title => 'Dark Side Of The Moon', 
          year => 1974,
        });
      });

    Now either both will get added, or the entire transaction will be rolled
    back.

UNIQUENESS OF OBJECTS IN MEMORY
    Class::DBI supports uniqueness of objects in memory. In a given perl
    interpreter there will only be one instance of any given object at one
    time. Many variables may reference that object, but there can be only
    one.

    Here's an example to illustrate:

      my $artist1 = Music::Artist->insert({ artistid => 7, name => 'Polysics' });
      my $artist2 = Music::Artist->retrieve(7);
      my $artist3 = Music::Artist->search( name => 'Polysics' )->first;

    Now $artist1, $artist2, and $artist3 all point to the same object. If
    you update a property on one of them, all of them will reflect the
    update.

    This is implemented using a simple object lookup index for all live
    objects in memory. It is not a traditional cache - when your objects go
    out of scope, they will be destroyed normally, and a future retrieve
    will instantiate an entirely new object.

    The ability to perform this magic for you replies on your perl having
    access to the Scalar::Util::weaken function. Although this is part of
    the core perl distribution, some vendors do not compile support for it.
    To find out if your perl has support for it, you can run this on the
    command line:

      perl -e 'use Scalar::Util qw(weaken)'

    If you get an error message about weak references not being implemented,
    Class::DBI will not maintain this lookup index, but give you a separate
    instances for each retrieve.

    A few new tools are offered for adjusting the behavior of the object
    index. These are still somewhat experimental and may change in a future
    release.

  remove_from_object_index
      $artist->remove_from_object_index();

    This is an object method for removing a single object from the live
    objects index. You can use this if you want to have multiple distinct
    copies of the same object in memory.

  clear_object_index
      Music::DBI->clear_object_index();

    You can call this method on any class or instance of Class::DBI, but the
    effect is universal: it removes all objects from the index.

  purge_object_index_every
      Music::Artist->purge_object_index_every(2000);

    Weak references are not removed from the index when an object goes out
    of scope. This means that over time the index will grow in memory. This
    is really only an issue for long-running environments like mod_perl, but
    every so often dead references are cleaned out to prevent this. By
    default, this happens every 1000 object loads, but you can change that
    default for your class by setting the 'purge_object_index_every' value.

    (Eventually this may handled in the DESTROY method instead.)

    As a final note, keep in mind that you can still have multiple distinct
    copies of an object in memory if you have multiple perl interpreters
    running. CGI, mod_perl, and many other common usage situations run
    multiple interpreters, meaning that each one of them may have an
    instance of an object representing the same data. However, this is no
    worse than it was before, and is entirely normal for database
    applications in multi-process environments.

SUBCLASSING
    The preferred method of interacting with Class::DBI is for you to write
    a subclass for your database connection, with each table-class
    inheriting in turn from it.

    As well as encapsulating the connection information in one place, this
    also allows you to override default behaviour or add additional
    functionality across all of your classes.

    As the innards of Class::DBI are still in flux, you must exercise
    extreme caution in overriding private methods of Class::DBI (those
    starting with an underscore), unless they are explicitly mentioned in
    this documentation as being safe to override. If you find yourself
    needing to do this, then I would suggest that you ask on the mailing
    list about it, and we'll see if we can either come up with a better
    approach, or provide a new means to do whatever you need to do.

CAVEATS