Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

DBIx::Class::Storage(3)              User Contributed Perl Documentation             DBIx::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 sideeffects
       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.



perl v5.12.5                                     2011-07-26                          DBIx::Class::Storage(3)