fix broken link in manual
[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   $class->storage->debug(1);
21
22 To send the output somewhere else set debugfh:-
23
24   $class->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, so for a schema C< MySchema > you need to
55 specify a fully qualified namespace: C< package MySchema::MyTable; >
56 for example.
57
58 =head2 syntax error at or near "<something>" ...
59
60 This can happen if you have a relation whose name is a word reserved by your
61 database, e.g. "user":
62
63   package My::Schema::User;
64   ...
65   __PACKAGE__->table('users');
66   __PACKAGE__->add_columns(qw/ id name /);
67   __PACKAGE__->set_primary_key('id');
68   ...
69   1;
70
71   package My::Schema::ACL;
72   ...
73   __PACKAGE__->table('acl');
74   __PACKAGE__->add_columns(qw/ user_id /);
75   __PACKAGE__->belongs_to( 'user' => 'My::Schema::User', 'user_id' );
76   ...
77   1;
78
79   $schema->resultset('ACL')->search(
80     {},
81     {
82       join => [qw/ user /],
83       '+select' => [ 'user.name' ]
84     }
85   );
86
87 The SQL generated would resemble something like:
88
89   SELECT me.user_id, user.name FROM acl me
90   JOIN users user ON me.user_id = user.id
91
92 If, as is likely, your database treats "user" as a reserved word, you'd end
93 up with the following errors:
94
95 1) syntax error at or near "." - due to "user.name" in the SELECT clause
96
97 2) syntax error at or near "user" - due to "user" in the JOIN clause
98
99 The solution is to enable quoting - see
100 L<DBIx::Class::Manual::Cookbook/Setting_quoting_for_the_generated_SQL> for
101 details.
102
103 Note that quoting may lead to problems with C<order_by> clauses, see
104 L<... column "foo DESC" does not exist ...> for info on avoiding those.
105
106 =head2 column "foo DESC" does not exist ...
107
108 This can happen if you've turned on quoting and then done something like
109 this:
110
111   $rs->search( {}, { order_by => [ 'name DESC' ] } );
112
113 This results in SQL like this:
114
115   ... ORDER BY "name DESC"
116
117 The solution is to pass your order_by items as scalar references to avoid
118 quoting:
119
120   $rs->search( {}, { order_by => [ \'name DESC' ] } );
121
122 Now you'll get SQL like this:
123
124   ... ORDER BY name DESC
125
126 =head2 Perl Performance Issues on Red Hat Systems
127
128 There is a problem with slow performance of certain DBIx::Class
129 operations using the system perl on some Fedora and Red Hat Enterprise
130 Linux system (as well as their derivative distributions such as Centos,
131 White Box and Scientific Linux).
132
133 Distributions affected include Fedora 5 through to Fedora 8 and RHEL5
134 upto and including RHEL5 Update 2. Fedora 9 (which uses perl 5.10) has
135 never been affected - this is purely a perl 5.8.8 issue.
136
137 As of September 2008 the following packages are known to be fixed and so
138 free of this performance issue (this means all Fedora and RHEL5 systems
139 with full current updates will not be subject to this problem):-
140
141   Fedora 8     - perl-5.8.8-41.fc8
142   RHEL5        - perl-5.8.8-15.el5_2.1
143
144 The issue is due to perl doing an exhaustive search of blessed objects
145 under certain circumstances.  The problem shows up as performance
146 degredation exponential to the number of L<DBIx::Class> row objects in
147 memory, so can be unoticeable with certain data sets, but with huge
148 performance impacts on other datasets.
149
150 A pair of tests for susceptability to the issue, and performance effects
151 of the bless/overload problem can be found in the L<DBIx::Class> test
152 suite in the file C<t/99rh_perl_perf_bug.t>
153
154 Further information on this issue can be found in
155 L<https://bugzilla.redhat.com/show_bug.cgi?id=379791>,
156 L<https://bugzilla.redhat.com/show_bug.cgi?id=460308> and
157 L<http://rhn.redhat.com/errata/RHBA-2008-0876.html>
158
159 =cut
160