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