1 package DBIx::Class::Storage;
6 use base qw/DBIx::Class/;
9 use DBIx::Class::Exception;
10 use Scalar::Util 'weaken';
12 use DBIx::Class::Storage::TxnScopeGuard;
16 __PACKAGE__->mk_group_accessors('simple' => qw/debug debugobj schema/);
17 __PACKAGE__->mk_group_accessors('inherited' => 'cursor_class');
19 __PACKAGE__->cursor_class('DBIx::Class::Cursor');
21 sub cursor { shift->cursor_class(@_); }
23 package # Hide from PAUSE
24 DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION;
26 use overload '"' => sub {
27 'DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION'
33 return bless $self, $class;
36 package DBIx::Class::Storage;
40 DBIx::Class::Storage - Generic Storage Handler
44 A base implementation of common Storage methods. For specific
45 information about L<DBI>-based storage, see L<DBIx::Class::Storage::DBI>.
53 Instantiates the Storage object.
58 my ($self, $schema) = @_;
60 $self = ref $self if ref $self;
65 $new->set_schema($schema);
67 if (my $profile = $ENV{DBIC_TRACE_PROFILE}) {
68 require DBIx::Class::Storage::Debug::PrettyPrint;
69 if ($profile =~ /^\.?\//) {
71 my $cfg = Config::Any->load_files({ files => [$profile], use_ext => 1 });
73 my ($filename, $config) = %{$cfg->[0]};
74 $debugobj = DBIx::Class::Storage::Debug::PrettyPrint->new($config)
76 $debugobj = DBIx::Class::Storage::Debug::PrettyPrint->new({ profile => $profile })
79 $debugobj = DBIx::Class::Storage::Statistics->new
81 $new->debugobj($debugobj);
83 my $debug_env = $ENV{DBIX_CLASS_STORAGE_DBI_DEBUG}
86 $new->debug(1) if $debug_env;
93 Used to reset the schema class or object which owns this
94 storage object, such as during L<DBIx::Class::Schema/clone>.
99 my ($self, $schema) = @_;
100 $self->schema($schema);
101 weaken $self->{schema} if ref $self->{schema};
106 Returns true if we have an open storage connection, false
107 if it is not (yet) open.
111 sub connected { die "Virtual method!" }
115 Closes any open storage connection unconditionally.
119 sub disconnect { die "Virtual method!" }
121 =head2 ensure_connected
123 Initiate a connection to the storage if one isn't already open.
127 sub ensure_connected { die "Virtual method!" }
129 =head2 throw_exception
131 Throws an exception - croaks.
135 sub throw_exception {
139 $self->schema->throw_exception(@_);
142 DBIx::Class::Exception->throw(@_);
150 =item Arguments: C<$coderef>, @coderef_args?
152 =item Return Value: The return value of $coderef
156 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
157 returning its result (if any). If an exception is caught, a rollback is issued
158 and the exception is rethrown. If the rollback fails, (i.e. throws an
159 exception) an exception is thrown that includes a "Rollback failed" message.
163 my $author_rs = $schema->resultset('Author')->find(1);
164 my @titles = qw/Night Day It/;
167 # If any one of these fails, the entire transaction fails
168 $author_rs->create_related('books', {
170 }) foreach (@titles);
172 return $author->books;
177 $rs = $schema->txn_do($coderef);
181 die "something terrible has happened!" #
182 if ($error =~ /Rollback failed/); # Rollback failed
184 deal_with_failed_transaction();
187 In a nested transaction (calling txn_do() from within a txn_do() coderef) only
188 the outermost transaction will issue a L</txn_commit>, and txn_do() can be
189 called in void, scalar and list context and it will behave as expected.
191 Please note that all of the code in your coderef, including non-DBIx::Class
192 code, is part of a transaction. This transaction may fail out halfway, or
193 it may get partially double-executed (in the case that our DB connection
194 failed halfway through the transaction, in which case we reconnect and
195 restart the txn). Therefore it is best that any side-effects in your coderef
196 are idempotent (that is, can be re-executed multiple times and get the
197 same result), and that you check up on your side-effects in the case of
206 ref $coderef eq 'CODE' or $self->throw_exception
207 ('$coderef must be a CODE reference');
209 my (@return_values, $return_value);
211 $self->txn_begin; # If this throws an exception, no rollback is needed
213 my $wantarray = wantarray; # Need to save this since the context
214 # inside the try{} block is independent
215 # of the context that called txn_do()
220 # Need to differentiate between scalar/list context to allow for
221 # returning a list in scalar context to get the size of the list
224 @return_values = $coderef->(@$args);
225 } elsif (defined $wantarray) {
227 $return_value = $coderef->(@$args);
240 my $exception_class = "DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION";
241 $self->throw_exception($error) # propagate nested rollback
242 if $_ =~ /$exception_class/;
244 $self->throw_exception(
245 "Transaction aborted: $error. Rollback failed: $_"
248 $self->throw_exception($error); # txn failed but rollback succeeded
251 return $wantarray ? @return_values : $return_value;
256 Starts a transaction.
258 See the preferred L</txn_do> method, which allows for
259 an entire code block to be executed transactionally.
263 sub txn_begin { die "Virtual method!" }
267 Issues a commit of the current transaction.
269 It does I<not> perform an actual storage commit unless there's a DBIx::Class
270 transaction currently in effect (i.e. you called L</txn_begin>).
274 sub txn_commit { die "Virtual method!" }
278 Issues a rollback of the current transaction. A nested rollback will
279 throw a L<DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION> exception,
280 which allows the rollback to propagate to the outermost transaction.
284 sub txn_rollback { die "Virtual method!" }
288 Arguments: $savepoint_name?
290 Created a new savepoint using the name provided as argument. If no name
291 is provided, a random name will be used.
295 sub svp_begin { die "Virtual method!" }
299 Arguments: $savepoint_name?
301 Release the savepoint provided as argument. If none is provided,
302 release the savepoint created most recently. This will implicitly
303 release all savepoints created after the one explicitly released as well.
307 sub svp_release { die "Virtual method!" }
311 Arguments: $savepoint_name?
313 Rollback to the savepoint provided as argument. If none is provided,
314 rollback to the savepoint created most recently. This will implicitly
315 release all savepoints created after the savepoint we rollback to.
319 sub svp_rollback { die "Virtual method!" }
323 =head2 txn_scope_guard
325 An alternative way of transaction handling based on
326 L<DBIx::Class::Storage::TxnScopeGuard>:
328 my $txn_guard = $storage->txn_scope_guard;
335 If an exception occurs, or the guard object otherwise leaves the scope
336 before C<< $txn_guard->commit >> is called, the transaction will be rolled
337 back by an explicit L</txn_rollback> call. In essence this is akin to
338 using a L</txn_begin>/L</txn_commit> pair, without having to worry
339 about calling L</txn_rollback> at the right places. Note that since there
340 is no defined code closure, there will be no retries and other magic upon
341 database disconnection. If you need such functionality see L</txn_do>.
345 sub txn_scope_guard {
346 return DBIx::Class::Storage::TxnScopeGuard->new($_[0]);
351 Returns a C<sql_maker> object - normally an object of class
352 C<DBIx::Class::SQLMaker>.
356 sub sql_maker { die "Virtual method!" }
360 Causes trace information to be emitted on the C<debugobj> object.
361 (or C<STDERR> if C<debugobj> has not specifically been set).
363 This is the equivalent to setting L</DBIC_TRACE> in your
368 Set or retrieve the filehandle used for trace/debug output. This should be
369 an IO::Handle compatible object (only the C<print> method is used. Initially
370 set to be STDERR - although see information on the
371 L<DBIC_TRACE> environment variable.
378 if ($self->debugobj->can('debugfh')) {
379 return $self->debugobj->debugfh(@_);
385 Sets or retrieves the object used for metric collection. Defaults to an instance
386 of L<DBIx::Class::Storage::Statistics> that is compatible with the original
387 method of using a coderef as a callback. See the aforementioned Statistics
388 class for more information.
392 Sets a callback to be executed each time a statement is run; takes a sub
393 reference. Callback is executed as $sub->($op, $info) where $op is
394 SELECT/INSERT/UPDATE/DELETE and $info is what would normally be printed.
396 See L<debugobj> for a better way.
403 if ($self->debugobj->can('callback')) {
404 return $self->debugobj->callback(@_);
410 The cursor class for this Storage object.
416 Deploy the tables to storage (CREATE TABLE and friends in a SQL-based
417 Storage class). This would normally be called through
418 L<DBIx::Class::Schema/deploy>.
422 sub deploy { die "Virtual method!" }
426 The arguments of C<connect_info> are always a single array reference,
427 and are Storage-handler specific.
429 This is normally accessed via L<DBIx::Class::Schema/connection>, which
430 encapsulates its argument list in an arrayref before calling
431 C<connect_info> here.
435 sub connect_info { die "Virtual method!" }
439 Handle a select statement.
443 sub select { die "Virtual method!" }
447 Handle an insert statement.
451 sub insert { die "Virtual method!" }
455 Handle an update statement.
459 sub update { die "Virtual method!" }
463 Handle a delete statement.
467 sub delete { die "Virtual method!" }
471 Performs a select, fetch and return of data - handles a single row
476 sub select_single { die "Virtual method!" }
478 =head2 columns_info_for
480 Returns metadata for the given source's columns. This
481 is *deprecated*, and will be removed before 1.0. You should
482 be specifying the metadata yourself if you need it.
486 sub columns_info_for { die "Virtual method!" }
488 =head1 ENVIRONMENT VARIABLES
492 If C<DBIC_TRACE> is set then trace information
493 is produced (as when the L<debug> method is set).
495 If the value is of the form C<1=/path/name> then the trace output is
496 written to the file C</path/name>.
498 This environment variable is checked when the storage object is first
499 created (when you call connect on your schema). So, run-time changes
500 to this environment variable will not take effect unless you also
501 re-connect on your schema.
503 =head2 DBIC_TRACE_PROFILE
505 If C<DBIC_TRACE_PROFILE> is set, L<DBIx::Class::Storage::PrettyPrint>
506 will be used to format the output from C<DBIC_TRACE>. The value it
507 is set to is the C<profile> that it will be used. If the value is a
508 filename the file is read with L<Config::Any> and the results are
509 used as the configuration for tracing. See L<SQL::Abstract::Tree/new>
510 for what that structure should look like.
513 =head2 DBIX_CLASS_STORAGE_DBI_DEBUG
515 Old name for DBIC_TRACE
519 L<DBIx::Class::Storage::DBI> - reference storage implementation using
520 SQL::Abstract and DBI.
524 Matt S. Trout <mst@shadowcatsystems.co.uk>
526 Andy Grundman <andy@hybridized.org>
530 You may distribute this code under the same terms as Perl itself.