1 package DBIx::Class::Storage;
6 use base qw/DBIx::Class/;
9 use DBIx::Class::Exception;
10 use Scalar::Util 'weaken';
11 use DBIx::Class::Storage::TxnScopeGuard;
15 __PACKAGE__->mk_group_accessors('simple' => qw/debug schema/);
16 __PACKAGE__->mk_group_accessors('component_class' => 'cursor_class');
18 __PACKAGE__->cursor_class('DBIx::Class::Cursor');
20 sub cursor { shift->cursor_class(@_); }
22 package # Hide from PAUSE
23 DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION;
25 use overload '"' => sub {
26 'DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION'
32 return bless $self, $class;
35 package DBIx::Class::Storage;
39 DBIx::Class::Storage - Generic Storage Handler
43 A base implementation of common Storage methods. For specific
44 information about L<DBI>-based storage, see L<DBIx::Class::Storage::DBI>.
52 Instantiates the Storage object.
57 my ($self, $schema) = @_;
59 $self = ref $self if ref $self;
64 $new->set_schema($schema);
66 if $ENV{DBIX_CLASS_STORAGE_DBI_DEBUG} || $ENV{DBIC_TRACE};
73 Used to reset the schema class or object which owns this
74 storage object, such as during L<DBIx::Class::Schema/clone>.
79 my ($self, $schema) = @_;
80 $self->schema($schema);
81 weaken $self->{schema} if ref $self->{schema};
86 Returns true if we have an open storage connection, false
87 if it is not (yet) open.
91 sub connected { die "Virtual method!" }
95 Closes any open storage connection unconditionally.
99 sub disconnect { die "Virtual method!" }
101 =head2 ensure_connected
103 Initiate a connection to the storage if one isn't already open.
107 sub ensure_connected { die "Virtual method!" }
109 =head2 throw_exception
111 Throws an exception - croaks.
115 sub throw_exception {
118 if (ref $self and $self->schema) {
119 $self->schema->throw_exception(@_);
122 DBIx::Class::Exception->throw(@_);
130 =item Arguments: C<$coderef>, @coderef_args?
132 =item Return Value: The return value of $coderef
136 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
137 returning its result (if any). If an exception is caught, a rollback is issued
138 and the exception is rethrown. If the rollback fails, (i.e. throws an
139 exception) an exception is thrown that includes a "Rollback failed" message.
143 my $author_rs = $schema->resultset('Author')->find(1);
144 my @titles = qw/Night Day It/;
147 # If any one of these fails, the entire transaction fails
148 $author_rs->create_related('books', {
150 }) foreach (@titles);
152 return $author->books;
157 $rs = $schema->txn_do($coderef);
161 die "something terrible has happened!" #
162 if ($error =~ /Rollback failed/); # Rollback failed
164 deal_with_failed_transaction();
167 In a nested transaction (calling txn_do() from within a txn_do() coderef) only
168 the outermost transaction will issue a L</txn_commit>, and txn_do() can be
169 called in void, scalar and list context and it will behave as expected.
171 Please note that all of the code in your coderef, including non-DBIx::Class
172 code, is part of a transaction. This transaction may fail out halfway, or
173 it may get partially double-executed (in the case that our DB connection
174 failed halfway through the transaction, in which case we reconnect and
175 restart the txn). Therefore it is best that any side-effects in your coderef
176 are idempotent (that is, can be re-executed multiple times and get the
177 same result), and that you check up on your side-effects in the case of
186 ref $coderef eq 'CODE' or $self->throw_exception
187 ('$coderef must be a CODE reference');
189 my (@return_values, $return_value);
191 $self->txn_begin; # If this throws an exception, no rollback is needed
193 my $wantarray = wantarray; # Need to save this since the context
194 # inside the try{} block is independent
195 # of the context that called txn_do()
200 # Need to differentiate between scalar/list context to allow for
201 # returning a list in scalar context to get the size of the list
204 @return_values = $coderef->(@$args);
205 } elsif (defined $wantarray) {
207 $return_value = $coderef->(@$args);
220 my $exception_class = "DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION";
221 $self->throw_exception($error) # propagate nested rollback
222 if $_ =~ /$exception_class/;
224 $self->throw_exception(
225 "Transaction aborted: $error. Rollback failed: $_"
228 $self->throw_exception($error); # txn failed but rollback succeeded
231 return wantarray ? @return_values : $return_value;
236 Starts a transaction.
238 See the preferred L</txn_do> method, which allows for
239 an entire code block to be executed transactionally.
243 sub txn_begin { die "Virtual method!" }
247 Issues a commit of the current transaction.
249 It does I<not> perform an actual storage commit unless there's a DBIx::Class
250 transaction currently in effect (i.e. you called L</txn_begin>).
254 sub txn_commit { die "Virtual method!" }
258 Issues a rollback of the current transaction. A nested rollback will
259 throw a L<DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION> exception,
260 which allows the rollback to propagate to the outermost transaction.
264 sub txn_rollback { die "Virtual method!" }
268 Arguments: $savepoint_name?
270 Created a new savepoint using the name provided as argument. If no name
271 is provided, a random name will be used.
275 sub svp_begin { die "Virtual method!" }
279 Arguments: $savepoint_name?
281 Release the savepoint provided as argument. If none is provided,
282 release the savepoint created most recently. This will implicitly
283 release all savepoints created after the one explicitly released as well.
287 sub svp_release { die "Virtual method!" }
291 Arguments: $savepoint_name?
293 Rollback to the savepoint provided as argument. If none is provided,
294 rollback to the savepoint created most recently. This will implicitly
295 release all savepoints created after the savepoint we rollback to.
299 sub svp_rollback { die "Virtual method!" }
303 =head2 txn_scope_guard
305 An alternative way of transaction handling based on
306 L<DBIx::Class::Storage::TxnScopeGuard>:
308 my $txn_guard = $storage->txn_scope_guard;
315 If an exception occurs, or the guard object otherwise leaves the scope
316 before C<< $txn_guard->commit >> is called, the transaction will be rolled
317 back by an explicit L</txn_rollback> call. In essence this is akin to
318 using a L</txn_begin>/L</txn_commit> pair, without having to worry
319 about calling L</txn_rollback> at the right places. Note that since there
320 is no defined code closure, there will be no retries and other magic upon
321 database disconnection. If you need such functionality see L</txn_do>.
325 sub txn_scope_guard {
326 return DBIx::Class::Storage::TxnScopeGuard->new($_[0]);
331 Returns a C<sql_maker> object - normally an object of class
332 C<DBIx::Class::SQLMaker>.
336 sub sql_maker { die "Virtual method!" }
340 Causes trace information to be emitted on the L</debugobj> object.
341 (or C<STDERR> if L</debugobj> has not specifically been set).
343 This is the equivalent to setting L</DBIC_TRACE> in your
348 Set or retrieve the filehandle used for trace/debug output. This should be
349 an IO::Handle compatible object (only the C<print> method is used. Initially
350 set to be STDERR - although see information on the
351 L<DBIC_TRACE> environment variable.
358 if ($self->debugobj->can('debugfh')) {
359 return $self->debugobj->debugfh(@_);
365 Sets or retrieves the object used for metric collection. Defaults to an instance
366 of L<DBIx::Class::Storage::Statistics> that is compatible with the original
367 method of using a coderef as a callback. See the aforementioned Statistics
368 class for more information.
376 return $self->{debugobj} = $_[0];
379 $self->{debugobj} ||= do {
380 if (my $profile = $ENV{DBIC_TRACE_PROFILE}) {
381 require DBIx::Class::Storage::Debug::PrettyPrint;
382 if ($profile =~ /^\.?\//) {
386 Config::Any->load_files({ files => [$profile], use_ext => 1 });
388 # sanitize the error message a bit
389 $_ =~ s/at \s+ .+ Storage\.pm \s line \s \d+ $//x;
390 $self->throw_exception("Failure processing \$ENV{DBIC_TRACE_PROFILE}: $_");
393 DBIx::Class::Storage::Debug::PrettyPrint->new(values %{$cfg->[0]});
396 DBIx::Class::Storage::Debug::PrettyPrint->new({ profile => $profile });
400 require DBIx::Class::Storage::Statistics;
401 DBIx::Class::Storage::Statistics->new
408 Sets a callback to be executed each time a statement is run; takes a sub
409 reference. Callback is executed as $sub->($op, $info) where $op is
410 SELECT/INSERT/UPDATE/DELETE and $info is what would normally be printed.
412 See L</debugobj> for a better way.
419 if ($self->debugobj->can('callback')) {
420 return $self->debugobj->callback(@_);
426 The cursor class for this Storage object.
432 Deploy the tables to storage (CREATE TABLE and friends in a SQL-based
433 Storage class). This would normally be called through
434 L<DBIx::Class::Schema/deploy>.
438 sub deploy { die "Virtual method!" }
442 The arguments of C<connect_info> are always a single array reference,
443 and are Storage-handler specific.
445 This is normally accessed via L<DBIx::Class::Schema/connection>, which
446 encapsulates its argument list in an arrayref before calling
447 C<connect_info> here.
451 sub connect_info { die "Virtual method!" }
455 Handle a select statement.
459 sub select { die "Virtual method!" }
463 Handle an insert statement.
467 sub insert { die "Virtual method!" }
471 Handle an update statement.
475 sub update { die "Virtual method!" }
479 Handle a delete statement.
483 sub delete { die "Virtual method!" }
487 Performs a select, fetch and return of data - handles a single row
492 sub select_single { die "Virtual method!" }
494 =head2 columns_info_for
496 Returns metadata for the given source's columns. This
497 is *deprecated*, and will be removed before 1.0. You should
498 be specifying the metadata yourself if you need it.
502 sub columns_info_for { die "Virtual method!" }
504 =head1 ENVIRONMENT VARIABLES
508 If C<DBIC_TRACE> is set then trace information
509 is produced (as when the L</debug> method is set).
511 If the value is of the form C<1=/path/name> then the trace output is
512 written to the file C</path/name>.
514 This environment variable is checked when the storage object is first
515 created (when you call connect on your schema). So, run-time changes
516 to this environment variable will not take effect unless you also
517 re-connect on your schema.
519 =head2 DBIC_TRACE_PROFILE
521 If C<DBIC_TRACE_PROFILE> is set, L<DBIx::Class::Storage::PrettyPrint>
522 will be used to format the output from C<DBIC_TRACE>. The value it
523 is set to is the C<profile> that it will be used. If the value is a
524 filename the file is read with L<Config::Any> and the results are
525 used as the configuration for tracing. See L<SQL::Abstract::Tree/new>
526 for what that structure should look like.
529 =head2 DBIX_CLASS_STORAGE_DBI_DEBUG
531 Old name for DBIC_TRACE
535 L<DBIx::Class::Storage::DBI> - reference storage implementation using
536 SQL::Abstract and DBI.
540 Matt S. Trout <mst@shadowcatsystems.co.uk>
542 Andy Grundman <andy@hybridized.org>
546 You may distribute this code under the same terms as Perl itself.