FS/FS/DBI.pm

   1 package FS::DBI;
   2 use strict;
   3 use warnings;
   4 use base qw( DBI );
   5
   6 =head1 NAME
   7
   8 FS::DBI - Freeside wrapper for DBI
   9
  10 =head1 SYNOPSIS
  11
  12   use FS::DBI;
  13
  14   $dbh = FS::DBI->connect( @args );
  15   $dbh->do(
  16     'UPDATE table SET foo = ? WHERE bar = ?',
  17     undef,
  18     $foo, $bar
  19   ) or die $dbh->errstr;
  20
  21 See L<DBI>
  22
  23 =head1 DESCRIPTION
  24
  25 Allow Freeside to manage how DBI is used when necessary
  26
  27 =head2 Legacy databases and DBD::Pg v3.0+
  28
  29 Breaking behavior was introduced in DBD::Pg version 3.0.0
  30 in regards to L<DBD::Pg/pg_enable_utf8>.
  31
  32 Some freedside databases are legacy databases with older encodings
  33 and locales. pg_enable_utf8 no longer sets client_encoding to utf8
  34 on non-utf8 databases, causing crashes and data corruption.
  35
  36 FS::DBI->connect() enforces utf8 client_encoding on all DBD::Pg connections
  37
  38 =head1 METHODS
  39
  40 =head2 connect @connect_args
  41
  42 For usage, see L<DBI/connect>
  43
  44 Force utf8 client_encoding on DBD::Pg connections
  45
  46 =cut
  47
  48 sub connect {
  49   my $class = shift;
  50   my $dbh = $class->SUPER::connect( @_ );
  51
  52   if ( $_[0] =~ /^DBI:Pg/ ) {
  53     $dbh->do('SET client_encoding TO UTF8;')
  54       or die sprintf 'Error setting client_encoding to UTF8: %s', $dbh->errstr;
  55
  56     # DBD::Pg requires touching this attribute when changing the client_encoding
  57     # on an already established connection, to get expected behavior.
  58     $dbh->{pg_enable_utf8} = -1;
  59   }
  60
  61   $dbh;
  62 }
  63
  64 # Stub required to subclass DBI
  65 package FS::DBI::st;
  66 use base qw( DBI::st );
  67
  68 # Stub required to subclass DBI
  69 package FS::DBI::db;
  70 use base qw( DBI::db );
  71
  72 1;