From: Ash Berlin <ash_github@firemirror.com>
Date: Sat, 13 Oct 2007 12:33:33 +0000 (+0000)
Subject: Add docs about sqlt_deploy_hook, and reorganise/reorder the Cookbook
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=d2f3e87bbb670790a5572e1f7b92f33cc57585ab;p=dbsrgits%2FDBIx-Class-Historic.git

Add docs about sqlt_deploy_hook, and reorganise/reorder the Cookbook
---

diff --git a/lib/DBIx/Class/Manual/Cookbook.pod b/lib/DBIx/Class/Manual/Cookbook.pod
index 2fdb3ad..0552a03 100644
--- a/lib/DBIx/Class/Manual/Cookbook.pod
+++ b/lib/DBIx/Class/Manual/Cookbook.pod
@@ -2,11 +2,9 @@
 
 DBIx::Class::Manual::Cookbook - Miscellaneous recipes
 
-=head1 RECIPES
+=head1 SEARCHING
 
-=head2 Searching
-
-=head3 Paged results
+=head2 Paged results
 
 When you expect a large number of results, you can ask L<DBIx::Class> for a
 paged resultset, which will fetch only a defined number of records at a time:
@@ -37,7 +35,7 @@ resultset (suitable for use in e.g. a template) using the C<pager> method:
 
   return $rs->pager();
 
-=head3 Complex WHERE clauses
+=head2 Complex WHERE clauses
 
 Sometimes you need to formulate a query using specific operators:
 
@@ -70,7 +68,7 @@ This results in the following C<WHERE> clause:
 For more information on generating complex queries, see
 L<SQL::Abstract/WHERE CLAUSES>.
 
-=head3 Arbitrary SQL through a custom ResultSource
+=head2 Arbitrary SQL through a custom ResultSource
 
 Sometimes you have to run arbitrary SQL because your query is too complex
 (e.g. it contains Unions, Sub-Selects, Stored Procedures, etc.) or has to
@@ -120,7 +118,7 @@ Next, you can execute your complex query using bind parameters like this:
   
 ... and you'll get back a perfect L<DBIx::Class::ResultSet>.
 
-=head3 Using specific columns
+=head2 Using specific columns
 
 When you only want specific columns from a table, you can use
 C<columns> to specify which ones you need. This is useful to avoid
@@ -140,7 +138,7 @@ use anyway:
 This is a shortcut for C<select> and C<as>, see below. C<columns>
 cannot be used together with C<select> and C<as>.
 
-=head3 Using database functions or stored procedures
+=head2 Using database functions or stored procedures
 
 The combination of C<select> and C<as> can be used to return the result of a
 database function or stored procedure as a column value. You use C<select> to
@@ -184,7 +182,7 @@ any of your aliases using either of these:
   # Or use DBIx::Class::AccessorGroup:
   __PACKAGE__->mk_group_accessors('column' => 'name_length');
 
-=head3 SELECT DISTINCT with multiple columns
+=head2 SELECT DISTINCT with multiple columns
 
   my $rs = $schema->resultset('Foo')->search(
     {},
@@ -198,7 +196,7 @@ any of your aliases using either of these:
 
   my $count = $rs->next->get_column('count');
 
-=head3 SELECT COUNT(DISTINCT colname)
+=head2 SELECT COUNT(DISTINCT colname)
 
   my $rs = $schema->resultset('Foo')->search(
     {},
@@ -210,7 +208,7 @@ any of your aliases using either of these:
     }
   );
 
-=head3 Grouping results
+=head2 Grouping results
 
 L<DBIx::Class> supports C<GROUP BY> as follows:
 
@@ -233,7 +231,7 @@ Please see L<DBIx::Class::ResultSet/ATTRIBUTES> documentation if you
 are in any way unsure about the use of the attributes above (C< join
 >, C< select >, C< as > and C< group_by >).
 
-=head3 Predefined searches
+=head2 Predefined searches
 
 You can write your own L<DBIx::Class::ResultSet> class by inheriting from it
 and define often used searches as methods:
@@ -263,7 +261,7 @@ Then call your new method in your code:
 
    my $ordered_cds = $schema->resultset('CD')->search_cds_ordered();
 
-=head3 Using SQL functions on the left hand side of a comparison
+=head2 Using SQL functions on the left hand side of a comparison
 
 Using SQL functions on the left hand side of a comparison is generally
 not a good idea since it requires a scan of the entire table.  However,
@@ -294,6 +292,8 @@ C<bind> attributes:
 
 =end hidden
 
+=head1 JOINS AND PREFETCHING
+
 =head2 Using joins and prefetch
 
 You can use the C<join> attribute to allow searching on, or sorting your
@@ -392,7 +392,7 @@ Also note that C<prefetch> should only be used when you know you will
 definitely use data from a related table. Pre-fetching related tables when you
 only need columns from the main table will make performance worse!
 
-=head3 Multi-step joins
+=head2 Multi-step joins
 
 Sometimes you want to join more than one relationship deep. In this example,
 we want to find all C<Artist> objects who have C<CD>s whose C<LinerNotes>
@@ -473,7 +473,248 @@ SQL statements:
   my $tag = $rs->first;
   print $tag->cd->artist->name;
 
