X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FManual%2FTroubleshooting.pod;h=e3b1ab3818f98b60cd4ee7a8cb861cebda270c47;hb=8423891f882417dd1f97ca5ef1effd929d624147;hp=643add5df9b525946a34eab0da9e68b69cea57af;hpb=01afee83a917866ef60276f6d29f5c08766d9741;p=dbsrgits%2FDBIx-Class.git

diff --git a/lib/DBIx/Class/Manual/Troubleshooting.pod b/lib/DBIx/Class/Manual/Troubleshooting.pod
index 643add5..e3b1ab3 100644
--- a/lib/DBIx/Class/Manual/Troubleshooting.pod
+++ b/lib/DBIx/Class/Manual/Troubleshooting.pod
@@ -10,22 +10,22 @@ you got back from connect().
 
 =head2 Tracing SQL
 
-The C<DBIX_CLASS_STORAGE_DBI_DEBUG> environment variable controls
+The C<DBIC_TRACE> environment variable controls
 SQL tracing, so to see what is happening try
 
-  export DBIX_CLASS_STORAGE_DBI_DEBUG=1
+  export DBIC_TRACE=1
 
-Alternatively use the C<storage->debug> class method:-
+Alternatively use the C<< storage->debug >> class method:-
 
-  $class->storage->debug(1);
+  $schema->storage->debug(1);
 
 To send the output somewhere else set debugfh:-
 
-  $class->storage->debugfh(IO::File->new('/tmp/trace.out', 'w');
+  $schema->storage->debugfh(IO::File->new('/tmp/trace.out', 'w');
 
 Alternatively you can do this with the environment variable too:-
 
-  export DBIX_CLASS_STORAGE_DBI_DEBUG="1=/tmp/trace.out"
+  export DBIC_TRACE="1=/tmp/trace.out"
 
 =head2 Can't locate method result_source_instance
 
@@ -47,5 +47,114 @@ correctly.
 
 L<DBI> version 1.50 and L<DBD::Pg> 1.43 are known to work.
 
+=head2 Can't locate object method "source_name" via package
+
+There's likely a syntax error in the table class referred to elsewhere
+in this error message.  In particular make sure that the package
+declaration is correct, so for a schema C< MySchema > you need to
+specify a fully qualified namespace: C< package MySchema::MyTable; >
+for example.
+
+=head2 syntax error at or near "<something>" ...
+
+This can happen if you have a relation whose name is a word reserved by your
+database, e.g. "user":
+
+  package My::Schema::User;
+  ...
+  __PACKAGE__->table('users');
+  __PACKAGE__->add_columns(qw/ id name /);
+  __PACKAGE__->set_primary_key('id');
+  ...
+  1;
+
+  package My::Schema::ACL;
+  ...
+  __PACKAGE__->table('acl');
+  __PACKAGE__->add_columns(qw/ user_id /);
+  __PACKAGE__->belongs_to( 'user' => 'My::Schema::User', 'user_id' );
+  ...
+  1;
+
+  $schema->resultset('ACL')->search(
+    {},
+    {
+      join => [qw/ user /],
+      '+select' => [ 'user.name' ]
+    }
+  );
+
+The SQL generated would resemble something like:
+
+  SELECT me.user_id, user.name FROM acl me
+  JOIN users user ON me.user_id = user.id
+
+If, as is likely, your database treats "user" as a reserved word, you'd end
+up with the following errors:
+
+1) syntax error at or near "." - due to "user.name" in the SELECT clause
+
+2) syntax error at or near "user" - due to "user" in the JOIN clause
+
+The solution is to enable quoting - see
+L<DBIx::Class::Manual::Cookbook/Setting_quoting_for_the_generated_SQL> for
+details.
+
+Note that quoting may lead to problems with C<order_by> clauses, see
+L<... column "foo DESC" does not exist ...> for info on avoiding those.
+
+=head2 column "foo DESC" does not exist ...
+
+This can happen if you've turned on quoting and then done something like
+this:
+
+  $rs->search( {}, { order_by => [ 'name DESC' ] } );
+
+This results in SQL like this:
+
+  ... ORDER BY "name DESC"
+
+The solution is to pass your order_by items as scalar references to avoid
+quoting:
+
+  $rs->search( {}, { order_by => [ \'name DESC' ] } );
+
+Now you'll get SQL like this:
+
+  ... ORDER BY name DESC
+
+=head2 Perl Performance Issues on Red Hat Systems
+
+There is a problem with slow performance of certain DBIx::Class
+operations using the system perl on some Fedora and Red Hat Enterprise
+Linux system (as well as their derivative distributions such as Centos,
+White Box and Scientific Linux).
+
+Distributions affected include Fedora 5 through to Fedora 8 and RHEL5
+upto and including RHEL5 Update 2. Fedora 9 (which uses perl 5.10) has
+never been affected - this is purely a perl 5.8.8 issue.
+
+As of September 2008 the following packages are known to be fixed and so
+free of this performance issue (this means all Fedora and RHEL5 systems
+with full current updates will not be subject to this problem):-
+
+  Fedora 8     - perl-5.8.8-41.fc8
+  RHEL5        - perl-5.8.8-15.el5_2.1
+
+The issue is due to perl doing an exhaustive search of blessed objects
+under certain circumstances.  The problem shows up as performance
+degredation exponential to the number of L<DBIx::Class> row objects in
+memory, so can be unoticeable with certain data sets, but with huge
+performance impacts on other datasets.
+
+A pair of tests for susceptability to the issue, and performance effects
+of the bless/overload problem can be found in the L<DBIx::Class> test
+suite in the file C<t/99rh_perl_perf_bug.t>
+
+Further information on this issue can be found in
+L<https://bugzilla.redhat.com/show_bug.cgi?id=379791>,
+L<https://bugzilla.redhat.com/show_bug.cgi?id=460308> and
+L<http://rhn.redhat.com/errata/RHBA-2008-0876.html>
+
 =cut