lib/DBIx/Class/Storage/DBI/ODBC/Microsoft_SQL_Server.pm

   1 package DBIx::Class::Storage::DBI::ODBC::Microsoft_SQL_Server;
   2 use strict;
   3 use warnings;
   4
   5 use base qw/DBIx::Class::Storage::DBI::MSSQL/;
   6 use mro 'c3';
   7 use Scalar::Util 'reftype';
   8 use Try::Tiny;
   9 use DBIx::Class::Carp;
  10 use namespace::clean;
  11
  12 __PACKAGE__->mk_group_accessors(simple => qw/
  13   _using_dynamic_cursors
  14 /);
  15
  16 =head1 NAME
  17
  18 DBIx::Class::Storage::DBI::ODBC::Microsoft_SQL_Server - Support specific
  19 to Microsoft SQL Server over ODBC
  20
  21 =head1 DESCRIPTION
  22
  23 This class implements support specific to Microsoft SQL Server over ODBC.  It is
  24 loaded automatically by by DBIx::Class::Storage::DBI::ODBC when it detects a
  25 MSSQL back-end.
  26
  27 Most of the functionality is provided from the superclass
  28 L<DBIx::Class::Storage::DBI::MSSQL>.
  29
  30 =head1 USAGE NOTES
  31
  32 =head2 Basic Linux Setup (Debian)
  33
  34   sudo aptitude install tdsodbc libdbd-odbc-perl unixodbc
  35
  36 In case it is not already there put the following in C</etc/odbcinst.ini>:
  37
  38   [FreeTDS]
  39   Description = FreeTDS
  40   Driver      = /usr/lib/odbc/libtdsodbc.so
  41   Setup       = /usr/lib/odbc/libtdsS.so
  42   UsageCount  = 1
  43
  44 Set your C<$dsn> in L<connect_info|DBIx::Class::Storage::DBI/connect_info> as follows:
  45
  46   dbi:ODBC:server=<my.host.name>;port=1433;driver=FreeTDS;tds_version=8.0
  47
  48 If you use the EasySoft driver (L<http://www.easysoft.com>):
  49
  50   dbi:ODBC:server=<my.host.name>;port=1433;driver=Easysoft ODBC-SQL Server
  51
  52 =head2 Basic Windows Setup
  53
  54 Use the following C<$dsn> for the Microsoft ODBC driver:
  55
  56   dbi:ODBC:driver={SQL Server};server=SERVER\SQL_SERVER_INSTANCE_NAME
  57
  58 And for the Native Client:
  59
  60   dbi:ODBC:driver={SQL Server Native Client 10.0};server=SERVER\SQL_SERVER_INSTANCE_NAME
  61
  62 Go into Control Panel -> System and Security -> Administrative Tools -> Data
  63 Sources (ODBC) to check driver names and to set up data sources.
  64
  65 Use System DSNs, not User DSNs if you want to use DSNs.
  66
  67 If you set up a DSN, use the following C<$dsn> for
  68 L<connect_info|DBIx::Class::Storage::DBI/connect_info>:
  69
  70   dbi:ODBC:dsn=MY_DSN
  71
  72 =head1 MULTIPLE ACTIVE STATEMENTS
  73
  74 The following options are alternative ways to enable concurrent executing
  75 statement support. Each has its own advantages and drawbacks and works on
  76 different platforms. Read each section carefully.
  77
  78 In order of preference, they are:
  79
  80 =over 8
  81
  82 =item * L<mars|/connect_call_use_mars>
  83
  84 =item * L<dynamic_cursors|/connect_call_use_dynamic_cursors>
  85
  86 =item * L<server_cursors|/connect_call_use_server_cursors>
  87
  88 =back
  89
  90 =head1 METHODS
  91
  92 =head2 connect_call_use_mars
  93
  94 Use as:
  95
  96   on_connect_call => 'use_mars'
  97
  98 in your connection info, or alternatively specify it directly:
  99
 100   Your::Schema->connect (
 101     $original_dsn . '; MARS_Connection=Yes',
 102     $user,
 103     $pass,
 104     \%attrs,
 105   )
 106
 107 Use to enable a feature of SQL Server 2005 and later, "Multiple Active Result
 108 Sets". See L<DBD::ODBC::FAQ/Does DBD::ODBC support Multiple Active Statements?>
 109 for more information.
 110
 111 This does not work on FreeTDS drivers at the time of this writing, and only
 112 works with the Native Client, later versions of the Windows MS ODBC driver, and
 113 the Easysoft driver.
 114
 115 =cut
 116
 117 sub connect_call_use_mars {
 118   my $self = shift;
 119
 120   my $dsn = $self->_dbi_connect_info->[0];
 121
 122   if (ref($dsn) eq 'CODE') {
 123     $self->throw_exception('cannot change the DBI DSN on a CODE ref connect_info');
 124   }
 125
 126   if ($dsn !~ /MARS_Connection=/) {
 127     if ($self->using_freetds) {
 128       $self->throw_exception('FreeTDS does not support MARS at the time of '
 129                             .'writing.');
 130     }
 131
 132     if (exists $self->_server_info->{normalized_dbms_version} &&
 133                $self->_server_info->{normalized_dbms_version} < 9) {
 134       $self->throw_exception('SQL Server 2005 or later required to use MARS.');
 135     }
 136
 137     if (my ($data_source) = $dsn =~ /^dbi:ODBC:([\w-]+)\z/i) { # prefix with DSN
 138       warn "Bare DSN in ODBC connect string, rewriting as 'dsn=$data_source'"
 139           ." for MARS\n";
 140       $dsn = "dbi:ODBC:dsn=$data_source";
 141     }
 142
 143     $self->_dbi_connect_info->[0] = "$dsn;MARS_Connection=Yes";
 144     $self->disconnect;
 145     $self->ensure_connected;
 146   }
 147 }
 148
 149 sub connect_call_use_MARS {
 150   carp "'connect_call_use_MARS' has been deprecated, use "
 151       ."'connect_call_use_mars' instead.";
 152   shift->connect_call_use_mars(@_)
 153 }
 154
 155 =head2 connect_call_use_dynamic_cursors
 156
 157 Use as:
 158
 159   on_connect_call => 'use_dynamic_cursors'
 160
 161 Which will add C<< odbc_cursortype => 2 >> to your DBI connection
 162 attributes, or alternatively specify the necessary flag directly:
 163
 164   Your::Schema->connect (@dsn, { ... odbc_cursortype => 2 })
 165
 166 See L<DBD::ODBC/odbc_cursortype> for more information.
 167
 168 If you're using FreeTDS, C<tds_version> must be set to at least C<8.0>.
 169
 170 This will not work with CODE ref connect_info's.
 171
 172 B<WARNING:> on FreeTDS (and maybe some other drivers) this will break
 173 C<SCOPE_IDENTITY()>, and C<SELECT @@IDENTITY> will be used instead, which on SQL
 174 Server 2005 and later will return erroneous results on tables which have an on
 175 insert trigger that inserts into another table with an C<IDENTITY> column.
 176
 177 B<WARNING:> on FreeTDS, changes made in one statement (e.g. an insert) may not
 178 be visible from a following statement (e.g. a select.)
 179
 180 B<WARNING:> FreeTDS versions > 0.82 seem to have completely broken the ODBC
 181 protocol. DBIC will not allow dynamic cursor support with such versions to
 182 protect your data. Please hassle the authors of FreeTDS to act on the bugs that
 183 make their driver not overly usable with DBD::ODBC.
 184
 185 =cut
 186
 187 sub connect_call_use_dynamic_cursors {
 188   my $self = shift;
 189
 190   if (($self->_dbic_connect_attributes->{odbc_cursortype} || 0) < 2) {
 191
 192     my $dbi_inf = $self->_dbi_connect_info;
 193
 194     $self->throw_exception ('Cannot set DBI attributes on a CODE ref connect_info')
 195       if ref($dbi_inf->[0]) eq 'CODE';
 196
 197     # reenter connection information with the attribute re-set
 198     $dbi_inf->[3] = {} if @$dbi_inf <= 3;
 199     $dbi_inf->[3]{odbc_cursortype} = 2;
 200
 201     $self->_dbi_connect_info($dbi_inf);
 202
 203     $self->disconnect; # resetting dbi attrs, so have to reconnect
 204     $self->ensure_connected;
 205   }
 206 }
 207
 208 sub _run_connection_actions {
 209   my $self = shift;
 210
 211   # keep the dynamic_cursors_support and driver-state in sync
 212   # on every reconnect
 213   my $use_dyncursors = ($self->_dbic_connect_attributes->{odbc_cursortype} || 0) > 1;
 214   if (
 215     $use_dyncursors
 216       xor
 217     !!$self->_using_dynamic_cursors
 218   ) {
 219     if ($use_dyncursors) {
 220       try {
 221         my $dbh = $self->_dbh;
 222         local $dbh->{RaiseError} = 1;
 223         local $dbh->{PrintError} = 0;
 224         $dbh->do('SELECT @@IDENTITY');
 225       } catch {
 226         $self->throw_exception (
 227           'Your drivers do not seem to support dynamic cursors (odbc_cursortype => 2).'
 228          . (
 229           $self->using_freetds
 230             ? ' If you are using FreeTDS, make sure to set tds_version to 8.0 or greater.'
 231             : ''
 232           )
 233         );
 234       };
 235
 236       $self->_using_dynamic_cursors(1);
 237       $self->_identity_method('@@identity');
 238       $self->_no_scope_identity_query($self->using_freetds);
 239     }
 240     else {
 241       $self->_using_dynamic_cursors(0);
 242       $self->_identity_method(undef);
 243       $self->_no_scope_identity_query(undef);
 244     }
 245   }
 246
 247   $self->next::method (@_);
 248
 249   # freetds is too damn broken, some fixups
 250   if ($self->using_freetds) {
 251
 252     # no dynamic cursors starting from 0.83
 253     if ($self->_using_dynamic_cursors) {
 254       my $fv = $self->_dbh_get_info('SQL_DRIVER_VER');
 255       $self->throw_exception(
 256         'Dynamic cursors (odbc_cursortype => 2) are not supported with FreeTDS > 0.82 '
 257       . "(you have $fv). Please hassle FreeTDS authors to fix the outstanding bugs in "
 258       . 'their driver.'
 259       ) if $fv > 0.82
 260     }
 261
 262     # FreeTDS is too broken wrt execute_for_fetch batching
 263     # just disable it outright until things quiet down
 264     $self->_get_dbh->{odbc_disable_array_operations} = 1;
 265   }
 266 }
 267
 268 =head2 connect_call_use_server_cursors
 269
 270 Use as:
 271
 272   on_connect_call => 'use_server_cursors'
 273
 274 May allow multiple active select statements. See
 275 L<DBD::ODBC/odbc_SQL_ROWSET_SIZE> for more information.
 276
 277 Takes an optional parameter for the value to set the attribute to, default is
 278 C<2>.
 279
 280 B<WARNING>: this does not work on all versions of SQL Server, and may lock up
 281 your database!
 282
 283 At the time of writing, this option only works on Microsoft's Windows drivers,
 284 later versions of the ODBC driver and the Native Client driver.
 285
 286 =cut
 287
 288 sub connect_call_use_server_cursors {
 289   my $self            = shift;
 290   my $sql_rowset_size = shift || 2;
 291
 292   if ($^O !~ /win32|cygwin/i) {
 293     $self->throw_exception('Server cursors only work on Windows platforms at '
 294                           .'the time of writing.');
 295   }
 296
 297   $self->_get_dbh->{odbc_SQL_ROWSET_SIZE} = $sql_rowset_size;
 298 }
 299
 300 =head2 using_freetds
 301
 302 Tries to determine, to the best of our ability, whether or not you are using the
 303 FreeTDS driver with L<DBD::ODBC>.
 304
 305 =cut
 306
 307 sub using_freetds {
 308   my $self = shift;
 309
 310   my $dsn = $self->_dbi_connect_info->[0];
 311
 312   $dsn = '' if ref $dsn eq 'CODE';
 313
 314   return 1 if $dsn =~ /driver=FreeTDS/i
 315               || ($self->_dbh_get_info('SQL_DRIVER_NAME')||'') =~ /tdsodbc/i;
 316
 317   return 0;
 318 }
 319
 320 1;
 321
 322 =head1 AUTHOR
 323
 324 See L<DBIx::Class/AUTHOR> and L<DBIx::Class/CONTRIBUTORS>.
 325
 326 =head1 LICENSE
 327
 328 You may distribute this code under the same terms as Perl itself.
 329
 330 =cut
 331 # vim:sw=2 sts=2 et