1 package DBIx::Class::Storage;
6 use base qw/DBIx::Class/;
8 use Scalar::Util qw/weaken/;
9 use Carp::Clan qw/^DBIx::Class/;
12 __PACKAGE__->mk_group_accessors('simple' => qw/debug debugobj schema/);
13 __PACKAGE__->mk_group_accessors('inherited' => 'cursor_class');
15 __PACKAGE__->cursor_class('DBIx::Class::Cursor');
17 sub cursor { shift->cursor_class(@_); }
19 package # Hide from PAUSE
20 DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION;
22 use overload '"' => sub {
23 'DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION'
29 return bless $self, $class;
32 package DBIx::Class::Storage;
36 DBIx::Class::Storage - Generic Storage Handler
40 A base implementation of common Storage methods. For specific
41 information about L<DBI>-based storage, see L<DBIx::Class::Storage::DBI>.
49 Instantiates the Storage object.
54 my ($self, $schema) = @_;
56 $self = ref $self if ref $self;
61 $new->set_schema($schema);
62 $new->debugobj(new DBIx::Class::Storage::Statistics());
66 my $debug_env = $ENV{DBIX_CLASS_STORAGE_DBI_DEBUG}
69 if (defined($debug_env) && ($debug_env =~ /=(.+)$/)) {
70 $fh = IO::File->new($1, 'w')
71 or $new->throw_exception("Cannot open trace file $1");
73 $fh = IO::File->new('>&STDERR');
78 $new->debug(1) if $debug_env;
85 Used to reset the schema class or object which owns this
86 storage object, such as during L<DBIx::Class::Schema/clone>.
91 my ($self, $schema) = @_;
92 $self->schema($schema);
93 weaken($self->{schema}) if ref $self->{schema};
98 Returns true if we have an open storage connection, false
99 if it is not (yet) open.
103 sub connected { die "Virtual method!" }
107 Closes any open storage connection unconditionally.
111 sub disconnect { die "Virtual method!" }
113 =head2 ensure_connected
115 Initiate a connection to the storage if one isn't already open.
119 sub ensure_connected { die "Virtual method!" }
121 =head2 throw_exception
123 Throws an exception - croaks.
127 sub throw_exception {
130 $self->schema->throw_exception(@_) if $self->schema;
138 =item Arguments: C<$coderef>, @coderef_args?
140 =item Return Value: The return value of $coderef
144 Executes C<$coderef> with (optional) arguments C<@coderef_args> atomically,
145 returning its result (if any). If an exception is caught, a rollback is issued
146 and the exception is rethrown. If the rollback fails, (i.e. throws an
147 exception) an exception is thrown that includes a "Rollback failed" message.
151 my $author_rs = $schema->resultset('Author')->find(1);
152 my @titles = qw/Night Day It/;
155 # If any one of these fails, the entire transaction fails
156 $author_rs->create_related('books', {
158 }) foreach (@titles);
160 return $author->books;
165 $rs = $schema->txn_do($coderef);
168 if ($@) { # Transaction failed
169 die "something terrible has happened!" #
170 if ($@ =~ /Rollback failed/); # Rollback failed
172 deal_with_failed_transaction();
175 In a nested transaction (calling txn_do() from within a txn_do() coderef) only
176 the outermost transaction will issue a L</txn_commit>, and txn_do() can be
177 called in void, scalar and list context and it will behave as expected.
179 Please note that all of the code in your coderef, including non-DBIx::Class
180 code, is part of a transaction. This transaction may fail out halfway, or
181 it may get partially double-executed (in the case that our DB connection
182 failed halfway through the transaction, in which case we reconnect and
183 restart the txn). Therefore it is best that any side-effects in your coderef
184 are idempotent (that is, can be re-executed multiple times and get the
185 same result), and that you check up on your side-effects in the case of
191 my ($self, $coderef, @args) = @_;
193 ref $coderef eq 'CODE' or $self->throw_exception
194 ('$coderef must be a CODE reference');
196 my (@return_values, $return_value);
198 $self->txn_begin; # If this throws an exception, no rollback is needed
200 my $wantarray = wantarray; # Need to save this since the context
201 # inside the eval{} block is independent
202 # of the context that called txn_do()
205 # Need to differentiate between scalar/list context to allow for
206 # returning a list in scalar context to get the size of the list
209 @return_values = $coderef->(@args);
210 } elsif (defined $wantarray) {
212 $return_value = $coderef->(@args);
228 my $rollback_error = $@;
229 my $exception_class = "DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION";
230 $self->throw_exception($error) # propagate nested rollback
231 if $rollback_error =~ /$exception_class/;
233 $self->throw_exception(
234 "Transaction aborted: $error. Rollback failed: ${rollback_error}"
237 $self->throw_exception($error); # txn failed but rollback succeeded
241 return $wantarray ? @return_values : $return_value;
246 Starts a transaction.
248 See the preferred L</txn_do> method, which allows for
249 an entire code block to be executed transactionally.
253 sub txn_begin { die "Virtual method!" }
257 Issues a commit of the current transaction.
261 sub txn_commit { die "Virtual method!" }
265 Issues a rollback of the current transaction. A nested rollback will
266 throw a L<DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION> exception,
267 which allows the rollback to propagate to the outermost transaction.
271 sub txn_rollback { die "Virtual method!" }
275 Returns a C<sql_maker> object - normally an object of class
276 C<DBIC::SQL::Abstract>.
280 sub sql_maker { die "Virtual method!" }
284 Causes trace information to be emitted on the C<debugobj> object.
285 (or C<STDERR> if C<debugobj> has not specifically been set).
287 This is the equivalent to setting L</DBIC_TRACE> in your
292 Set or retrieve the filehandle used for trace/debug output. This should be
293 an IO::Handle compatible ojbect (only the C<print> method is used. Initially
294 set to be STDERR - although see information on the
295 L<DBIC_TRACE> environment variable.
302 if ($self->debugobj->can('debugfh')) {
303 return $self->debugobj->debugfh(@_);
309 Sets or retrieves the object used for metric collection. Defaults to an instance
310 of L<DBIx::Class::Storage::Statistics> that is compatible with the original
311 method of using a coderef as a callback. See the aforementioned Statistics
312 class for more information.
316 Sets a callback to be executed each time a statement is run; takes a sub
317 reference. Callback is executed as $sub->($op, $info) where $op is
318 SELECT/INSERT/UPDATE/DELETE and $info is what would normally be printed.
320 See L<debugobj> for a better way.
327 if ($self->debugobj->can('callback')) {
328 return $self->debugobj->callback(@_);
334 The cursor class for this Storage object.
340 Deploy the tables to storage (CREATE TABLE and friends in a SQL-based
341 Storage class). This would normally be called through
342 L<DBIx::Class::Schema/deploy>.
346 sub deploy { die "Virtual method!" }
350 The arguments of C<connect_info> are always a single array reference,
351 and are Storage-handler specific.
353 This is normally accessed via L<DBIx::Class::Schema/connection>, which
354 encapsulates its argument list in an arrayref before calling
355 C<connect_info> here.
359 sub connect_info { die "Virtual method!" }
363 Handle a select statement.
367 sub select { die "Virtual method!" }
371 Handle an insert statement.
375 sub insert { die "Virtual method!" }
379 Handle an update statement.
383 sub update { die "Virtual method!" }
387 Handle a delete statement.
391 sub delete { die "Virtual method!" }
395 Performs a select, fetch and return of data - handles a single row
400 sub select_single { die "Virtual method!" }
402 =head2 columns_info_for
404 Returns metadata for the given source's columns. This
405 is *deprecated*, and will be removed before 1.0. You should
406 be specifying the metadata yourself if you need it.
410 sub columns_info_for { die "Virtual method!" }
412 =head1 ENVIRONMENT VARIABLES
416 If C<DBIC_TRACE> is set then trace information
417 is produced (as when the L<debug> method is set).
419 If the value is of the form C<1=/path/name> then the trace output is
420 written to the file C</path/name>.
422 This environment variable is checked when the storage object is first
423 created (when you call connect on your schema). So, run-time changes
424 to this environment variable will not take effect unless you also
425 re-connect on your schema.
427 =head2 DBIX_CLASS_STORAGE_DBI_DEBUG
429 Old name for DBIC_TRACE
433 Matt S. Trout <mst@shadowcatsystems.co.uk>
435 Andy Grundman <andy@hybridized.org>
439 You may distribute this code under the same terms as Perl itself.