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   # keep the dynamic_cursors_support and driver-state in sync
 215   # on every reconnect
 216   my $use_dyncursors = ($self->_dbic_connect_attributes->{odbc_cursortype} || 0) > 1;
 217   if (
 218     $use_dyncursors
 219       xor
 220     !!$self->_using_dynamic_cursors
 221   ) {
 222     if ($use_dyncursors) {
 223       try {
 224         my $dbh = $self->_dbh;
 225         local $dbh->{RaiseError} = 1;
 226         local $dbh->{PrintError} = 0;
 227         $dbh->do('SELECT @@IDENTITY');
 228       } catch {
 229         $self->throw_exception (
 230           'Your drivers do not seem to support dynamic cursors (odbc_cursortype => 2).'
 231          . (
 232           $self->_using_freetds
 233             ? ' If you are using FreeTDS, make sure to set tds_version to 8.0 or greater.'
 234             : ''
 235           )
 236         );
 237       };
 238
 239       $self->_using_dynamic_cursors(1);
 240       $self->_identity_method('@@identity');
 241       $self->_no_scope_identity_query($self->_using_freetds);
 242     }
 243     else {
 244       $self->_using_dynamic_cursors(0);
 245       $self->_identity_method(undef);
 246       $self->_no_scope_identity_query(undef);
 247     }
 248   }
 249
 250   $self->next::method (@_);
 251
 252   # freetds is too damn broken, some fixups
 253   if ($self->_using_freetds) {
 254
 255     # no dynamic cursors starting from 0.83
 256     if ($self->_using_dynamic_cursors) {
 257       my $fv = $self->_using_freetds_version || 999;  # assume large if can't be determined
 258       $self->throw_exception(
 259         'Dynamic cursors (odbc_cursortype => 2) are not supported with FreeTDS > 0.82 '
 260       . "(you have $fv). Please hassle FreeTDS authors to fix the outstanding bugs in "
 261       . 'their driver.'
 262       ) if $fv > 0.82
 263     }
 264
 265     # FreeTDS is too broken wrt execute_for_fetch batching
 266     # just disable it outright until things quiet down
 267     $self->_disable_odbc_array_ops;
 268   }
 269 }
 270
 271 =head2 connect_call_use_server_cursors
 272
 273 Use as:
 274
 275   on_connect_call => 'use_server_cursors'
 276
 277 May allow multiple active select statements. See
 278 L<DBD::ODBC/odbc_SQL_ROWSET_SIZE> for more information.
 279
 280 Takes an optional parameter for the value to set the attribute to, default is
 281 C<2>.
 282
 283 B<WARNING>: this does not work on all versions of SQL Server, and may lock up
 284 your database!
 285
 286 At the time of writing, this option only works on Microsoft's Windows drivers,
 287 later versions of the ODBC driver and the Native Client driver.
 288
 289 =cut
 290
 291 sub connect_call_use_server_cursors {
 292   my $self            = shift;
 293   my $sql_rowset_size = shift || 2;
 294
 295   if ($^O !~ /win32|cygwin/i) {
 296     $self->throw_exception('Server cursors only work on Windows platforms at '
 297                           .'the time of writing.');
 298   }
 299
 300   $self->_get_dbh->{odbc_SQL_ROWSET_SIZE} = $sql_rowset_size;
 301 }
 302
 303 1;
 304
 305 =head1 AUTHOR
 306
 307 See L<DBIx::Class/AUTHOR> and L<DBIx::Class/CONTRIBUTORS>.
 308
 309 =head1 LICENSE
 310
 311 You may distribute this code under the same terms as Perl itself.
 312
 313 =cut
 314 # vim:sw=2 sts=2 et