NAME¶
DBIx::Class::Storage - Generic Storage Handler
DESCRIPTION¶
A base implementation of common Storage methods. For specific information about
DBI-based storage, see DBIx::Class::Storage::DBI.
METHODS¶
new¶
Arguments: $schema
Instantiates the Storage object.
set_schema¶
Used to reset the schema class or object which owns this storage object, such as
during "clone" in DBIx::Class::Schema.
connected¶
Returns true if we have an open storage connection, false if it is not (yet)
open.
disconnect¶
Closes any open storage connection unconditionally.
ensure_connected¶
Initiate a connection to the storage if one isn't already open.
throw_exception¶
Throws an exception - croaks.
txn_do¶
- Arguments: $coderef, @coderef_args?
- Return Value: The return value of $coderef
Executes $coderef with (optional) arguments @coderef_args atomically, returning
its result (if any). If an exception is caught, a rollback is issued and the
exception is rethrown. If the rollback fails, (i.e. throws an exception) an
exception is thrown that includes a "Rollback failed" message.
For example,
my $author_rs = $schema->resultset('Author')->find(1);
my @titles = qw/Night Day It/;
my $coderef = sub {
# If any one of these fails, the entire transaction fails
$author_rs->create_related('books', {
title => $_
}) foreach (@titles);
return $author->books;
};
my $rs;
try {
$rs = $schema->txn_do($coderef);
} catch {
my $error = shift;
# Transaction failed
die "something terrible has happened!"
if ($error =~ /Rollback failed/); # Rollback failed
deal_with_failed_transaction();
};
In a nested transaction (calling
txn_do() from within a
txn_do()
coderef) only the outermost transaction will issue a "txn_commit",
and
txn_do() can be called in void, scalar and list context and it will
behave as expected.
Please note that all of the code in your coderef, including non-DBIx::Class
code, is part of a transaction. This transaction may fail out halfway, or it
may get partially double-executed (in the case that our DB connection failed
halfway through the transaction, in which case we reconnect and restart the
txn). Therefore it is best that any side-effects in your coderef are
idempotent (that is, can be re-executed multiple times and get the same
result), and that you check up on your side-effects in the case of transaction
failure.
txn_begin¶
Starts a transaction.
See the preferred "txn_do" method, which allows for an entire code
block to be executed transactionally.
txn_commit¶
Issues a commit of the current transaction.
It does
not perform an actual storage commit unless there's a DBIx::Class
transaction currently in effect (i.e. you called "txn_begin").
txn_rollback¶
Issues a rollback of the current transaction. A nested rollback will throw a
DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION exception, which allows the
rollback to propagate to the outermost transaction.
svp_begin¶
Arguments: $savepoint_name?
Created a new savepoint using the name provided as argument. If no name is
provided, a random name will be used.
svp_release¶
Arguments: $savepoint_name?
Release the savepoint provided as argument. If none is provided, release the
savepoint created most recently. This will implicitly release all savepoints
created after the one explicitly released as well.
svp_rollback¶
Arguments: $savepoint_name?
Rollback to the savepoint provided as argument. If none is provided, rollback to
the savepoint created most recently. This will implicitly release all
savepoints created after the savepoint we rollback to.
txn_scope_guard¶
An alternative way of transaction handling based on
DBIx::Class::Storage::TxnScopeGuard:
my $txn_guard = $storage->txn_scope_guard;
$row->col1("val1");
$row->update;
$txn_guard->commit;
If an exception occurs, or the guard object otherwise leaves the scope before
"$txn_guard->commit" is called, the transaction will be rolled
back by an explicit "txn_rollback" call. In essence this is akin to
using a "txn_begin"/"txn_commit" pair, without having to
worry about calling "txn_rollback" at the right places. Note that
since there is no defined code closure, there will be no retries and other
magic upon database disconnection. If you need such functionality see
"txn_do".
sql_maker¶
Returns a "sql_maker" object - normally an object of class
"DBIx::Class::SQLMaker".
debug¶
Causes trace information to be emitted on the "debugobj" object. (or
"STDERR" if "debugobj" has not specifically been set).
This is the equivalent to setting "DBIC_TRACE" in your shell
environment.
debugfh¶
Set or retrieve the filehandle used for trace/debug output. This should be an
IO::Handle compatible object (only the "print" method is used.
Initially set to be STDERR - although see information on the DBIC_TRACE
environment variable.
debugobj¶
Sets or retrieves the object used for metric collection. Defaults to an instance
of DBIx::Class::Storage::Statistics that is compatible with the original
method of using a coderef as a callback. See the aforementioned Statistics
class for more information.
debugcb¶
Sets a callback to be executed each time a statement is run; takes a sub
reference. Callback is executed as $sub->($op, $info) where $op is
SELECT/INSERT/UPDATE/DELETE and $info is what would normally be printed.
See "debugobj" for a better way.
cursor_class¶
The cursor class for this Storage object.
deploy¶
Deploy the tables to storage (CREATE TABLE and friends in a SQL-based Storage
class). This would normally be called through "deploy" in
DBIx::Class::Schema.
connect_info¶
The arguments of "connect_info" are always a single array reference,
and are Storage-handler specific.
This is normally accessed via "connection" in DBIx::Class::Schema,
which encapsulates its argument list in an arrayref before calling
"connect_info" here.
select¶
Handle a select statement.
insert¶
Handle an insert statement.
update¶
Handle an update statement.
delete¶
Handle a delete statement.
select_single¶
Performs a select, fetch and return of data - handles a single row only.
columns_info_for¶
Returns metadata for the given source's columns. This is *deprecated*, and will
be removed before 1.0. You should be specifying the metadata yourself if you
need it.
ENVIRONMENT VARIABLES¶
DBIC_TRACE¶
If "DBIC_TRACE" is set then trace information is produced (as when the
"debug" method is set).
If the value is of the form "1=/path/name" then the trace output is
written to the file "/path/name".
This environment variable is checked when the storage object is first created
(when you call connect on your schema). So, run-time changes to this
environment variable will not take effect unless you also re-connect on your
schema.
DBIC_TRACE_PROFILE¶
If "DBIC_TRACE_PROFILE" is set, DBIx::Class::Storage::PrettyPrint will
be used to format the output from "DBIC_TRACE". The value it is set
to is the "profile" that it will be used. If the value is a filename
the file is read with Config::Any and the results are used as the
configuration for tracing. See "new" in SQL::Abstract::Tree for what
that structure should look like.
DBIX_CLASS_STORAGE_DBI_DEBUG¶
Old name for DBIC_TRACE
SEE ALSO¶
DBIx::Class::Storage::DBI - reference storage implementation using SQL::Abstract
and DBI.
AUTHORS¶
Matt S. Trout <mst@shadowcatsystems.co.uk>
Andy Grundman <andy@hybridized.org>
LICENSE¶
You may distribute this code under the same terms as Perl itself.