Update examples to be more explicit about load_components order

[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / PK / Auto.pm

diff --git a/lib/DBIx/Class/PK/Auto.pm b/lib/DBIx/Class/PK/Auto.pm
index f4ee81c..6b5356a 100644 (file)
--- a/lib/DBIx/Class/PK/Auto.pm
+++ b/lib/DBIx/Class/PK/Auto.pm
@@ -1,5 +1,7 @@
 package DBIx::Class::PK::Auto;
 
+#use base qw/DBIx::Class::PK/;
+use base qw/DBIx::Class/;
 use strict;
 use warnings;
 
@@ -9,16 +11,40 @@ DBIx::Class::PK::Auto - Automatic Primary Key class
 
 =head1 SYNOPSIS
 
+    # In your table classes (replace PK::Auto::SQLite with your
+    # database)
+    __PACKAGE__->load_components(qw/PK::Auto::SQLite Core/);
+    __PACKAGE__->set_primary_key('id');
+
 =head1 DESCRIPTION
 
 This class overrides the insert method to get automatically
 incremented primary keys.
 
-=head1 METHODS
+You don't want to be using this directly - instead load the
+appropriate one for your database, e.g. C<PK::Auto::SQLite>, in your
+table classes:
+
+    __PACKAGE__->load_components(qw/PK::Auto::SQLite Core/);
+
+Note that C<PK::Auto::SQLite> is specified as the leftmost argument.
+
+Alternatively, you can load the components separately:
+
+    __PACKAGE__->load_components(qw/Core/);
+    __PACKAGE__->load_components(qw/PK::Auto::SQLite/);
+
+This can be used, for example, if you have different databases and
+need to determine the appropriate C<PK::Auto> class at runtime.
+
+=head1 LOGIC
+
+C<PK::Auto> does this by letting the database assign the primary key
+field and fetching the assigned value afterwards.
 
-=over 4
+=head1 METHODS
 
-=item insert
+=head2 insert
 
 Overrides insert so that it will get the value of autoincremented
 primary keys.
@@ -27,11 +53,17 @@ primary keys.
 
 sub insert {
   my ($self, @rest) = @_;
-  my $ret = $self->NEXT::ACTUAL::insert(@rest);
+  my $ret = $self->next::method(@rest);
+
+  # if all primaries are already populated, skip auto-inc
+  my $populated = 0;
+  map { $populated++ if defined $self->get_column($_) } $self->primary_columns;
+  return $ret if ( $populated == scalar $self->primary_columns );
+
   my ($pri, $too_many) =
-    (grep { $self->_primaries->{$_}{'auto_increment'} }
-       keys %{ $self->_primaries })
-    || (keys %{ $self->_primaries });
+    (grep { $self->column_info($_)->{'auto_increment'} }
+       $self->primary_columns)
+    || $self->primary_columns;
   $self->throw( "More than one possible key found for auto-inc on ".ref $self )
     if $too_many;
   unless (defined $self->get_column($pri)) {
@@ -44,13 +76,20 @@ sub insert {
   return $ret;
 }
 
-1;
+=head2 sequence
+
+Manually define the correct sequence for your table, to avoid the overhead
+associated with looking up the sequence automatically.
 
-=back
+=cut
+
+__PACKAGE__->mk_classdata('sequence');
+
+1;
 
 =head1 AUTHORS
 
-Matt S. Trout <perl-stuff@trout.me.uk>
+Matt S. Trout <mst@shadowcatsystems.co.uk>
 
 =head1 LICENSE