-=head2 Columns of data
+=head1 ROW-LEVEL OPERATIONS
+
+=head2 Retrieving a row object's Schema
+
+It is possible to get a Schema object from a row object like so:
+
+  my $schema = $cd->result_source->schema;
+  # use the schema as normal:
+  my $artist_rs = $schema->resultset('Artist'); 
+
+This can be useful when you don't want to pass around a Schema object to every
+method.
+
+=head2 Getting the value of the primary key for the last database insert
+
+AKA getting last_insert_id
+
+If you are using PK::Auto (which is a core component as of 0.07), this is 
+straightforward:
+
+  my $foo = $rs->create(\%blah);
+  # do more stuff
+  my $id = $foo->id; # foo->my_primary_key_field will also work.
+
+If you are not using autoincrementing primary keys, this will probably
+not work, but then you already know the value of the last primary key anyway.
+
+=head2 Stringification
+
+Employ the standard stringification technique by using the C<overload>
+module.
+
+To make an object stringify itself as a single column, use something
+like this (replace C<foo> with the column/method of your choice):
+
+  use overload '""' => sub { shift->name}, fallback => 1;
+
+For more complex stringification, you can use an anonymous subroutine:
+
+  use overload '""' => sub { $_[0]->name . ", " .
+                             $_[0]->address }, fallback => 1;
+
+=head3 Stringification Example
+
+Suppose we have two tables: C<Product> and C<Category>. The table
+specifications are:
+
+  Product(id, Description, category)
+  Category(id, Description)
+
+C<category> is a foreign key into the Category table.
+
+If you have a Product object C<$obj> and write something like
+
+  print $obj->category
+
+things will not work as expected.
+
+To obtain, for example, the category description, you should add this
+method to the class defining the Category table:
+
+  use overload "" => sub {
+      my $self = shift;
+
+      return $self->Description;
+  }, fallback => 1;
+
+=head2 Want to know if find_or_create found or created a row?
+
+Just use C<find_or_new> instead, then check C<in_storage>:
+
+  my $obj = $rs->find_or_new({ blah => 'blarg' });
+  unless ($obj->in_storage) {
+    $obj->insert;
+    # do whatever else you wanted if it was a new row
+  }
+
+=head2 Dynamic Sub-classing DBIx::Class proxy classes 
+
+AKA multi-class object inflation from one table
+ 
+L<DBIx::Class> classes are proxy classes, therefore some different
+techniques need to be employed for more than basic subclassing.  In
+this example we have a single user table that carries a boolean bit
+for admin.  We would like like to give the admin users
+objects(L<DBIx::Class::Row>) the same methods as a regular user but
+also special admin only methods.  It doesn't make sense to create two
+seperate proxy-class files for this.  We would be copying all the user
+methods into the Admin class.  There is a cleaner way to accomplish
+this.
+
+Overriding the C<inflate_result> method within the User proxy-class
+gives us the effect we want.  This method is called by
+L<DBIx::Class::ResultSet> when inflating a result from storage.  So we
+grab the object being returned, inspect the values we are looking for,
+bless it if it's an admin object, and then return it.  See the example
+below:
+ 
+B<Schema Definition> 
+ 
+    package DB::Schema; 
+     
+    use base qw/DBIx::Class::Schema/; 
+ 
+    __PACKAGE__->load_classes(qw/User/); 
+ 
+ 
+B<Proxy-Class definitions> 
+ 
+    package DB::Schema::User; 
+     
+    use strict; 
+    use warnings; 
+    use base qw/DBIx::Class/; 
+     
+    ### Defined what our admin class is for ensure_class_loaded 
+    my $admin_class = __PACKAGE__ . '::Admin'; 
+     
+    __PACKAGE__->load_components(qw/Core/); 
+     
+    __PACKAGE__->table('users'); 
+     
+    __PACKAGE__->add_columns(qw/user_id   email    password  
+                                firstname lastname active 
+                                admin/); 
+     
+    __PACKAGE__->set_primary_key('user_id'); 
+     
+    sub inflate_result { 
+        my $self = shift;  
+        my $ret = $self->next::method(@_); 
+        if( $ret->admin ) {### If this is an admin rebless for extra functions  
+            $self->ensure_class_loaded( $admin_class ); 
+            bless $ret, $admin_class; 
+        } 
+        return $ret; 
+    } 
+     
+    sub hello { 
+        print "I am a regular user.\n"; 
+        return ; 
+    } 
+     
+     
+    package DB::Schema::User::Admin; 
+     
+    use strict; 
+    use warnings; 
+    use base qw/DB::Schema::User/; 
+     
+    sub hello 
+    { 
+        print "I am an admin.\n"; 
+        return; 
+    } 
+     
+    sub do_admin_stuff 
+    { 
+        print "I am doing admin stuff\n"; 
+        return ; 
+    } 
+ 
+B<Test File> test.pl 
+ 
+    use warnings; 
+    use strict; 
+    use DB::Schema; 
+     
+    my $user_data = { email    => 'someguy@place.com',  
+                      password => 'pass1',  
+                      admin    => 0 }; 
+                           
+    my $admin_data = { email    => 'someadmin@adminplace.com',  
+                       password => 'pass2',  
+                       admin    => 1 }; 
+                           
+    my $schema = DB::Schema->connection('dbi:Pg:dbname=test'); 
+     
+    $schema->resultset('User')->create( $user_data ); 
+    $schema->resultset('User')->create( $admin_data ); 
+     
+    ### Now we search for them 
+    my $user = $schema->resultset('User')->single( $user_data ); 
+    my $admin = $schema->resultset('User')->single( $admin_data ); 
+     
+    print ref $user, "\n"; 
+    print ref $admin, "\n"; 
+     
+    print $user->password , "\n"; # pass1 
+    print $admin->password , "\n";# pass2; inherited from User 
+    print $user->hello , "\n";# I am a regular user. 
+    print $admin->hello, "\n";# I am an admin. 
+ 
+    ### The statement below will NOT print 
+    print "I can do admin stuff\n" if $user->can('do_admin_stuff'); 
+    ### The statement below will print 
+    print "I can do admin stuff\n" if $admin->can('do_admin_stuff'); 
+
+=head2 Skip object creation for faster results
+
+DBIx::Class is not built for speed, it's built for convenience and
+ease of use, but sometimes you just need to get the data, and skip the
+fancy objects.
+  
+To do this simply use L<DBIx::Class::ResultClass::HashRefInflator>.
+  
+ my $rs = $schema->resultset('CD');
+ 
+ $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
+ 
+ my $hash_ref = $rs->find(1);
+  
+Wasn't that easy?
+  
+=head2 Get raw data for blindingly fast results
+
+If the L<HashRefInflator|DBIx::Class::ResultClass::HashRefInflator> solution
+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:-
+
+  my $cursor = $rs->cursor
+  while (my @vals = $cursor->next) {
+      # use $val[0..n] here
+  }
+
+You will need to map the array offsets to particular columns (you can
+use the I<select> attribute of C<search()> to force ordering).
+
+=head1 RESULTSET OPERATIONS
+
+=head2 Getting Schema from a ResultSet
+
+To get the schema object from a result set, do the following:
+
+ $rs->result_source->schema
+
+=head2 Getting Columns Of Data
+
+AKA Aggregating Data
 
 If you want to find the sum of a particular column there are several
 ways, the obvious one is to use search:
