From: Peter Rabbitson <ribasushi@cpan.org>
Date: Wed, 21 Jan 2009 13:51:21 +0000 (+0000)
Subject: First stab at properly documenting the new sqlt_hook for resultsources
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=2d7d8459576fcc3f41845b40d755fc83a4b04c01;p=dbsrgits%2FDBIx-Class-Historic.git

First stab at properly documenting the new sqlt_hook for resultsources
---

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index b86ab7a..216d71b 100644
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -820,7 +820,7 @@ above is not fast enough for you, you can use a DBIx::Class to return values
 exactly as they come out of the data base with none of the convenience methods
 wrapped round them.
 
-This is used like so:-
+This is used like so:
 
   my $cursor = $rs->cursor
   while (my @vals = $cursor->next) {
@@ -1167,7 +1167,9 @@ C<oracles.heavily(nested(functions_can('take', 'lots'), OF), 'args')>
 
 Often you will want indexes on columns on your table to speed up searching. To
 do this, create a method called C<sqlt_deploy_hook> in the relevant source 
-class:
+class (refer to the advanced 
+L<callback system|DBIx::Class::ResultSource/sqlt_deploy_callback> if you wish
+to share a hook between multiple sources):
 
  package My::Schema::Artist;
 
@@ -1201,9 +1203,11 @@ created:
    $sqlt_schema->drop_table('table_name');
  }
 
-You could also add views or procedures to the output using 
-L<SQL::Translator::Schema/add_view> or 
-L<SQL::Translator::Schema/add_procedure>.
+You could also add views, procedures or triggers to the output using
+L<SQL::Translator::Schema/add_view>,
+L<SQL::Translator::Schema/add_procedure> or
+L<SQL::Translator::Schema/add_trigger>.
+
 
 =head2 Schema versioning
 
diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm
index 4f62cba..cbba2a0 100644
--- a/lib/DBIx/Class/ResultSource.pm
+++ b/lib/DBIx/Class/ResultSource.pm
@@ -994,28 +994,6 @@ sub compare_relationship_keys {
   return $found;
 }
 
-=head2 sqlt_deploy_hook
-
-=over 4
-
-=item Arguments: $source, $sqlt_table
-
-=item Return value: undefined
-
-=back
-
-This is NOT a method of C<ResultSource>.
-
-An optional sub which you can declare in your own Result class that will get 
-passed the L<SQL::Translator::Schema::Table> object when you deploy the schema
-via L</create_ddl_dir> or L</deploy>.
-
-This is useful to make L<SQL::Translator> create non-unique indexes,
-or set table options such as C<Engine=INNOFB>.
-
-For an example of what you can do with this, see 
-L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
-
 =head2 resolve_join
 
 =over 4
@@ -1409,9 +1387,36 @@ should not be used.  It will be removed before 1.0.
 
 =cut
 
-=head2 sqlt_deploy_hook($sqlt_table)
+=head2 sqlt_deploy_hook
+
+=over 4
+
+=item Arguments: $source, $sqlt_table
 
-Triggers C<sqlt_deploy_callback>.
+=item Return value: undefined
+
+=back
+
+An optional sub which you can declare in your own Result class that will get 
+passed the L<SQL::Translator::Schema::Table> object when you deploy the schema
+via L</create_ddl_dir> or L</deploy>.
+
+This is useful to make L<SQL::Translator> create non-unique indexes, or set
+table options such as C<Engine=INNODB>. For an example of what you can do with
+this, see
+L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
+
+Note that sqlt_deploy_hook is called by 
+L<DBIx::Class::Schema/deployment_statements>, which in turn is called before
+L<DBIx::Class::Schema/deploy>. Therefore the hook can be used only to manipulate
+the L<SQL::Translator::Table> object before it is turned into SQL fed to the
+database. If you want to execute post-deploy statements which can not be generated
+by L<SQL::Translator>, the currently suggested method is to overload
+L<DBIx::Class::Storage/deploy> and use L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
+
+Starting from DBIC 0.08100 a simple hook is inherited by all result sources, which
+invokes the method or coderef specified in L</sqlt_deploy_callback>. You can still
+overload this method like in older DBIC versions without any compatibility issues.
 
 =cut
 
@@ -1422,6 +1427,14 @@ sub sqlt_deploy_hook {
   }
 }
 
+=head2 sqlt_deploy_callback
+
+An attribute which contains the callback to trigger on C<sqlt_deploy_hook>.
+Defaults to C<default_sqlt_deploy_hook>. Can be a code reference or the name
+of a method in a result class. You would change the default value in case you
+want to share a hook between several result sources, or if you want to use a
+result source without a declared result class.
+
 =head2 default_sqlt_deploy_hook($table)
 
 Delegates to a an optional C<sqlt_deploy_hook> method on the C<result_class>.
@@ -1444,11 +1457,6 @@ sub default_sqlt_deploy_hook {
   }
 }
 
-=head2 sqlt_deploy_callback
-
-An attribute which contains the callback to trigger on C<sqlt_deploy_hook>.
-Defaults to C<default_sqlt_deploy_hook>. Can be a code reference or a method
-name.
 
 =head1 AUTHORS
 
diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index e58fbf2..02c48de 100644
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -440,6 +440,13 @@ L</create_ddl_dir> or L</deploy>.
 For an example of what you can do with this, see 
 L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
 
+Note that sqlt_deploy_hook is called by L</deployment_statements>, which in turn
+is called before L</deploy>. Therefore the hook can be used only to manipulate
+the L<SQL::Translator::Schema> object before it is turned into SQL fed to the
+database. If you want to execute post-deploy statements which can not be generated
+by L<SQL::Translator>, the currently suggested method is to overload L</deploy>
+and use L<dbh_do|DBIx::Class::Storage::DBI/dbh_do>.
+
 =head1 METHODS
 
 =head2 connect