remove Sub::Name hack for method dispatch, pass $next instead
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / Storage / DBI / Sybase.pm
1 package DBIx::Class::Storage::DBI::Sybase;
2
3 use strict;
4 use warnings;
5
6 use base qw/
7     DBIx::Class::Storage::DBI::Sybase::Common
8     DBIx::Class::Storage::DBI::AutoCast
9 /;
10 use mro 'c3';
11 use Carp::Clan qw/^DBIx::Class/;
12 use List::Util ();
13
14 __PACKAGE__->mk_group_accessors('simple' =>
15     qw/_identity _blob_log_on_update _insert_dbh _identity_method/
16 );
17
18 =head1 NAME
19
20 DBIx::Class::Storage::DBI::Sybase - Sybase support for DBIx::Class
21
22 =head1 SYNOPSIS
23
24 This subclass supports L<DBD::Sybase> for real Sybase databases.  If you are
25 using an MSSQL database via L<DBD::Sybase>, your storage will be reblessed to
26 L<DBIx::Class::Storage::DBI::Sybase::Microsoft_SQL_Server>.
27
28 =head1 DESCRIPTION
29
30 If your version of Sybase does not support placeholders, then your storage
31 will be reblessed to L<DBIx::Class::Storage::DBI::Sybase::NoBindVars>. You can
32 also enable that driver explicitly, see the documentation for more details.
33
34 With this driver there is unfortunately no way to get the C<last_insert_id>
35 without doing a C<SELECT MAX(col)>. This is done safely in a transaction
36 (locking the table.) See L</INSERTS WITH PLACEHOLDERS>.
37
38 A recommended L<DBIx::Class::Storage::DBI/connect_info> setting:
39
40   on_connect_call => [['datetime_setup'], ['blob_setup', log_on_update => 0]]
41
42 =head1 METHODS
43
44 =cut
45
46 sub _rebless {
47   my $self = shift;
48
49   if (ref($self) eq 'DBIx::Class::Storage::DBI::Sybase') {
50     my $dbtype = eval {
51       @{$self->_get_dbh->selectrow_arrayref(qq{sp_server_info \@attribute_id=1})}[2]
52     } || '';
53
54     my $exception = $@;
55     $dbtype =~ s/\W/_/gi;
56     my $subclass = "DBIx::Class::Storage::DBI::Sybase::${dbtype}";
57
58     if (!$exception && $dbtype && $self->load_optional_class($subclass)) {
59       bless $self, $subclass;
60       $self->_rebless;
61     } else { # real Sybase
62       my $no_bind_vars = 'DBIx::Class::Storage::DBI::Sybase::NoBindVars';
63
64       if ($self->using_freetds) {
65         carp <<'EOF' unless $ENV{DBIC_SYBASE_FREETDS_NOWARN};
66
67 You are using FreeTDS with Sybase.
68
69 We will do our best to support this configuration, but please consider this
70 support experimental.
71
72 TEXT/IMAGE columns will definitely not work.
73
74 You are encouraged to recompile DBD::Sybase with the Sybase Open Client libraries
75 instead.
76
77 See perldoc DBIx::Class::Storage::DBI::Sybase for more details.
78
79 To turn off this warning set the DBIC_SYBASE_FREETDS_NOWARN environment
80 variable.
81 EOF
82         if (not $self->_typeless_placeholders_supported) {
83           if ($self->_placeholders_supported) {
84             $self->auto_cast(1);
85           } else {
86             $self->ensure_class_loaded($no_bind_vars);
87             bless $self, $no_bind_vars;
88             $self->_rebless;
89           }
90         }
91       }
92       elsif (not $self->_get_dbh->{syb_dynamic_supported}) {
93         # not necessarily FreeTDS, but no placeholders nevertheless
94         $self->ensure_class_loaded($no_bind_vars);
95         bless $self, $no_bind_vars;
96         $self->_rebless;
97       } elsif (not $self->_typeless_placeholders_supported) {
98 # this is highly unlikely, but we check just in case
99         $self->auto_cast(1);
100       }
101     }
102   }
103 }
104
105 sub _init {
106   my $self = shift;
107   $self->_set_max_connect(256);
108
109   # based on LongReadLen in connect_info
110   $self->set_textsize if $self->using_freetds;
111 }
112
113 # Make sure we have CHAINED mode turned on if AutoCommit is off in non-FreeTDS
114 # DBD::Sybase (since we don't know how DBD::Sybase was compiled.) If however
115 # we're using FreeTDS, CHAINED mode turns on an implicit transaction which we
116 # only want when AutoCommit is off.
117 sub _populate_dbh {
118   my $self = shift;
119
120   $self->next::method(@_);
121
122   if (not $self->using_freetds) {
123     $self->_dbh->{syb_chained_txn} = 1;
124   } else {
125     if ($self->_dbh_autocommit) {
126       $self->_dbh->do('SET CHAINED OFF');
127     } else {
128       $self->_dbh->do('SET CHAINED ON');
129     }
130   }
131 }
132
133 =head2 connect_call_blob_setup
134
135 Used as:
136
137   on_connect_call => [ [ 'blob_setup', log_on_update => 0 ] ]
138
139 Does C<< $dbh->{syb_binary_images} = 1; >> to return C<IMAGE> data as raw binary
140 instead of as a hex string.
141
142 Recommended.
143
144 Also sets the C<log_on_update> value for blob write operations. The default is
145 C<1>, but C<0> is better if your database is configured for it.
146
147 See
148 L<DBD::Sybase/Handling_IMAGE/TEXT_data_with_syb_ct_get_data()/syb_ct_send_data()>.
149
150 =cut
151
152 sub connect_call_blob_setup {
153   my $self = shift;
154   my %args = @_;
155   my $dbh = $self->_dbh;
156   $dbh->{syb_binary_images} = 1;
157
158   $self->_blob_log_on_update($args{log_on_update})
159     if exists $args{log_on_update};
160 }
161
162 sub _is_lob_type {
163   my $self = shift;
164   my $type = shift;
165   $type && $type =~ /(?:text|image|lob|bytea|binary|memo)/i;
166 }
167
168 sub _prep_for_execute {
169   my $self = shift;
170   my ($op, $extra_bind, $ident, $args) = @_;
171
172   my ($sql, $bind) = $self->next::method (@_);
173
174   if ($op eq 'insert') {
175     my $table = $ident->from;
176
177     my $bind_info = $self->_resolve_column_info(
178       $ident, [map $_->[0], @{$bind}]
179     );
180     my $identity_col = List::Util::first
181       { $bind_info->{$_}{is_auto_increment} }
182       (keys %$bind_info)
183     ;
184
185     if ($identity_col) {
186       $sql = join ("\n",
187         "SET IDENTITY_INSERT $table ON",
188         $sql,
189         "SET IDENTITY_INSERT $table OFF",
190       );
191     }
192     else {
193       $identity_col = List::Util::first
194         { $ident->column_info($_)->{is_auto_increment} }
195         $ident->columns
196       ;
197     }
198
199     if ($identity_col) {
200       $sql =
201         "$sql\n" .
202         $self->_fetch_identity_sql($ident, $identity_col);
203     }
204   }
205
206   return ($sql, $bind);
207 }
208
209 # Stolen from SQLT, with some modifications. This is a makeshift
210 # solution before a sane type-mapping library is available, thus
211 # the 'our' for easy overrides.
212 our %TYPE_MAPPING  = (
213     number    => 'numeric',
214     money     => 'money',
215     varchar   => 'varchar',
216     varchar2  => 'varchar',
217     timestamp => 'datetime',
218     text      => 'varchar',
219     real      => 'double precision',
220     comment   => 'text',
221     bit       => 'bit',
222     tinyint   => 'smallint',
223     float     => 'double precision',
224     serial    => 'numeric',
225     bigserial => 'numeric',
226     boolean   => 'varchar',
227     long      => 'varchar',
228 );
229
230 sub _native_data_type {
231   my ($self, $type) = @_;
232
233   $type = lc $type;
234   $type =~ s/\s* identity//x;
235
236   return uc($TYPE_MAPPING{$type} || $type);
237 }
238
239 sub _fetch_identity_sql {
240   my ($self, $source, $col) = @_;
241
242   return sprintf ("SELECT MAX(%s) FROM %s",
243     map { $self->sql_maker->_quote ($_) } ($col, $source->from)
244   );
245 }
246
247 sub _execute {
248   my $self = shift;
249   my ($op) = @_;
250
251   my ($rv, $sth, @bind) = $self->dbh_do($self->can('_dbh_execute'), @_);
252
253   if ($op eq 'insert') {
254     $self->_identity($sth->fetchrow_array);
255     $sth->finish;
256   }
257
258   return wantarray ? ($rv, $sth, @bind) : $rv;
259 }
260
261 sub last_insert_id { shift->_identity }
262
263 # handles TEXT/IMAGE and transaction for last_insert_id
264 sub insert {
265   my $self = shift;
266   my ($source, $to_insert) = @_;
267
268   my $blob_cols = $self->_remove_blob_cols($source, $to_insert);
269
270   my $identity_col = List::Util::first
271     { $source->column_info($_)->{is_auto_increment} }
272     $source->columns;
273
274   # do we need the horrific SELECT MAX(COL) hack?
275   my $dumb_last_insert_id =
276     (    $identity_col
277       && (not exists $to_insert->{$identity_col})
278       && ($self->_identity_method||'') ne '@@IDENTITY'
279     ) ? 1 : 0;
280
281   my $next = $self->next::can;
282
283   # we are already in a transaction, or there are no blobs
284   # and we don't need the PK - just (try to) do it
285   if ($self->{transaction_depth}
286         || (!$blob_cols && !$dumb_last_insert_id) 
287   ) {
288     return $self->_insert (
289       $source, $to_insert, $blob_cols, $identity_col, $next
290     );
291   }
292
293   # this is tricky: a transaction needs to take place if we need
294   # either a last_insert_id or we will be doing blob insert.
295   # This will happen on a *seperate* connection, thus the local()
296   # acrobatics
297
298   local $self->{_dbh};
299
300   # localize so it appears right if we blow out with an exception
301   local $self->{transaction_depth} = 0;
302
303   $self->_insert_dbh($self->_connect(@{ $self->_dbi_connect_info }))
304     unless $self->_insert_dbh;
305
306   $self->{_dbh} = $self->_insert_dbh;
307   my $guard = $self->txn_scope_guard;
308
309   # _dbh_begin_work in the guard may reconnect,
310   # so we update the accessor just in case
311   $self->_insert_dbh($self->_dbh);
312
313   my $updated_cols = $self->_insert (
314     $source, $to_insert, $blob_cols, $identity_col, $next
315   );
316
317   $guard->commit;
318
319   return $updated_cols;
320
321 }
322
323 sub _insert {
324   my ($self, $source, $to_insert, $blob_cols, $identity_col, $next) = @_;
325
326   my $updated_cols = $self->$next ($source, $to_insert);
327
328   my $final_row = {
329     $identity_col => $self->last_insert_id($source, $identity_col),
330     %$to_insert,
331     %$updated_cols,
332   };
333
334   $self->_insert_blobs ($source, $blob_cols, $final_row) if $blob_cols;
335
336   return $updated_cols;
337 }
338
339 sub update {
340   my $self = shift;
341   my ($source, $fields, $where) = @_;
342
343   my $wantarray = wantarray;
344
345   my $blob_cols = $self->_remove_blob_cols($source, $fields);
346
347 # update+blob update(s) done atomically
348   my $guard = $self->txn_scope_guard if $blob_cols;
349
350   my @res;
351   if ($wantarray) {
352     @res    = $self->next::method(@_);
353   }
354   elsif (defined $wantarray) {
355     $res[0] = $self->next::method(@_);
356   }
357   else {
358     $self->next::method(@_);
359   }
360
361   $self->_update_blobs($source, $blob_cols, $where) if $blob_cols;
362
363   $guard->commit if $guard;
364
365   return $wantarray ? @res : $res[0];
366 }
367
368 sub _remove_blob_cols {
369   my ($self, $source, $fields) = @_;
370
371   my %blob_cols;
372
373   for my $col (keys %$fields) {
374     if ($self->_is_lob_type($source->column_info($col)->{data_type})) {
375       $blob_cols{$col} = delete $fields->{$col};
376       $fields->{$col} = \"''";
377     }
378   }
379
380   return keys %blob_cols ? \%blob_cols : undef;
381 }
382
383 sub _update_blobs {
384   my ($self, $source, $blob_cols, $where) = @_;
385
386   my (@primary_cols) = $source->primary_columns;
387
388   croak "Cannot update TEXT/IMAGE column(s) without a primary key"
389     unless @primary_cols;
390
391 # check if we're updating a single row by PK
392   my $pk_cols_in_where = 0;
393   for my $col (@primary_cols) {
394     $pk_cols_in_where++ if defined $where->{$col};
395   }
396   my @rows;
397
398   if ($pk_cols_in_where == @primary_cols) {
399     my %row_to_update;
400     @row_to_update{@primary_cols} = @{$where}{@primary_cols};
401     @rows = \%row_to_update;
402   } else {
403     my $rs = $source->resultset->search(
404       $where,
405       {
406         result_class => 'DBIx::Class::ResultClass::HashRefInflator',
407         columns => \@primary_cols
408       }
409     );
410     @rows = $rs->all; # statement must finish
411   }
412
413   for my $row (@rows) {
414     $self->_insert_blobs($source, $blob_cols, $row);
415   }
416 }
417
418 sub _insert_blobs {
419   my ($self, $source, $blob_cols, $row) = @_;
420   my $dbh = $self->_get_dbh;
421
422   my $table = $source->from;
423
424   my %row = %$row;
425   my (@primary_cols) = $source->primary_columns;
426
427   croak "Cannot update TEXT/IMAGE column(s) without a primary key"
428     unless @primary_cols;
429
430   if ((grep { defined $row{$_} } @primary_cols) != @primary_cols) {
431     croak "Cannot update TEXT/IMAGE column(s) without primary key values";
432   }
433
434   for my $col (keys %$blob_cols) {
435     my $blob = $blob_cols->{$col};
436
437     my %where = map { ($_, $row{$_}) } @primary_cols;
438     my $cursor = $source->resultset->search(\%where, {
439       select => [$col]
440     })->cursor;
441     $cursor->next;
442     my $sth = $cursor->sth;
443
444     eval {
445       do {
446         $sth->func('CS_GET', 1, 'ct_data_info') or die $sth->errstr;
447       } while $sth->fetch;
448
449       $sth->func('ct_prepare_send') or die $sth->errstr;
450
451       my $log_on_update = $self->_blob_log_on_update;
452       $log_on_update    = 1 if not defined $log_on_update;
453
454       $sth->func('CS_SET', 1, {
455         total_txtlen => length($blob),
456         log_on_update => $log_on_update
457       }, 'ct_data_info') or die $sth->errstr;
458
459       $sth->func($blob, length($blob), 'ct_send_data') or die $sth->errstr;
460
461       $sth->func('ct_finish_send') or die $sth->errstr;
462     };
463     my $exception = $@;
464     $sth->finish if $sth;
465     if ($exception) {
466       if ($self->using_freetds) {
467         croak (
468           'TEXT/IMAGE operation failed, probably because you are using FreeTDS: '
469           . $exception
470         );
471       } else {
472         croak $exception;
473       }
474     }
475   }
476 }
477
478 =head2 connect_call_datetime_setup
479
480 Used as:
481
482   on_connect_call => 'datetime_setup'
483
484 In L<DBIx::Class::Storage::DBI/connect_info> to set:
485
486   $dbh->syb_date_fmt('ISO_strict'); # output fmt: 2004-08-21T14:36:48.080Z
487   $dbh->do('set dateformat mdy');   # input fmt:  08/13/1979 18:08:55.080
488
489 On connection for use with L<DBIx::Class::InflateColumn::DateTime>, using
490 L<DateTime::Format::Sybase>, which you will need to install.
491
492 This works for both C<DATETIME> and C<SMALLDATETIME> columns, although
493 C<SMALLDATETIME> columns only have minute precision.
494
495 =cut
496
497 {
498   my $old_dbd_warned = 0;
499
500   sub connect_call_datetime_setup {
501     my $self = shift;
502     my $dbh = $self->_dbh;
503
504     if ($dbh->can('syb_date_fmt')) {
505       # amazingly, this works with FreeTDS
506       $dbh->syb_date_fmt('ISO_strict');
507     } elsif (not $old_dbd_warned) {
508       carp "Your DBD::Sybase is too old to support ".
509       "DBIx::Class::InflateColumn::DateTime, please upgrade!";
510       $old_dbd_warned = 1;
511     }
512
513     $dbh->do('SET DATEFORMAT mdy');
514
515     1;
516   }
517 }
518
519 sub datetime_parser_type { "DateTime::Format::Sybase" }
520
521 # ->begin_work and such have no effect with FreeTDS but we run them anyway to
522 # let the DBD keep any state it needs to.
523 #
524 # If they ever do start working, the extra statements will do no harm (because
525 # Sybase supports nested transactions.)
526
527 sub _dbh_begin_work {
528   my $self = shift;
529   $self->next::method(@_);
530   if ($self->using_freetds) {
531     $self->_get_dbh->do('BEGIN TRAN');
532   }
533 }
534
535 sub _dbh_commit {
536   my $self = shift;
537   if ($self->using_freetds) {
538     $self->_dbh->do('COMMIT');
539   }
540   return $self->next::method(@_);
541 }
542
543 sub _dbh_rollback {
544   my $self = shift;
545   if ($self->using_freetds) {
546     $self->_dbh->do('ROLLBACK');
547   }
548   return $self->next::method(@_);
549 }
550
551 # savepoint support using ASE syntax
552
553 sub _svp_begin {
554   my ($self, $name) = @_;
555
556   $self->_get_dbh->do("SAVE TRANSACTION $name");
557 }
558
559 # A new SAVE TRANSACTION with the same name releases the previous one.
560 sub _svp_release { 1 }
561
562 sub _svp_rollback {
563   my ($self, $name) = @_;
564
565   $self->_get_dbh->do("ROLLBACK TRANSACTION $name");
566 }
567
568 1;
569
570 =head1 Schema::Loader Support
571
572 There is an experimental branch of L<DBIx::Class::Schema::Loader> that will
573 allow you to dump a schema from most (if not all) versions of Sybase.
574
575 It is available via subversion from:
576
577   http://dev.catalyst.perl.org/repos/bast/branches/DBIx-Class-Schema-Loader/current/
578
579 =head1 FreeTDS
580
581 This driver supports L<DBD::Sybase> compiled against FreeTDS
582 (L<http://www.freetds.org/>) to the best of our ability, however it is
583 recommended that you recompile L<DBD::Sybase> against the Sybase Open Client
584 libraries. They are a part of the Sybase ASE distribution:
585
586 The Open Client FAQ is here:
587 L<http://www.isug.com/Sybase_FAQ/ASE/section7.html>.
588
589 Sybase ASE for Linux (which comes with the Open Client libraries) may be
590 downloaded here: L<http://response.sybase.com/forms/ASE_Linux_Download>.
591
592 To see if you're using FreeTDS check C<< $schema->storage->using_freetds >>, or run:
593
594   perl -MDBI -le 'my $dbh = DBI->connect($dsn, $user, $pass); print $dbh->{syb_oc_version}'
595
596 Some versions of the libraries involved will not support placeholders, in which
597 case the storage will be reblessed to
598 L<DBIx::Class::Storage::DBI::Sybase::NoBindVars>.
599
600 In some configurations, placeholders will work but will throw implicit type
601 conversion errors for anything that's not expecting a string. In such a case,
602 the C<auto_cast> option from L<DBIx::Class::Storage::DBI::AutoCast> is
603 automatically set, which you may enable on connection with
604 L<DBIx::Class::Storage::DBI::AutoCast/connect_call_set_auto_cast>. The type info
605 for the C<CAST>s is taken from the L<DBIx::Class::ResultSource/data_type>
606 definitions in your Result classes, and are mapped to a Sybase type (if it isn't
607 already) using a mapping based on L<SQL::Translator>.
608
609 In other configurations, placeholers will work just as they do with the Sybase
610 Open Client libraries.
611
612 Inserts or updates of TEXT/IMAGE columns will B<NOT> work with FreeTDS.
613
614 =head1 INSERTS WITH PLACEHOLDERS
615
616 With placeholders enabled, inserts are done in a transaction so that there are
617 no concurrency issues with getting the inserted identity value using
618 C<SELECT MAX(col)>, which is the only way to get the C<IDENTITY> value in this
619 mode.
620
621 When using C<DBIx::Class::Storage::DBI::Sybase::NoBindVars> transactions are
622 disabled, as there are no concurrency issues with C<SELECT @@IDENTITY> as it's a
623 session variable.
624
625 =head1 TRANSACTIONS
626
627 Due to limitations of the TDS protocol, L<DBD::Sybase>, or both; you cannot
628 begin a transaction while there are active cursors. An active cursor is, for
629 example, a L<ResultSet|DBIx::Class::ResultSet> that has been executed using
630 C<next> or C<first> but has not been exhausted or
631 L<reset|DBIx::Class::ResultSet/reset>.
632
633 For example, this will not work:
634
635   $schema->txn_do(sub {
636     my $rs = $schema->resultset('Book');
637     while (my $row = $rs->next) {
638       $schema->resultset('MetaData')->create({
639         book_id => $row->id,
640         ...
641       });
642     }
643   });
644
645 Transactions done for inserts in C<AutoCommit> mode when placeholders are in use
646 are not affected, as they use an extra database handle to do the insert.
647
648 Some workarounds:
649
650 =over 4
651
652 =item * use L<DBIx::Class::Storage::DBI::Replicated>
653
654 =item * L<connect|DBIx::Class::Schema/connect> another L<Schema|DBIx::Class::Schema>
655
656 =item * load the data from your cursor with L<DBIx::Class::ResultSet/all>
657
658 =back
659
660 =head1 MAXIMUM CONNECTIONS
661
662 The TDS protocol makes separate connections to the server for active statements
663 in the background. By default the number of such connections is limited to 25,
664 on both the client side and the server side.
665
666 This is a bit too low for a complex L<DBIx::Class> application, so on connection
667 the client side setting is set to C<256> (see L<DBD::Sybase/maxConnect>.) You
668 can override it to whatever setting you like in the DSN.
669
670 See
671 L<http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.help.ase_15.0.sag1/html/sag1/sag1272.htm>
672 for information on changing the setting on the server side.
673
674 =head1 DATES
675
676 See L</connect_call_datetime_setup> to setup date formats
677 for L<DBIx::Class::InflateColumn::DateTime>.
678
679 =head1 TEXT/IMAGE COLUMNS
680
681 L<DBD::Sybase> compiled with FreeTDS will B<NOT> allow you to insert or update
682 C<TEXT/IMAGE> columns.
683
684 Setting C<< $dbh->{LongReadLen} >> will also not work with FreeTDS use either:
685
686   $schema->storage->dbh->do("SET TEXTSIZE $bytes");
687
688 or
689
690   $schema->storage->set_textsize($bytes);
691
692 instead.
693
694 However, the C<LongReadLen> you pass in
695 L<DBIx::Class::Storage::DBI/connect_info> is used to execute the equivalent
696 C<SET TEXTSIZE> command on connection.
697
698 See L</connect_call_blob_setup> for a L<DBIx::Class::Storage::DBI/connect_info>
699 setting you need to work with C<IMAGE> columns.
700
701 =head1 AUTHOR
702
703 See L<DBIx::Class/CONTRIBUTORS>.
704
705 =head1 LICENSE
706
707 You may distribute this code under the same terms as Perl itself.
708
709 =cut
710 # vim:sts=2 sw=2: