makes search_related on extended rels without the optimized version work. involves...
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Troubleshooting.pod
1 =head1 NAME
2
3 DBIx::Class::Manual::Troubleshooting - Got a problem? Shoot it.
4
5 =head2  "Can't locate storage blabla"
6
7 You're trying to make a query on a non-connected schema. Make sure you got
8 the current resultset from $schema->resultset('Artist') on a schema object
9 you got back from connect().
10
11 =head2 Tracing SQL
12
13 The C<DBIC_TRACE> environment variable controls
14 SQL tracing, so to see what is happening try
15
16   export DBIC_TRACE=1
17
18 Alternatively use the C<< storage->debug >> class method:-
19
20   $schema->storage->debug(1);
21
22 To send the output somewhere else set debugfh:-
23
24   $schema->storage->debugfh(IO::File->new('/tmp/trace.out', 'w');
25
26 Alternatively you can do this with the environment variable, too:-
27
28   export DBIC_TRACE="1=/tmp/trace.out"
29
30 =head2 Can't locate method result_source_instance
31
32 For some reason the table class in question didn't load fully, so the
33 ResultSource object for it hasn't been created. Debug this class in
34 isolation, then try loading the full schema again.
35
36 =head2 Can't get last insert ID under Postgres with serial primary keys
37
38 Older L<DBI> and L<DBD::Pg> versions do not handle C<last_insert_id>
39 correctly, causing code that uses auto-incrementing primary key
40 columns to fail with a message such as:
41
42   Can't get last insert id at /.../DBIx/Class/Row.pm line 95
43
44 In particular the RHEL 4 and FC3 Linux distributions both ship with
45 combinations of L<DBI> and L<DBD::Pg> modules that do not work
46 correctly.
47
48 L<DBI> version 1.50 and L<DBD::Pg> 1.43 are known to work.
49
50 =head2 Can't locate object method "source_name" via package
51
52 There's likely a syntax error in the table class referred to elsewhere
53 in this error message.  In particular make sure that the package
54 declaration is correct. For example, for a schema C< MySchema > 
55 you need to specify a fully qualified namespace: C< package MySchema::MyTable; >.
56
57 =head2 syntax error at or near "<something>" ...
58
59 This can happen if you have a relation whose name is a word reserved by your
60 database, e.g. "user":
61
62   package My::Schema::User;
63   ...
64   __PACKAGE__->table('users');
65   __PACKAGE__->add_columns(qw/ id name /);
66   __PACKAGE__->set_primary_key('id');
67   ...
68   1;
69
70   package My::Schema::ACL;
71   ...
72   __PACKAGE__->table('acl');
73   __PACKAGE__->add_columns(qw/ user_id /);
74   __PACKAGE__->belongs_to( 'user' => 'My::Schema::User', 'user_id' );
75   ...
76   1;
77
78   $schema->resultset('ACL')->search(
79     {},
80     {
81       join => [qw/ user /],
82       '+select' => [ 'user.name' ]
83     }
84   );
85
86 The SQL generated would resemble something like:
87
88   SELECT me.user_id, user.name FROM acl me
89   JOIN users user ON me.user_id = user.id
90
91 If, as is likely, your database treats "user" as a reserved word, you'd end
92 up with the following errors:
93
94 1) syntax error at or near "." - due to "user.name" in the SELECT clause
95
96 2) syntax error at or near "user" - due to "user" in the JOIN clause
97
98 The solution is to enable quoting - see
99 L<DBIx::Class::Manual::Cookbook/Setting_quoting_for_the_generated_SQL> for
100 details.
101
102 =head2 column "foo DESC" does not exist ...
103
104 This can happen if you are still using the obsolete order hack, and also
105 happen to turn on SQL-quoting.
106
107   $rs->search( {}, { order_by => [ 'name DESC' ] } );
108
109 Since L<DBIx::Class> >= 0.08100 and L<SQL::Abstract> >= 1.50 the above
110 should be written as:
111
112   $rs->search( {}, { order_by => { -desc => 'name' } } );
113
114 For more ways to express order clauses refer to
115 L<SQL::Abstract/ORDER_BY_CLAUSES>
116
117 =head2 Perl Performance Issues on Red Hat Systems
118
119 There is a problem with slow performance of certain DBIx::Class
120 operations using the system perl on some Fedora and Red Hat Enterprise
121 Linux system (as well as their derivative distributions such as Centos,
122 White Box and Scientific Linux).
123
124 Distributions affected include Fedora 5 through to Fedora 8 and RHEL5
125 upto and including RHEL5 Update 2. Fedora 9 (which uses perl 5.10) has
126 never been affected - this is purely a perl 5.8.8 issue.
127
128 As of September 2008 the following packages are known to be fixed and so
129 free of this performance issue (this means all Fedora and RHEL5 systems
130 with full current updates will not be subject to this problem):-
131
132   Fedora 8     - perl-5.8.8-41.fc8
133   RHEL5        - perl-5.8.8-15.el5_2.1
134
135 This issue is due to perl doing an exhaustive search of blessed objects
136 under certain circumstances.  The problem shows up as performance
137 degradation exponential to the number of L<DBIx::Class> row objects in
138 memory, so can be unnoticeable with certain data sets, but with huge
139 performance impacts on other datasets.
140
141 A pair of tests for susceptibility to the issue and performance effects
142 of the bless/overload problem can be found in the L<DBIx::Class> test
143 suite, in the C<t/99rh_perl_perf_bug.t> file.
144
145 Further information on this issue can be found in
146 L<https://bugzilla.redhat.com/show_bug.cgi?id=379791>,
147 L<https://bugzilla.redhat.com/show_bug.cgi?id=460308> and
148 L<http://rhn.redhat.com/errata/RHBA-2008-0876.html>
149
150 =head2 Excessive Memory Allocation with TEXT/BLOB/etc. Columns and Large LongReadLen
151
152 It has been observed, using L<DBD::ODBC>, that creating a L<DBIx::Class::Row> 
153 object which includes a column of data type TEXT/BLOB/etc. will allocate 
154 LongReadLen bytes.  This allocation does not leak, but if LongReadLen 
155 is large in size, and many such row objects are created, e.g. as the 
156 output of a ResultSet query, the memory footprint of the Perl interpreter 
157 can grow very large.
158
159 The solution is to use the smallest practical value for LongReadLen.
160
161 =cut
162