/ 
DBIx-Class-0.08099_03
River stage three • 347 direct dependents • 457 total dependents
/ DBIx::Class::Storage

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;
eval {
  $rs = $schema->txn_do($coderef);
};

if ($@) {                                  # Transaction failed
  die "something terrible has happened!"   #
    if ($@ =~ /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.

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 (EXPERIMENTAL)

An alternative way of using transactions to txn_do:

my $txn = $storage->txn_scope_guard;

$row->col1("val1");
$row->update;

$txn->commit;

If a exception occurs, the transaction will be rolled back. This is still very experiemental, and we are not 100% sure it is working right when nested. The onus is on you as the user to make sure you dont forget to call $$txn-commit>.

sql_maker

Returns a sql_maker object - normally an object of class DBIC::SQL::Abstract.

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 ojbect (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.

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.