@@ -522,25 +763,25 @@ This will cause the following SQL statement to be run:
 Which will of course only work if your database supports this function.
 See L<DBIx::Class::ResultSetColumn> for more documentation.
 
-=head2 Using relationships
+=head1 USING RELATIONSHIPS
 
-=head3 Create a new row in a related table
+=head2 Create a new row in a related table
 
   my $book->create_related('author', { name => 'Fred'});
 
-=head3 Search in a related table
+=head2 Search in a related table
 
 Only searches for books named 'Titanic' by the author in $author.
 
   my $author->search_related('books', { name => 'Titanic' });
 
-=head3 Delete data in a related table
+=head2 Delete data in a related table
 
 Deletes only the book named Titanic by the author in $author.
 
   my $author->delete_related('books', { name => 'Titanic' });
 
-=head3 Ordering a relationship result set
+=head2 Ordering a relationship result set
 
 If you always want a relation to be ordered, you can specify this when you 
 create the relationship.
@@ -549,20 +790,52 @@ To order C<< $book->pages >> by descending page_number.
 
   Book->has_many('pages' => 'Page', 'book', { order_by => \'page_number DESC'} );
 
+=head2 Many-to-many relationships
 
+This is straightforward using L<ManyToMany|DBIx::Class::Relationship/many_to_many>:
 
-=head2 Transactions
+  package My::DB;
+  # ... set up connection ...
 
-As of version 0.04001, there is improved transaction support in
-L<DBIx::Class::Storage> and L<DBIx::Class::Schema>.  Here is an
-example of the recommended way to use it:
+  package My::User;
+  use base 'My::DB';
+  __PACKAGE__->table('user');
+  __PACKAGE__->add_columns(qw/id name/);
+  __PACKAGE__->set_primary_key('id');
+  __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'user');
+  __PACKAGE__->many_to_many('addresses' => 'user_address', 'address');
 
-  my $genus = $schema->resultset('Genus')->find(12);
+  package My::UserAddress;
+  use base 'My::DB';
+  __PACKAGE__->table('user_address');
+  __PACKAGE__->add_columns(qw/user address/);
+  __PACKAGE__->set_primary_key(qw/user address/);
+  __PACKAGE__->belongs_to('user' => 'My::User');
+  __PACKAGE__->belongs_to('address' => 'My::Address');
 
