Reduce the number of times $self->_dbh is called inside dbh_do() to speed
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / CDBICompat.pm
CommitLineData
ea2e61bf 1package DBIx::Class::CDBICompat;
2
3use strict;
4use warnings;
75a23b3e 5use base qw/DBIx::Class::Core DBIx::Class::DB/;
289ba852 6use Carp::Clan qw/^DBIx::Class/;
7
8eval {
9 require Class::Trigger;
10 require DBIx::ContextualFetch;
11};
12croak "Class::Trigger and DBIx::ContextualFetch is required for CDBICompat" if $@;
126042ee 13
55e2d745 14__PACKAGE__->load_own_components(qw/
15 Constraints
16 Triggers
17 ReadOnly
55e2d745 18 LiveObjectIndex
19 AttributeAPI
20 Stringify
21 DestroyWarning
22 Constructor
23 AccessorMapping
24 ColumnCase
a9c8094b 25 Relationships
e60dc79f 26 Copy
55e2d745 27 LazyLoading
28 AutoUpdate
29 TempColumns
e60dc79f 30 GetSet
55e2d745 31 Retrieve
2a21de92 32 Pager
55e2d745 33 ColumnGroups
5ef62e9f 34 ColumnsAsHash
e60dc79f 35 AbstractSearch
36 ImaDBI
37 Iterator
38/);
55e2d745 39
40 #DBIx::Class::ObjIndexStubs
ea2e61bf 411;
34d52be2 42
75d07914 43=head1 NAME
34d52be2 44
880a1a0c 45DBIx::Class::CDBICompat - Class::DBI Compatibility layer.
34d52be2 46
15fe6346 47=head1 SYNOPSIS
48
4965b78d 49 package My::CDBI;
50 use base qw/DBIx::Class::CDBICompat/;
51
52 ...continue as Class::DBI...
15fe6346 53
34d52be2 54=head1 DESCRIPTION
55
880a1a0c 56DBIx::Class features a fully featured compatibility layer with L<Class::DBI>
4965b78d 57and some common plugins to ease transition for existing CDBI users.
58
59This is not a wrapper or subclass of DBIx::Class but rather a series of plugins. The result being that even though you're using the Class::DBI emulation layer you are still getting DBIx::Class objects. You can use all DBIx::Class features and methods via CDBICompat. This allows you to take advantage of DBIx::Class features without having to rewrite your CDBI code.
60
61
62=head2 Plugins
63
64CDBICompat is good enough that many CDBI plugins will work with CDBICompat, but many of the plugin features are better done with DBIx::Class methods.
65
66=head3 Class::DBI::AbstractSearch
67
68C<search_where()> is fully emulated using DBIC's search. Aside from emulation there's no reason to use C<search_where()>.
69
70=head3 Class::DBI::Plugin::NoCache
71
72C<nocache> is fully emulated.
73
74=head3 Class::DBI::Sweet
75
76The features of CDBI::Sweet are better done using DBIC methods which are almost exactly the same. It even uses L<Data::Page>.
77
78=head3 Class::DBI::Plugin::DeepAbstractSearch
79
fbee5c55 80This plugin will work, but it is more efficiently done using DBIC's native search facilities. The major difference is that DBIC will not infer the join for you, you have to tell it the join tables.
4965b78d 81
82
83=head2 Choosing Features
e7d1440f 84
85In fact, this class is just a receipe containing all the features emulated.
86If you like, you can choose which features to emulate by building your
87own class and loading it like this:
15fe6346 88
4965b78d 89 package My::DB;
15fe6346 90 __PACKAGE__->load_own_components(qw/CDBICompat/);
91
75d07914 92this will automatically load the features included in My::DB::CDBICompat,
15fe6346 93provided it looks something like this:
94
95 package My::DB::CDBICompat;
96 __PACKAGE__->load_components(qw/
97 CDBICompat::ColumnGroups
98 CDBICompat::Retrieve
99 CDBICompat::HasA
100 CDBICompat::HasMany
101 CDBICompat::MightHave
102 /);
103
34d52be2 104
e7d1440f 105=head1 LIMITATIONS
106
af133470 107=head2 Unimplemented
108
e7d1440f 109The following methods and classes are not emulated, maybe in the future.
110
111=over 4
112
113=item Class::DBI::Query
114
115Deprecated in Class::DBI.
116
117=item Class::DBI::Column
118
119Not documented in Class::DBI. CDBICompat's columns() returns a plain string, not an object.
120
121=item data_type()
122
123Undocumented CDBI method.
124
af133470 125=back
126
127=head2 Limited Support
128
129The following elements of Class::DBI have limited support.
130
131=over 4
132
474481a9 133=item Class::DBI::Relationship
e7d1440f 134
474481a9 135The semi-documented Class::DBI::Relationship objects returned by C<meta_info($type, $col)> are mostly emulated except for their C<args> method.
e7d1440f 136
af133470 137=item Relationships
138
139Relationships between tables (has_a, has_many...) must be delcared after all tables in the relationship have been declared. Thus the usual CDBI idiom of declaring columns and relationships for each class together will not work. They must instead be done like so:
140
141 package Foo;
142 use base qw(Class::DBI);
143
144 Foo->table("foo");
145 Foo->columns( All => qw(this that bar) );
146
147 package Bar;
148 use base qw(Class::DBI);
149
150 Bar->table("bar");
151 Bar->columns( All => qw(up down) );
152
153 # Now that Foo and Bar are declared it is safe to declare a
154 # relationship between them
155 Foo->has_a( bar => "Bar" );
156
157
e7d1440f 158=back
159
34d52be2 160=head1 AUTHORS
161
daec44b8 162Matt S. Trout <mst@shadowcatsystems.co.uk>
34d52be2 163
164=head1 LICENSE
165
166You may distribute this code under the same terms as Perl itself.
167
168=cut
169