Tiny POD formatting fix
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Manual / Troubleshooting.pod
CommitLineData
3b44ccc6 1=head1 NAME
2
3DBIx::Class::Manual::Troubleshooting - Got a problem? Shoot it.
ee38fa40 4
130c6439 5=head2 "Can't locate storage blabla"
ee38fa40 6
01afee83 7You're trying to make a query on a non-connected schema. Make sure you got
8the current resultset from $schema->resultset('Artist') on a schema object
9you got back from connect().
10
159a8515 11=head2 Tracing SQL
12
6fe735fa 13The C<DBIC_TRACE> environment variable controls
159a8515 14SQL tracing, so to see what is happening try
15
6fe735fa 16 export DBIC_TRACE=1
159a8515 17
1780ac9b 18Alternatively use the C<< storage->debug >> class method:-
159a8515 19
20 $class->storage->debug(1);
21
92b858c9 22To send the output somewhere else set debugfh:-
23
24 $class->storage->debugfh(IO::File->new('/tmp/trace.out', 'w');
25
26Alternatively you can do this with the environment variable too:-
27
6fe735fa 28 export DBIC_TRACE="1=/tmp/trace.out"
159a8515 29
01afee83 30=head2 Can't locate method result_source_instance
31
32For some reason the table class in question didn't load fully, so the
33ResultSource object for it hasn't been created. Debug this class in
34isolation, then try loading the full schema again.
35
36=head2 Can't get last insert ID under Postgres with serial primary keys
37
38Older L<DBI> and L<DBD::Pg> versions do not handle C<last_insert_id>
39correctly, causing code that uses auto-incrementing primary key
40columns to fail with a message such as:
41
42 Can't get last insert id at /.../DBIx/Class/Row.pm line 95
43
44In particular the RHEL 4 and FC3 Linux distributions both ship with
45combinations of L<DBI> and L<DBD::Pg> modules that do not work
46correctly.
47
48L<DBI> version 1.50 and L<DBD::Pg> 1.43 are known to work.
49
b24d86a1 50=head2 Can't locate object method "source_name" via package
38c07935 51
52There's likely a syntax error in the table class referred to elsewhere
53in this error message. In particular make sure that the package
54declaration is correct, so for a schema C< MySchema > you need to
55specify a fully qualified namespace: C< package MySchema::MyTable; >
56for example.
57
0e8f60fc 58=head2 syntax error at or near "<something>" ...
59
60This can happen if you have a relation whose name is a word reserved by your
61database, 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
87The 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
92If, as is likely, your database treats "user" as a reserved word, you'd end
93up with the following errors:
94
951) syntax error at or near "." - due to "user.name" in the SELECT clause
96
972) syntax error at or near "user" - due to "user" in the JOIN clause
98
99The solution is to enable quoting - see
100L<DBIx::Class::Manual::Cookbook/Setting_quoting_for_the_generated_SQL> for
101details.
102
103Note that quoting may lead to problems with C<order_by> clauses, see
104L<... column "foo DESC" does not exist ...> for info on avoiding those.
105
106=head2 column "foo DESC" does not exist ...
107
108This can happen if you've turned on quoting and then done something like
109this:
110
111 $rs->search( {}, { order_by => [ 'name DESC' ] } );
112
113This results in SQL like this:
114
115 ... ORDER BY "name DESC"
116
117The solution is to pass your order_by items as scalar references to avoid
118quoting:
119
120 $rs->search( {}, { order_by => [ \'name DESC' ] } );
121
122Now you'll get SQL like this:
123
124 ... ORDER BY name DESC
125
dc253b77 126=head2 Perl Performance Issues on Red Hat Systems
127
128There is a problem with slow performance of certain DBIx::Class
129operations using the system perl on some Fedora and Red Hat Enterprise
130Linux system (as well as their derivative distributions such as Centos,
c13fabce 131White Box and Scientific Linux).
dc253b77 132
133Distributions affected include Fedora 5 through to Fedora 8 and RHEL5
134upto and including RHEL5 Update 2. Fedora 9 (which uses perl 5.10) has
135never been affected - this is purely a perl 5.8.8 issue.
136
137As of September 2008 the following packages are known to be fixed and so
138free of this performance issue (this means all Fedora and RHEL5 systems
139with 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
144The issue is due to perl doing an exhaustive search of blessed objects
145under certain circumstances. The problem shows up as performance
146degredation exponential to the number of L<DBIx::Class> row objects in
147memory, so can be unoticeable with certain data sets, but with huge
148performance impacts on other datasets.
149
150A pair of tests for susceptability to the issue, and performance effects
151of the bless/overload problem can be found in the L<DBIx::Class> test
152suite in the file C<t/99rh_perl_perf_bug.t>
153
154Further information on this issue can be found in
155L<https://bugzilla.redhat.com/show_bug.cgi?id=379791>,
156L<https://bugzilla.redhat.com/show_bug.cgi?id=460308> and
157L<http://rhn.redhat.com/errata/RHBA-2008-0876.html>
158
ee38fa40 159=cut
160