-  my $coderef2 = sub {
-    $genus->extinct(1);
-    $genus->update;
-  };
+  package My::Address;
+  use base 'My::DB';
+  __PACKAGE__->table('address');
+  __PACKAGE__->add_columns(qw/id street town area_code country/);
+  __PACKAGE__->set_primary_key('id');
+  __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'address');
+  __PACKAGE__->many_to_many('users' => 'user_address', 'user');
+
+  $rs = $user->addresses(); # get all addresses for a user
+  $rs = $address->users(); # get all users for an address
+
+=head1 TRANSACTIONS
+
+As of version 0.04001, there is improved transaction support in
+L<DBIx::Class::Storage> and L<DBIx::Class::Schema>.  Here is an
+example of the recommended way to use it:
+
+  my $genus = $schema->resultset('Genus')->find(12);
+
+  my $coderef2 = sub {
+    $genus->extinct(1);
+    $genus->update;
+  };
 
   my $coderef1 = sub {
     $genus->add_to_species({ name => 'troglodyte' });
@@ -591,118 +864,22 @@ transaction to fail. Support for savepoints and for true nested
 transactions (for databases that support them) will hopefully be added
 in the future.
 
-=head2 Many-to-many relationships
+=head1 SQL 
 
-This is straightforward using L<ManyToMany|DBIx::Class::Relationship/many_to_many>:
+=head2 Creating Schemas From An Existing Database
 
-  package My::DB;
-  # ... set up connection ...
+L<DBIx::Class::Schema::Loader> will connect to a database and create a 
+L<DBIx::Class::Schema> and associated sources by examining the database.
 
-  package My::User;
-  use base 'My::DB';
-  __PACKAGE__->table('user');
-  __PACKAGE__->add_columns(qw/id name/);
-  __PACKAGE__->set_primary_key('id');
-  __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'user');
-  __PACKAGE__->many_to_many('addresses' => 'user_address', 'address');
-
-  package My::UserAddress;
-  use base 'My::DB';
-  __PACKAGE__->table('user_address');
-  __PACKAGE__->add_columns(qw/user address/);
-  __PACKAGE__->set_primary_key(qw/user address/);
-  __PACKAGE__->belongs_to('user' => 'My::User');
-  __PACKAGE__->belongs_to('address' => 'My::Address');
+The recommend way of achieving this is to use the 
+L<make_schema_at|DBIx::Class::Schema::Loader/make_schema_at> method:
 
-  package My::Address;
-  use base 'My::DB';
-  __PACKAGE__->table('address');
-  __PACKAGE__->add_columns(qw/id street town area_code country/);
-  __PACKAGE__->set_primary_key('id');
-  __PACKAGE__->has_many('user_address' => 'My::UserAddress', 'address');
-  __PACKAGE__->many_to_many('users' => 'user_address', 'user');
-
-  $rs = $user->addresses(); # get all addresses for a user
-  $rs = $address->users(); # get all users for an address
-
-=head2 Setting default values for a row
-
-It's as simple as overriding the C<new> method.  Note the use of
-C<next::method>.
-
-  sub new {
-    my ( $class, $attrs ) = @_;
-
-    $attrs->{foo} = 'bar' unless defined $attrs->{foo};
-
-    my $new = $class->next::method($attrs);
-
-    return $new;
-  }
-
-For more information about C<next::method>, look in the L<Class::C3> 
-documentation. See also L<DBIx::Class::Manual::Component> for more
-ways to write your own base classes to do this.
-
-People looking for ways to do "triggers" with DBIx::Class are probably
-just looking for this. 
-
-=head2 Stringification
-
-Employ the standard stringification technique by using the C<overload>
-module.
-
-To make an object stringify itself as a single column, use something
-like this (replace C<foo> with the column/method of your choice):
-
-  use overload '""' => sub { shift->name}, fallback => 1;
-
-For more complex stringification, you can use an anonymous subroutine:
-
-  use overload '""' => sub { $_[0]->name . ", " .
-                             $_[0]->address }, fallback => 1;
-
-=head3 Stringification Example
-
-Suppose we have two tables: C<Product> and C<Category>. The table
-specifications are:
-
-  Product(id, Description, category)
-  Category(id, Description)
-
-C<category> is a foreign key into the Category table.
-
-If you have a Product object C<$obj> and write something like
-
-  print $obj->category
-
-things will not work as expected.
-
-To obtain, for example, the category description, you should add this
-method to the class defining the Category table:
-
-  use overload "" => sub {
-      my $self = shift;
-
-      return $self->Description;
-  }, fallback => 1;
-
-=head2 Disconnecting cleanly
-
-If you find yourself quitting an app with Control-C a lot during
-development, you might like to put the following signal handler in
-your main database class to make sure it disconnects cleanly:
-
-  $SIG{INT} = sub {
-    __PACKAGE__->storage->disconnect;
-  };
-
-=head2 Schema import/export
+  perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("My::Schema", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])'
 
-To create a DBIx::Class schema from an existing database, use
-L<DBIx::Class::Schema::Loader>'s C<make_schema_at>:
+This will create a tree of files rooted at C<./lib/My/Schema/> containing
+source definitions for all the tables found in the C<foo> database.
 
-  perl -MDBIx::Class::Schema::Loader=make_schema_at,dump_to_dir:./lib -e 'make_schema_at("My::Schema", { debug => 1 }, [ "dbi:Pg:dbname=foo","postgres" ])'
+=head2 Creating DDL SQL
 
 The following functionality requires you to have L<SQL::Translator>
 (also known as "SQL Fairy") installed.
