=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