DBIx::Class::Storage(3User Contributed Perl DocumentatiDBIx::Class::Storage(3)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::Debug::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.
perl v5.16.2 2012-10-18 DBIx::Class::Storage(3)