[Bast-commits] r5330 - in DBIx-Class/0.08/trunk/lib/DBIx/Class: . Manual

Wed Jan 21 13:51:21 GMT 2009

Author: ribasushi
Date: 2009-01-21 13:51:21 +0000 (Wed, 21 Jan 2009)
New Revision: 5330

Modified:
   DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Cookbook.pod
   DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSource.pm
   DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm
Log:
First stab at properly documenting the new sqlt_hook for resultsources

Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Cookbook.pod
===================================================================

--- DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Cookbook.pod	2009-01-20 23:39:24 UTC (rev 5329)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/Manual/Cookbook.pod	2009-01-21 13:51:21 UTC (rev 5330)
@@ -820,7 +820,7 @@
 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 @@
 
 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,10 +1203,12 @@
    $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
 
 The following example shows simplistically how you might use DBIx::Class to

Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSource.pm
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSource.pm	2009-01-20 23:39:24 UTC (rev 5329)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/ResultSource.pm	2009-01-21 13:51:21 UTC (rev 5330)
@@ -994,28 +994,6 @@
   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,10 +1387,37 @@
 
 =cut
 
-=head2 sqlt_deploy_hook($sqlt_table)
+=head2 sqlt_deploy_hook
 
-Triggers C<sqlt_deploy_callback>.
+=over 4
 
+=item Arguments: $source, $sqlt_table
+
+=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
 
 sub sqlt_deploy_hook {
@@ -1422,6 +1427,14 @@
   }
 }
 
+=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,12 +1457,7 @@
   }
 }
 
-=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
 
 Matt S. Trout <mst at shadowcatsystems.co.uk>

Modified: DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm
===================================================================
--- DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm	2009-01-20 23:39:24 UTC (rev 5329)
+++ DBIx-Class/0.08/trunk/lib/DBIx/Class/Schema.pm	2009-01-21 13:51:21 UTC (rev 5330)
@@ -440,6 +440,13 @@
 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