@@ -712,7 +889,7 @@ To create a set of database-specific .sql files for the above schema:
  my $schema = My::Schema->connect($dsn);
  $schema->create_ddl_dir(['MySQL', 'SQLite', 'PostgreSQL'],
                         '0.1',
-                        '/dbscriptdir/'
+                        './dbscriptdir/'
                         );
 
 By default this will create schema files in the current directory, for
@@ -729,7 +906,7 @@ To import created .sql files using the mysql client:
 
 To create C<ALTER TABLE> conversion scripts to update a database to a
 newer version of your schema at a later point, first set a new
-$VERSION in your Schema file, then:
+C<$VERSION> in your Schema file, then:
 
  my $schema = My::Schema->connect($dsn);
  $schema->create_ddl_dir(['MySQL', 'SQLite', 'PostgreSQL'],
@@ -743,44 +920,47 @@ of the schema, plus scripts to convert from version 0.1 to 0.2. This
 requires that the files for 0.1 as created above are available in the
 given directory to diff against.
 
+=head2 Adding Indexes And Functions To Your SQL
 
-=head2 Easy migration from class-based to schema-based setup
+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:
 
-You want to start using the schema-based approach to L<DBIx::Class>
-(see L<SchemaIntro.pod>), but have an established class-based setup with lots
-of existing classes that you don't want to move by hand. Try this nifty script
-instead:
+ package My::Schema::Artist;
 
-  use MyDB;
-  use SQL::Translator;
-  
-  my $schema = MyDB->schema_instance;
-  
-  my $translator           =  SQL::Translator->new( 
-      debug                => $debug          ||  0,
-      trace                => $trace          ||  0,
-      no_comments          => $no_comments    ||  0,
-      show_warnings        => $show_warnings  ||  0,
-      add_drop_table       => $add_drop_table ||  0,
-      validate             => $validate       ||  0,
-      parser_args          => {
-         'DBIx::Schema'    => $schema,
-                              },
-      producer_args   => {
-          'prefix'         => 'My::Schema',
-                         },
-  );
-  
-  $translator->parser('SQL::Translator::Parser::DBIx::Class');
-  $translator->producer('SQL::Translator::Producer::DBIx::Class::File');
-  
-  my $output = $translator->translate(@args) or die
-          "Error: " . $translator->error;
-  
-  print $output;
+ __PACKAGE__->table('artist');
+ __PACKAGE__->add_columns(id => { ... }, name => { ... })
 
-You could use L<Module::Find> to search for all subclasses in the MyDB::*
-namespace, which is currently left as an exercise for the reader.
+ sub sqlt_deploy_hook {
+   my ($self, $sqlt_table) = @_;
+
+   $sqlt_table->add_index(name => 'idx_name', fields => ['name']);
+ }
+
+ 1;
+
+Sometimes you might want to change the index depending on the type of the 
+database for which SQL is being generated:
+
+  my ($db_type = $sqlt_table->schema->translator->producer_type)
+    =~ s/^SQL::Translator::Producer:://;
+
+You can also add hooks to the schema level to stop certain tables being 
+created:
+
+ package My::Schema;
+
+ ...
+
+ sub sqlt_deploy_hook {
+   my ($self, $sqlt_schema) = @_;
+
+   $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>.
 
 =head2 Schema versioning
 
@@ -811,17 +991,16 @@ Deploy update to customers
 
 =back
 
-=head3 Create a DBIx::Class schema
+B<Create a DBIx::Class schema>
 
 This can either be done manually, or generated from an existing database as
-described under C<Schema import/export>.
+described under L</Creating Schemas From An Existing Database>
 
-=head3 Save the schema
+B<Save the schema>
 
-Call L<DBIx::Class::Schema/create_ddl_dir> as above under L<Schema
-import/export>.
+Call L<DBIx::Class::Schema/create_ddl_dir> as above under L</Creating DDL SQL>.
 
-=head3 Deploy to customers
+B<Deploy to customers>
 
 There are several ways you could deploy your schema. These are probably
 beyond the scope of this recipe, but might include:
@@ -839,14 +1018,14 @@ all part of your install.
 
 =back
 
-=head3 Modify the schema to change functionality
+B<Modify the schema to change functionality>
 
 As your application evolves, it may be necessary to modify your schema
 to change functionality. Once the changes are made to your schema in
 DBIx::Class, export the modified schema and the conversion scripts as
-in L<Schema import/export>.
+in L</Creating DDL SQL>.
 
-=head3 Deploy update to customers
+B<Deploy update to customers>
 
 Add the L<DBIx::Class::Schema::Versioned> schema component to your
 Schema class. This will add a new table to your database called
@@ -857,6 +1036,36 @@ database thinks it has.
 Alternatively, you can send the conversion sql scripts to your
 customers as above.
 
+=head2 Setting quoting for the generated SQL. 
+
+If the database contains column names with spaces and/or reserved words, they
+need to be quoted in the SQL queries. This is done using:
+
+ __PACKAGE__->storage->sql_maker->quote_char([ qw/[ ]/] );
+ __PACKAGE__->storage->sql_maker->name_sep('.');
+
+The first sets the quote characters. Either a pair of matching
+brackets, or a C<"> or C<'>:
+  
+ __PACKAGE__->storage->sql_maker->quote_char('"');
+
+Check the documentation of your database for the correct quote
+characters to use. C<name_sep> needs to be set to allow the SQL
+generator to put the quotes the correct place.
+
+In most cases you should set these as part of the arguments passed to 
+L<DBIx::Class::Schema/conect>:
+
+ my $schema = My::Schema->connect(
+  'dbi:mysql:my_db',
+  'db_user',
+  'db_password',
+  {
+    quote_char => '"',
+    name_sep   => '.'
+  }
+ )
+
 =head2 Setting limit dialect for SQL::Abstract::Limit
 
 In some cases, SQL::Abstract::Limit cannot determine the dialect of
@@ -872,24 +1081,50 @@ to Microsoft SQL-server (See more names in SQL::Abstract::Limit
 The JDBC bridge is one way of getting access to a MSSQL server from a platform
 that Microsoft doesn't deliver native client libraries for. (e.g. Linux)
 
-=head2 Setting quoting for the generated SQL. 
+The limit dialect can also be set at connect time by specifying a 
+C<limit_dialect> key in the final hash as shown above.
 
-If the database contains column names with spaces and/or reserved words, they
-need to be quoted in the SQL queries. This is done using:
+=head1 BOOTSTRAPPING/MIGRATING 
 
-  __PACKAGE__->storage->sql_maker->quote_char([ qw/[ ]/] );
-  __PACKAGE__->storage->sql_maker->name_sep('.');
+=head2 Easy migration from class-based to schema-based setup
 
-The first sets the quote characters. Either a pair of matching
-brackets, or a C<"> or C<'>:
+You want to start using the schema-based approach to L<DBIx::Class>
+(see L<SchemaIntro.pod>), but have an established class-based setup with lots
+of existing classes that you don't want to move by hand. Try this nifty script
+instead:
+
+  use MyDB;
+  use SQL::Translator;
+  
+  my $schema = MyDB->schema_instance;
   
-  __PACKAGE__->storage->sql_maker->quote_char('"');
+  my $translator           =  SQL::Translator->new( 
+      debug                => $debug          ||  0,
+      trace                => $trace          ||  0,
+      no_comments          => $no_comments    ||  0,
+      show_warnings        => $show_warnings  ||  0,
+      add_drop_table       => $add_drop_table ||  0,
+      validate             => $validate       ||  0,
+      parser_args          => {
+         'DBIx::Schema'    => $schema,
+                              },
+      producer_args   => {
+          'prefix'         => 'My::Schema',
+                         },
+  );
+  
+  $translator->parser('SQL::Translator::Parser::DBIx::Class');
+  $translator->producer('SQL::Translator::Producer::DBIx::Class::File');
+  
+  my $output = $translator->translate(@args) or die
+          "Error: " . $translator->error;
+  
+  print $output;
 
-Check the documentation of your database for the correct quote
-characters to use. C<name_sep> needs to be set to allow the SQL
-generator to put the quotes the correct place.
+You could use L<Module::Find> to search for all subclasses in the MyDB::*
+namespace, which is currently left as an exercise for the reader.
 
-=head2 Overloading methods
+=head1 OVERLOADING METHODS
 
 L<DBIx::Class> uses the L<Class::C3> package, which provides for redispatch of
 method calls, useful for things like default values and triggers. You have to
@@ -897,7 +1132,29 @@ use calls to C<next::method> to overload methods. More information on using
 L<Class::C3> with L<DBIx::Class> can be found in
 L<DBIx::Class::Manual::Component>.
 
-=head3 Changing one field whenever another changes
+=head2 Setting default values for a row
+
+It's as simple as overriding the C<new> method.  Note the use of
+C<next::method>.
+
+  sub new {
+    my ( $class, $attrs ) = @_;
+
+    $attrs->{foo} = 'bar' unless defined $attrs->{foo};
+
+    my $new = $class->next::method($attrs);
+
+    return $new;
+  }
+
+For more information about C<next::method>, look in the L<Class::C3> 
+documentation. See also L<DBIx::Class::Manual::Component> for more
+ways to write your own base classes to do this.
+
+People looking for ways to do "triggers" with DBIx::Class are probably
+just looking for this. 
+
+=head2 Changing one field whenever another changes
 
 For example, say that you have three columns, C<id>, C<number>, and 
 C<squared>.  You would like to make changes to C<number> and have
@@ -915,7 +1172,7 @@ You can accomplish this by overriding C<store_column>:
 Note that the hard work is done by the call to C<next::method>, which
 redispatches your call to store_column in the superclass(es).
 
-=head3 Automatically creating related objects
+=head2 Automatically creating related objects
 
 You might have a class C<Artist> which has many C<CD>s.  Further, if you
 want to create a C<CD> object every time you insert an C<Artist> object.
@@ -931,7 +1188,50 @@ You can accomplish this by overriding C<insert> on your objects:
 where C<fill_from_artist> is a method you specify in C<CD> which sets
 values in C<CD> based on the data in the C<Artist> object you pass in.
 
-=head2 Debugging DBIx::Class objects with Data::Dumper
+=head2 Wrapping/overloading a column accessor
+
+B<Problem:>
+
+Say you have a table "Camera" and want to associate a description
+with each camera. For most cameras, you'll be able to generate the description from
+the other columns. However, in a few special cases you may want to associate a
+custom description with a camera.
+
+B<Solution:>
+
+In your database schema, define a description field in the "Camera" table that
+can contain text and null values.
+
+In DBIC, we'll overload the column accessor to provide a sane default if no
+custom description is defined. The accessor will either return or generate the
+description, depending on whether the field is null or not.
+
+First, in your "Camera" schema class, define the description field as follows:
+
+  __PACKAGE__->add_columns(description => { accessor => '_description' });
+
+Next, we'll define the accessor-wrapper subroutine:
+
+  sub description {
+      my $self = shift;
+
+      # If there is an update to the column, we'll let the original accessor
+      # deal with it.
+      return $self->_description(@_) if @_;
+
+      # Fetch the column value.
+      my $description = $self->_description;
+
+      # If there's something in the description field, then just return that.
+      return $description if defined $description && length $descripton;
+
+      # Otherwise, generate a description.
+      return $self->generate_description;
+  }
+
+=head1 DEBUGGING AND PROFILING
+
+=head2 DBIx::Class objects with Data::Dumper
 
 L<Data::Dumper> can be a very useful tool for debugging, but sometimes it can
 be hard to find the pertinent data in all the data it can generate.
@@ -975,17 +1275,6 @@ base class and set C<$Data::Dumper::Freezer> to its name and L<Data::Dumper>
 will automagically clean up your data before printing it. See
 L<Data::Dumper/EXAMPLES> for more information.
 
-=head2 Retrieving a row object's Schema
-
-It is possible to get a Schema object from a row object like so:
-
-  my $schema = $cd->result_source->schema;
-  # use the schema as normal:
-  my $artist_rs = $schema->resultset('Artist'); 
-
-This can be useful when you don't want to pass around a Schema object to every
-method.
-
 =head2 Profiling
 
 When you enable L<DBIx::Class::Storage>'s debugging it prints the SQL
@@ -1048,218 +1337,5 @@ You could then create average, high and low execution times for an SQL
 statement and dig down to see if certain parameters cause aberrant behavior.
 You might want to check out L<DBIx::Class::QueryLog> as well.
 
-=head2 Getting the value of the primary key for the last database insert
-
-AKA getting last_insert_id
-
-If you are using PK::Auto, this is straightforward:
-
-  my $foo = $rs->create(\%blah);
-  # do more stuff
-  my $id = $foo->id; # foo->my_primary_key_field will also work.
-
-If you are not using autoincrementing primary keys, this will probably
-not work, but then you already know the value of the last primary key anyway.
-
-=head2 Dynamic Sub-classing DBIx::Class proxy classes 
-(AKA multi-class object inflation from one table) 
- 
-L<DBIx::Class> classes are proxy classes, therefore some different
-techniques need to be employed for more than basic subclassing.  In
-this example we have a single user table that carries a boolean bit
-for admin.  We would like like to give the admin users
-objects(L<DBIx::Class::Row>) the same methods as a regular user but
-also special admin only methods.  It doesn't make sense to create two
-seperate proxy-class files for this.  We would be copying all the user
-methods into the Admin class.  There is a cleaner way to accomplish
-this.
-
-Overriding the C<inflate_result> method within the User proxy-class
-gives us the effect we want.  This method is called by
-L<DBIx::Class::ResultSet> when inflating a result from storage.  So we
-grab the object being returned, inspect the values we are looking for,
-bless it if it's an admin object, and then return it.  See the example
-below:
- 
-B<Schema Definition> 
- 
-    package DB::Schema; 
-     
-    use base qw/DBIx::Class::Schema/; 
- 
-    __PACKAGE__->load_classes(qw/User/); 
- 
- 
-B<Proxy-Class definitions> 
- 
-    package DB::Schema::User; 
-     
-    use strict; 
-    use warnings; 
-    use base qw/DBIx::Class/; 
-     
-    ### Defined what our admin class is for ensure_class_loaded 
-    my $admin_class = __PACKAGE__ . '::Admin'; 
-     
-    __PACKAGE__->load_components(qw/Core/); 
-     
-    __PACKAGE__->table('users'); 
-     
-    __PACKAGE__->add_columns(qw/user_id   email    password  
-                                firstname lastname active 
-                                admin/); 
-     
-    __PACKAGE__->set_primary_key('user_id'); 
-     
-    sub inflate_result { 
-        my $self = shift;  
-        my $ret = $self->next::method(@_); 
-        if( $ret->admin ) {### If this is an admin rebless for extra functions  
-            $self->ensure_class_loaded( $admin_class ); 
-            bless $ret, $admin_class; 
-        } 
-        return $ret; 
-    } 
-     
-    sub hello { 
-        print "I am a regular user.\n"; 
-        return ; 
-    } 
-     
-     
-    package DB::Schema::User::Admin; 
-     
-    use strict; 
-    use warnings; 
-    use base qw/DB::Schema::User/; 
-     
-    sub hello 
-    { 
-        print "I am an admin.\n"; 
-        return; 
-    } 
-     
-    sub do_admin_stuff 
-    { 
-        print "I am doing admin stuff\n"; 
-        return ; 
-    } 
- 
-B<Test File> test.pl 
- 
-    use warnings; 
-    use strict; 
-    use DB::Schema; 
-     
-    my $user_data = { email    => 'someguy@place.com',  
-                      password => 'pass1',  
-                      admin    => 0 }; 
-                           
-    my $admin_data = { email    => 'someadmin@adminplace.com',  
-                       password => 'pass2',  
-                       admin    => 1 }; 
-                           
-    my $schema = DB::Schema->connection('dbi:Pg:dbname=test'); 
-     
-    $schema->resultset('User')->create( $user_data ); 
-    $schema->resultset('User')->create( $admin_data ); 
-     
-    ### Now we search for them 
-    my $user = $schema->resultset('User')->single( $user_data ); 
-    my $admin = $schema->resultset('User')->single( $admin_data ); 
-     
-    print ref $user, "\n"; 
-    print ref $admin, "\n"; 
-     
-    print $user->password , "\n"; # pass1 
-    print $admin->password , "\n";# pass2; inherited from User 
-    print $user->hello , "\n";# I am a regular user. 
-    print $admin->hello, "\n";# I am an admin. 
- 
-    ### The statement below will NOT print 
-    print "I can do admin stuff\n" if $user->can('do_admin_stuff'); 
-    ### The statement below will print 
-    print "I can do admin stuff\n" if $admin->can('do_admin_stuff'); 
-
-=head2 Skip object creation for faster results
-
-DBIx::Class is not built for speed, it's built for convenience and
-ease of use, but sometimes you just need to get the data, and skip the
-fancy objects.
-  
-To do this simply use L<DBIx::Class::ResultClass::HashRefInflator>.
-  
- my $rs = $schema->resultset('CD');
- 
- $rs->result_class('DBIx::Class::ResultClass::HashRefInflator');
- 
- my $hash_ref = $rs->find(1);
-  
-Wasn't that easy?
-  
-=head2 Get raw data for blindingly fast results
-
-If the C<inflate_result> solution 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:-
-
-  my $cursor = $rs->cursor
-  while (my @vals = $cursor->next) {
-      # use $val[0..n] here
-  }
-
-You will need to map the array offsets to particular columns (you can
-use the I<select> attribute of C<search()> to force ordering).
-
-=head2 Want to know if find_or_create found or created a row?
-
-Just use C<find_or_new> instead, then check C<in_storage>:
-
-  my $obj = $rs->find_or_new({ blah => 'blarg' });
-  unless ($obj->in_storage) {
-    $obj->insert;
-    # do whatever else you wanted if it was a new row
-  }
-
-=head3 Wrapping/overloading a column accessor
-
-Problem: Say you have a table "Camera" and want to associate a description
-with each camera. For most cameras, you'll be able to generate the description from
-the other columns. However, in a few special cases you may want to associate a
-custom description with a camera.
-
-Solution:
-
-In your database schema, define a description field in the "Camera" table that
-can contain text and null values.
-
-In DBIC, we'll overload the column accessor to provide a sane default if no
-custom description is defined. The accessor will either return or generate the
-description, depending on whether the field is null or not.
-
-First, in your "Camera" schema class, define the description field as follows:
-
-  __PACKAGE__->add_columns(description => { accessor => '_description' });
-
-Next, we'll define the accessor-wrapper subroutine:
-
-  sub description {
-      my $self = shift;
-
-      # If there is an update to the column, we'll let the original accessor
-      # deal with it.
-      return $self->_description(@_) if @_;
-
-      # Fetch the column value.
-      my $description = $self->_description;
-
-      # If there's something in the description field, then just return that.
-      return $description if defined $description && length $descripton;
-
-      # Otherwise, generate a description.
-      return $self->generate_description;
-  }
 
 =cut
diff --git a/lib/DBIx/Class/ResultSource.pm b/lib/DBIx/Class/ResultSource.pm
index 4efa0d7..d23c765 100644
--- a/lib/DBIx/Class/ResultSource.pm
+++ b/lib/DBIx/Class/ResultSource.pm
@@ -1057,6 +1057,15 @@ sub throw_exception {
   }
 }
 
+=head2 sqlt_deploy_hook($sqlt_table)
+
+An optional sub which you can declare in your own Schema 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>.
+
+For an example of what you can do with this, see 
+L<DBIx::Class::Manual::Cookbook/Adding Indexes And Functions To Your SQL>.
+
 =head1 AUTHORS
 
 Matt S. Trout <mst@shadowcatsystems.co.uk>
diff --git a/lib/DBIx/Class/Schema.pm b/lib/DBIx/Class/Schema.pm
index 79988b8..b668c83 100644
--- a/lib/DBIx/Class/Schema.pm
+++ b/lib/DBIx/Class/Schema.pm
@@ -1050,6 +1050,17 @@ sub ddl_filename {
     return $filename;
 }
 
+=head2 sqlt_deploy_hook($sqlt_schema)
+
+An optional sub which you can declare in your own Schema class that will get 
+passed the L<SQL::Translator::Schema> object when you deploy the schema via
+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>.
+
+=cut
+
 1;
 
 =head1 AUTHORS