Merge 'DBIx-Class-current' into 'versioning'

diff --combined lib/DBIx/Class/Schema.pm

index 5b53140,77bd865..1d6af1e
--- 1/lib/DBIx/Class/Schema.pm
--- 2/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@@ -5,7 -5,6 +5,7 @@@ use warnings
  
  use Carp::Clan qw/^DBIx::Class/;
  use Scalar::Util qw/weaken/;
+ +use File::Spec;
  require Module::Find;
  
  use base qw/DBIx::Class/;
@@@ -448,7 -447,7 +448,7 @@@ sub load_namespaces 
    return;
  }
  
- =head2 compose_connection
+ =head2 compose_connection (DEPRECATED)
  
  =over 4
  
@@@ -458,6 -457,12 +458,12 @@@
  
  =back
  
+ DEPRECATED. You probably wanted compose_namespace.
+ 
+ Actually, you probably just wanted to call connect.
+ 
+ =for hidden due to deprecation
+ 
  Calls L<DBIx::Class::Schema/"compose_namespace"> to the target namespace,
  calls L<DBIx::Class::Schema/connection> with @db_info on the new schema,
  then injects the L<DBix::Class::ResultSetProxy> component and a
@@@ -472,43 -477,50 +478,50 @@@ more information
  
  =cut
  
- sub compose_connection {
-   my ($self, $target, @info) = @_;
-   my $base = 'DBIx::Class::ResultSetProxy';
-   eval "require ${base};";
-   $self->throw_exception
-     ("No arguments to load_classes and couldn't load ${base} ($@)")
-       if $@;
- 
-   if ($self eq $target) {
-     # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
-     foreach my $moniker ($self->sources) {
-       my $source = $self->source($moniker);
+ {
+   my $warn;
+ 
+   sub compose_connection {
+     my ($self, $target, @info) = @_;
+ 
+     warn "compose_connection deprecated as of 0.08000" unless $warn++;
+ 
+     my $base = 'DBIx::Class::ResultSetProxy';
+     eval "require ${base};";
+     $self->throw_exception
+       ("No arguments to load_classes and couldn't load ${base} ($@)")
+         if $@;
+   
+     if ($self eq $target) {
+       # Pathological case, largely caused by the docs on early C::M::DBIC::Plain
+       foreach my $moniker ($self->sources) {
+         my $source = $self->source($moniker);
+         my $class = $source->result_class;
+         $self->inject_base($class, $base);
+         $class->mk_classdata(resultset_instance => $source->resultset);
+         $class->mk_classdata(class_resolver => $self);
+       }
+       $self->connection(@info);
+       return $self;
+     }
+   
+     my $schema = $self->compose_namespace($target, $base);
+     {
+       no strict 'refs';
+       *{"${target}::schema"} = sub { $schema };
+     }
+   
+     $schema->connection(@info);
+     foreach my $moniker ($schema->sources) {
+       my $source = $schema->source($moniker);
        my $class = $source->result_class;
-       $self->inject_base($class, $base);
+       #warn "$moniker $class $source ".$source->storage;
+       $class->mk_classdata(result_source_instance => $source);
        $class->mk_classdata(resultset_instance => $source->resultset);
-       $class->mk_classdata(class_resolver => $self);
+       $class->mk_classdata(class_resolver => $schema);
      }
-     $self->connection(@info);
-     return $self;
-   }
- 
-   my $schema = $self->compose_namespace($target, $base);
-   {
-     no strict 'refs';
-     *{"${target}::schema"} = sub { $schema };
-   }
- 
-   $schema->connection(@info);
-   foreach my $moniker ($schema->sources) {
-     my $source = $schema->source($moniker);
-     my $class = $source->result_class;
-     #warn "$moniker $class $source ".$source->storage;
-     $class->mk_classdata(result_source_instance => $source);
-     $class->mk_classdata(resultset_instance => $source->resultset);
-     $class->mk_classdata(class_resolver => $schema);
+     return $schema;
    }
-   return $schema;
  }
  
  =head2 compose_namespace
@@@ -647,7 -659,6 +660,7 @@@ sub connection 
    my $storage = $storage_class->new($self);
    $storage->connect_info(\@info);
    $self->storage($storage);
+ +  $self->on_connect() if($self->can('on_connect'));
    return $self;
  }
  
@@@ -903,41 -914,16 +916,41 @@@ sub deploy 
  
  =over 4
  
- -=item Arguments: \@databases, $version, $directory, $sqlt_args
+ +=item Arguments: \@databases, $version, $directory, $preversion, $sqlt_args
  
  =back
  
  Creates an SQL file based on the Schema, for each of the specified
- -database types, in the given directory.
+ +database types, in the given directory. Given a previous version number,
+ +this will also create a file containing the ALTER TABLE statements to
+ +transform the previous schema into the current one. Note that these
+ +statements may contain DROP TABLE or DROP COLUMN statements that can
+ +potentially destroy data.
+ +
+ +The file names are created using the C<ddl_filename> method below, please
+ +override this method in your schema if you would like a different file
+ +name format. For the ALTER file, the same format is used, replacing
+ +$version in the name with "$preversion-$version".
+ +
+ +If no arguments are passed, then the following default values are used:
+ +
+ +=over 4
+ +
+ +=item databases  - ['MySQL', 'SQLite', 'PostgreSQL']
+ +
+ +=item version    - $schema->VERSION
+ +
+ +=item directory  - './'
+ +
+ +=item preversion - <none>
+ +
+ +=back
  
  Note that this feature is currently EXPERIMENTAL and may not work correctly
  across all databases, or fully handle complex relationships.
  
+ +WARNING: Please check all SQL files created, before applying them.
+ +
  =cut
  
  sub create_ddl_dir {
@@@ -949,30 -935,19 +962,30 @@@
  
  =head2 ddl_filename (EXPERIMENTAL)
  
- -  my $filename = $table->ddl_filename($type, $dir, $version)
+ +=over 4
+ +
+ +=item Arguments: $directory, $database-type, $version, $preversion
+ +
+ +=back
+ +
+ +  my $filename = $table->ddl_filename($type, $dir, $version, $preversion)
+ +
+ +This method is called by C<create_ddl_dir> to compose a file name out of
+ +the supplied directory, database type and version number. The default file
+ +name format is: C<$dir$schema-$version-$type.sql>.
  
- -Creates a filename for a SQL file based on the table class name.  Not
- -intended for direct end user use.
+ +You may override this method in your schema if you wish to use a different
+ +format.
  
  =cut
  
  sub ddl_filename {
- -    my ($self, $type, $dir, $version) = @_;
+ +    my ($self, $type, $dir, $version, $pversion) = @_;
  
      my $filename = ref($self);
      $filename =~ s/::/-/;
- -    $filename = "$dir$filename-$version-$type.sql";
+ +    $filename = File::Spec->catfile($dir, "$filename-$version-$type.sql");
+ +    $filename =~ s/$version/$pversion-$version/ if($pversion);
  
      return $filename;
  }