view release on metacpan or  search on metacpan

lib/Class/DBI/AutoIncrement.pm  view on Meta::CPAN

    # seqid is automatically incremented by 3 at each insert, starting at 5
    MyProject::Book->autoincrement('seqid', Min => 5, Step => 3);    

By default Class::DBI::AutoIncrement queries the database for the current
highest value of the auto-incremented column upon each call to C<insert>.
If you want to let Class::DBI::AutoIncrement cache this value, set the
'Cache' parameter to true:

    # seqid is automatically incremented by 1 at each insert, and query the database
    # only the first time we need to know the current index value
    MyProject::Book->autoincrement('seqid', Cache => 1);

=item B<insert>(\%data)

Overrides Class::DBI's C<insert> method. If C<< $data->{$column} >> is undefined,
it is automagically set to its next value. If C<< $data->{$column} >> is defined,
this value is used unchanged.

=item B<create>(\%data)

This method is supported for backward compatibility reasons. Do not use it.
Same as C<insert>.

=back

=head1 DIAGNOSTICS

=over

=item "you must define a column name to autoincrement."

You tried to call 'autoincrement' without specifying a column name.

=item "class <class> already has one auto-incremented column"

You tried to call 'autoincrement' twice for the same table/class.

=item "parameter 'Min' of method 'autoincrement' must be a number."

You called the method 'autoincrement' with an invalid number beside the 'Min' attribute. 

=item "no auto-incremented column has been specified for class <class>"

You most likely tried to call 'insert' without having first called 'autoincrement'.

=item "no database table has been specified for class <class>"

You most likely tried to call 'insert' without having first called the Class::DBI methods 'table'.

=item "BUG: 'require <class>' failed because of: ..."

Class::DBI::AutoIncrement failed to find the package <class> in @INC.

=item "Class::DBI::AutoIncrement expects class $caller to inherit from at least 1 more parent class"

A child class of Class::DBI::AutoIncrement must inherit from at least Class::DBI::AutoIncrement and an other class that subclasses Class::DBI 
(or Class::DBI itself).

=back

=head1 BUGS AND LIMITATIONS

Class::DBI::AutoIncrement silently modifies the class hierarchy
of its children classes during runtime. You might get weird
results if your code relies on a static class hierarchy.

If you are using caching, either let Class::DBI::AutoIncrement handle 
the computation of the next sequence index completly or do it all by yourself, 
but do not mix both ways or you will get weird results. Really.

Fetching the current highest value of the sequence from the database
and inserting a new row is not done atomically. You will get race
conditions if multiple threads are inserting into the same table.

=head1 THANKS

Big thanks to David Westbrook for providing me with exemplar
bug reports and usefull inspiration!

=head1 SEE ALSO

See Class::DBI.

See Class::DBI::AutoIncrement::Simple for a simpler alternative that should fit
most of your needs.

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005 by Erwan Lemonnier C<< <erwan@cpan.org> >>

This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See L<perlartistic>.

=head1 DISCLAIMER OF WARRANTY

Because this software is licensed free of charge, there is no warranty
for the software, to the extent permitted by applicable law. Except when
otherwise stated in writing the copyright holders and/or other parties
provide the software "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. The
entire risk as to the quality and performance of the software is with
you. Should the software prove defective, you assume the cost of all
necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing
will any copyright holder, or any other party who may modify and/or
redistribute the software as permitted by the above licence, be
liable to you for damages, including any general, special, incidental,
or consequential damages arising out of the use or inability to use
the software (including but not limited to loss of data or data being
rendered inaccurate or losses sustained by you or third parties or a
failure of the software to operate with any other software), even if
such holder or other party has been advised of the possibility of
such damages.

=cut