Clarification cascade_* attribute defaults documentation
[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
c92da5a9 20 $schema->storage->debug(1);
159a8515 21
92b858c9 22To send the output somewhere else set debugfh:-
23
c92da5a9 24 $schema->storage->debugfh(IO::File->new('/tmp/trace.out', 'w');
92b858c9 25
48580715 26Alternatively you can do this with the environment variable, too:-
92b858c9 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
48580715 54declaration is correct. For example, for a schema C< MySchema >
55you need to specify a fully qualified namespace: C< package MySchema::MyTable; >.
38c07935 56
0e8f60fc 57=head2 syntax error at or near "<something>" ...
58
59This can happen if you have a relation whose name is a word reserved by your
60database, 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
86The 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
91If, as is likely, your database treats "user" as a reserved word, you'd end
92up with the following errors:
93
941) syntax error at or near "." - due to "user.name" in the SELECT clause
95
962) syntax error at or near "user" - due to "user" in the JOIN clause
97
98The solution is to enable quoting - see
99L<DBIx::Class::Manual::Cookbook/Setting_quoting_for_the_generated_SQL> for
100details.
101
0e8f60fc 102=head2 column "foo DESC" does not exist ...
103
8d5a66b8 104This can happen if you are still using the obsolete order hack, and also
48580715 105happen to turn on SQL-quoting.
0e8f60fc 106
107 $rs->search( {}, { order_by => [ 'name DESC' ] } );
108
8d5a66b8 109Since L<DBIx::Class> >= 0.08100 and L<SQL::Abstract> >= 1.50 the above
110should be written as:
0e8f60fc 111
8d5a66b8 112 $rs->search( {}, { order_by => { -desc => 'name' } } );
0e8f60fc 113
8d5a66b8 114For more ways to express order clauses refer to
115L<SQL::Abstract/ORDER_BY_CLAUSES>
0e8f60fc 116
dc253b77 117=head2 Perl Performance Issues on Red Hat Systems
118
119There is a problem with slow performance of certain DBIx::Class
120operations using the system perl on some Fedora and Red Hat Enterprise
121Linux system (as well as their derivative distributions such as Centos,
c13fabce 122White Box and Scientific Linux).
dc253b77 123
124Distributions affected include Fedora 5 through to Fedora 8 and RHEL5
125upto and including RHEL5 Update 2. Fedora 9 (which uses perl 5.10) has
126never been affected - this is purely a perl 5.8.8 issue.
127
128As of September 2008 the following packages are known to be fixed and so
129free of this performance issue (this means all Fedora and RHEL5 systems
130with 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
48580715 135This issue is due to perl doing an exhaustive search of blessed objects
dc253b77 136under certain circumstances. The problem shows up as performance
48580715 137degradation exponential to the number of L<DBIx::Class> row objects in
138memory, so can be unnoticeable with certain data sets, but with huge
dc253b77 139performance impacts on other datasets.
140
48580715 141A pair of tests for susceptibility to the issue and performance effects
dc253b77 142of the bless/overload problem can be found in the L<DBIx::Class> test
48580715 143suite, in the C<t/99rh_perl_perf_bug.t> file.
dc253b77 144
145Further information on this issue can be found in
146L<https://bugzilla.redhat.com/show_bug.cgi?id=379791>,
147L<https://bugzilla.redhat.com/show_bug.cgi?id=460308> and
148L<http://rhn.redhat.com/errata/RHBA-2008-0876.html>
149
d50421e7 150=head2 Excessive Memory Allocation with TEXT/BLOB/etc. Columns and Large LongReadLen
151
48580715 152It has been observed, using L<DBD::ODBC>, that creating a L<DBIx::Class::Row>
d50421e7 153object which includes a column of data type TEXT/BLOB/etc. will allocate
154LongReadLen bytes. This allocation does not leak, but if LongReadLen
155is large in size, and many such row objects are created, e.g. as the
156output of a ResultSet query, the memory footprint of the Perl interpreter
157can grow very large.
158
159The solution is to use the smallest practical value for LongReadLen.
160
45a054fc 161=head2 create_ddl_dir does not produce DDL for MySQL views
162
163L<SQL::Translator> does not create DDL for MySQL views if it doesn't know you
164are using mysql version 5.000001 or higher. To explicity set this version, add
165C<mysql_version> to the C<producer_args> in the C<%sqlt> options.
166
167 $schema->create_ddl_dir(['MySQL'], '1.0', './sql/', undef, { producer_args => { mysql_version => 5.000058 } })
168
ee38fa40 169=cut
170