.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Storage 3pm"
.TH DBIx::Class::Storage 3pm "2022-05-21" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Storage \- Generic Storage Handler
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A base implementation of common Storage methods.  For specific
information about \s-1DBI\s0\-based storage, see DBIx::Class::Storage::DBI.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Arguments: \f(CW$schema\fR
.PP
Instantiates the Storage object.
.SS "set_schema"
.IX Subsection "set_schema"
Used to reset the schema class or object which owns this
storage object, such as during \*(L"clone\*(R" in DBIx::Class::Schema.
.SS "connected"
.IX Subsection "connected"
Returns true if we have an open storage connection, false
if it is not (yet) open.
.SS "disconnect"
.IX Subsection "disconnect"
Closes any open storage connection unconditionally.
.SS "ensure_connected"
.IX Subsection "ensure_connected"
Initiate a connection to the storage if one isn't already open.
.SS "throw_exception"
.IX Subsection "throw_exception"
Throws an exception \- croaks.
.SS "txn_do"
.IX Subsection "txn_do"
.ie n .IP "Arguments: $coderef, @coderef_args?" 4
.el .IP "Arguments: \f(CW$coderef\fR, \f(CW@coderef_args\fR?" 4
.IX Item "Arguments: $coderef, @coderef_args?"
.PD 0
.ie n .IP "Return Value: The return value of $coderef" 4
.el .IP "Return Value: The return value of \f(CW$coderef\fR" 4
.IX Item "Return Value: The return value of $coderef"
.PD
.PP
Executes \f(CW$coderef\fR with (optional) arguments \f(CW@coderef_args\fR 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 \*(L"Rollback failed\*(R" message.
.PP
For example,
.PP
.Vb 2
\&  my $author_rs = $schema\->resultset(\*(AqAuthor\*(Aq)\->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(\*(Aqbooks\*(Aq, {
\&      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();
\&  };
.Ve
.PP
In a nested transaction (calling \fBtxn_do()\fR from within a \fBtxn_do()\fR coderef) only
the outermost transaction will issue a \*(L"txn_commit\*(R", and \fBtxn_do()\fR can be
called in void, scalar and list context and it will behave as expected.
.PP
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 \s-1DB\s0 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.
.SS "txn_begin"
.IX Subsection "txn_begin"
Starts a transaction.
.PP
See the preferred \*(L"txn_do\*(R" method, which allows for
an entire code block to be executed transactionally.
.SS "txn_commit"
.IX Subsection "txn_commit"
Issues a commit of the current transaction.
.PP
It does \fInot\fR perform an actual storage commit unless there's a DBIx::Class
transaction currently in effect (i.e. you called \*(L"txn_begin\*(R").
.SS "txn_rollback"
.IX Subsection "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.
.SS "svp_begin"
.IX Subsection "svp_begin"
Arguments: \f(CW$savepoint_name\fR?
.PP
Created a new savepoint using the name provided as argument. If no name
is provided, a random name will be used.
.SS "svp_release"
.IX Subsection "svp_release"
Arguments: \f(CW$savepoint_name\fR?
.PP
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.
.SS "svp_rollback"
.IX Subsection "svp_rollback"
Arguments: \f(CW$savepoint_name\fR?
.PP
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.
.SS "txn_scope_guard"
.IX Subsection "txn_scope_guard"
An alternative way of transaction handling based on
DBIx::Class::Storage::TxnScopeGuard:
.PP
.Vb 1
\& my $txn_guard = $storage\->txn_scope_guard;
\&
\& $result\->col1("val1");
\& $result\->update;
\&
\& $txn_guard\->commit;
.Ve
.PP
If an exception occurs, or the guard object otherwise leaves the scope
before \f(CW\*(C`$txn_guard\->commit\*(C'\fR is called, the transaction will be rolled
back by an explicit \*(L"txn_rollback\*(R" call. In essence this is akin to
using a \*(L"txn_begin\*(R"/\*(L"txn_commit\*(R" pair, without having to worry
about calling \*(L"txn_rollback\*(R" 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 \*(L"txn_do\*(R".
.SS "sql_maker"
.IX Subsection "sql_maker"
Returns a \f(CW\*(C`sql_maker\*(C'\fR object \- normally an object of class
\&\f(CW\*(C`DBIx::Class::SQLMaker\*(C'\fR.
.SS "debug"
.IX Subsection "debug"
Causes trace information to be emitted on the \*(L"debugobj\*(R" object.
(or \f(CW\*(C`STDERR\*(C'\fR if \*(L"debugobj\*(R" has not specifically been set).
.PP
This is the equivalent to setting \*(L"\s-1DBIC_TRACE\*(R"\s0 in your
shell environment.
.SS "debugfh"
.IX Subsection "debugfh"
An opportunistic proxy to \->debugobj\->debugfh(@_)

If the currently set \*(L"debugobj\*(R" does not have a \*(L"debugfh\*(R" method, caling
this is a no-op.
.SS "debugobj"
.IX Subsection "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.
.SS "debugcb"
.IX Subsection "debugcb"
Sets a callback to be executed each time a statement is run; takes a sub
reference.  Callback is executed as \f(CW$sub\fR\->($op, \f(CW$info\fR) where \f(CW$op\fR is
\&\s-1SELECT/INSERT/UPDATE/DELETE\s0 and \f(CW$info\fR is what would normally be printed.
.PP
See \*(L"debugobj\*(R" for a better way.
.SS "cursor_class"
.IX Subsection "cursor_class"
The cursor class for this Storage object.
.SS "deploy"
.IX Subsection "deploy"
Deploy the tables to storage (\s-1CREATE TABLE\s0 and friends in a SQL-based
Storage class). This would normally be called through
\&\*(L"deploy\*(R" in DBIx::Class::Schema.
.SS "connect_info"
.IX Subsection "connect_info"
The arguments of \f(CW\*(C`connect_info\*(C'\fR are always a single array reference,
and are Storage-handler specific.
.PP
This is normally accessed via \*(L"connection\*(R" in DBIx::Class::Schema, which
encapsulates its argument list in an arrayref before calling
\&\f(CW\*(C`connect_info\*(C'\fR here.
.SS "select"
.IX Subsection "select"
Handle a select statement.
.SS "insert"
.IX Subsection "insert"
Handle an insert statement.
.SS "update"
.IX Subsection "update"
Handle an update statement.
.SS "delete"
.IX Subsection "delete"
Handle a delete statement.
.SS "select_single"
.IX Subsection "select_single"
Performs a select, fetch and return of data \- handles a single row
only.
.SS "columns_info_for"
.IX Subsection "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.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.SS "\s-1DBIC_TRACE\s0"
.IX Subsection "DBIC_TRACE"
If \f(CW\*(C`DBIC_TRACE\*(C'\fR is set then trace information
is produced (as when the \*(L"debug\*(R" method is set).
.PP
If the value is of the form \f(CW\*(C`1=/path/name\*(C'\fR then the trace output is
written to the file \f(CW\*(C`/path/name\*(C'\fR.
.PP
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.
.SS "\s-1DBIC_TRACE_PROFILE\s0"
.IX Subsection "DBIC_TRACE_PROFILE"
If \f(CW\*(C`DBIC_TRACE_PROFILE\*(C'\fR is set, DBIx::Class::Storage::Debug::PrettyTrace
will be used to format the output from \f(CW\*(C`DBIC_TRACE\*(C'\fR.  The value it
is set to is the \f(CW\*(C`profile\*(C'\fR 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 \*(L"new\*(R" in SQL::Abstract::Tree
for what that structure should look like.
.SS "\s-1DBIX_CLASS_STORAGE_DBI_DEBUG\s0"
.IX Subsection "DBIX_CLASS_STORAGE_DBI_DEBUG"
Old name for \s-1DBIC_TRACE\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBIx::Class::Storage::DBI \- reference storage implementation using
\&\s-1DBI\s0 and a subclass of SQL::Abstract::Classic ( or similar )
.SH "FURTHER QUESTIONS?"
.IX Header "FURTHER QUESTIONS?"
Check the list of additional \s-1DBIC\s0 resources.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This module is free software copyright
by the DBIx::Class (\s-1DBIC\s0) authors. You can
redistribute it and/or modify it under the same terms as the
DBIx::Class library.