=head1 NAME

Catalyst::Plugin::AutoCRUD::Manual::DBICTips - Tips for DBIx::Class Users

=head1 General Advice

If you created your C<DBIx::Class> Schema some time ago, perhaps using an
older version of C<DBIx::Class::Schema::Loader>, then it might well be lacking
some configuration which is required to get the best results from this plugin.

Common omissions in column configurations include C<is_foreign_key>,
C<join_type>, C<is_nullable>, and C<is_auto_increment>. Of course it's also
good practice to have your C<DBIx::Class> Schema closely reflect the database
schema anyway.

To automatically bring things up to date, download the latest version of
L<DBIx::Class::Schema::Loader> from CPAN, and use the output from that.

=head1 Foreign keys should be configured with C<is_foreign_key>

Any column in your result classes which contains the primary key of another
table should have the C<< is_foreign_key => 1 >> option added to its
configuration.

If using C<DBIx::Class::Schema::Loader> to generate your Schema, use at least
version 0.05 or the most recent release from CPAN to have this automatically
configured for you.

=head1 Make sure C<belongs_to> follows C<add_columns>

Whenver you use C<belongs_to()> in a result class, it B<must> come after any
calls to C<add_column()> which affect the foreign key. A situation where this
may not be the case is if you add additional column options in a second call
to C<add_column()>, after the C<DO NOT MODIFY THIS OR ANYTHING ABOVE> line.

If you do not follow this guideline, then you won't see any related data in 
the views generated by this plugin. Furthermore, you'll be losing much of
the advantage of C<DBIx::Class>.

A better solution is to re-generate your result class using a recent version
of C<DBIx::Class::Schema::Loader> from the CPAN (which may be 0.05 or later).

=head1 Optional C<belongs_to> relations must have a C<join_type>

If you have any C<belongs_to> type relations where the column containing the
foreign key can be NULL, it's I<strongly recommended> that you add a
C<join_type> parameter to the end of the relevant options to C<add_columns()>,
like so:

 # in a Book class, the book optionally has an Owner
 __PACKAGE__->belongs_to(
     'my_owner',                      # accessor name
     'My::DBIC::Schema::Owner',       # related class
     'owner_id',                      # our FK column (or join condition)
     { join_type => 'LEFT OUTER' }    # attributes
 );

If you don't do this, some database records will be missing! The technical
reason for this, if you are interested, is that C<DBIx::Class> defaults to an
INNER join for the C<belongs_to()> relation, but if the column can be null
(that is, C<is_nullable>) then you most likely want a LEFT OUTER join.

If using C<DBIx::Class::Schema::Loader> to generate your Schema, use at least
version 0.05 or the most recent release from CPAN to have this automatically
configured for you.

=head1 Columns with auto-increment data types

For those columns where your database uses an auto-incremented value, add the
C<< is_auto_increment => 1 >> parameter to the options list in
C<add_columns()>.  This will let the plugin know you don't need to supply a
value for new or updated records. The interface will look much better as a
result.

If using C<DBIx::Class::Schema::Loader> to generate your Schema, use at least
version 0.05 or the most recent release from CPAN to have this automatically
configured for you.

=cut