1DBIx::Class::Storage(3)User Contributed Perl DocumentatioDnBIx::Class::Storage(3)
2
3
4

NAME

6       DBIx::Class::Storage - Generic Storage Handler
7

DESCRIPTION

9       A base implementation of common Storage methods.  For specific
10       information about DBI-based storage, see DBIx::Class::Storage::DBI.
11

METHODS

13   new
14       Arguments: $schema
15
16       Instantiates the Storage object.
17
18   set_schema
19       Used to reset the schema class or object which owns this storage
20       object, such as during "clone" in DBIx::Class::Schema.
21
22   connected
23       Returns true if we have an open storage connection, false if it is not
24       (yet) open.
25
26   disconnect
27       Closes any open storage connection unconditionally.
28
29   ensure_connected
30       Initiate a connection to the storage if one isn't already open.
31
32   throw_exception
33       Throws an exception - croaks.
34
35   txn_do
36       Arguments: $coderef, @coderef_args?
37       Return Value: The return value of $coderef
38
39       Executes $coderef with (optional) arguments @coderef_args atomically,
40       returning its result (if any). If an exception is caught, a rollback is
41       issued and the exception is rethrown. If the rollback fails, (i.e.
42       throws an exception) an exception is thrown that includes a "Rollback
43       failed" message.
44
45       For example,
46
47         my $author_rs = $schema->resultset('Author')->find(1);
48         my @titles = qw/Night Day It/;
49
50         my $coderef = sub {
51           # If any one of these fails, the entire transaction fails
52           $author_rs->create_related('books', {
53             title => $_
54           }) foreach (@titles);
55
56           return $author->books;
57         };
58
59         my $rs;
60         try {
61           $rs = $schema->txn_do($coderef);
62         } catch {
63           my $error = shift;
64           # Transaction failed
65           die "something terrible has happened!"
66             if ($error =~ /Rollback failed/);          # Rollback failed
67
68           deal_with_failed_transaction();
69         };
70
71       In a nested transaction (calling txn_do() from within a txn_do()
72       coderef) only the outermost transaction will issue a "txn_commit", and
73       txn_do() can be called in void, scalar and list context and it will
74       behave as expected.
75
76       Please note that all of the code in your coderef, including
77       non-DBIx::Class code, is part of a transaction.  This transaction may
78       fail out halfway, or it may get partially double-executed (in the case
79       that our DB connection failed halfway through the transaction, in which
80       case we reconnect and restart the txn).  Therefore it is best that any
81       side-effects in your coderef are idempotent (that is, can be re-
82       executed multiple times and get the same result), and that you check up
83       on your side-effects in the case of transaction failure.
84
85   txn_begin
86       Starts a transaction.
87
88       See the preferred "txn_do" method, which allows for an entire code
89       block to be executed transactionally.
90
91   txn_commit
92       Issues a commit of the current transaction.
93
94       It does not perform an actual storage commit unless there's a
95       DBIx::Class transaction currently in effect (i.e. you called
96       "txn_begin").
97
98   txn_rollback
99       Issues a rollback of the current transaction. A nested rollback will
100       throw a DBIx::Class::Storage::NESTED_ROLLBACK_EXCEPTION exception,
101       which allows the rollback to propagate to the outermost transaction.
102
103   svp_begin
104       Arguments: $savepoint_name?
105
106       Created a new savepoint using the name provided as argument. If no name
107       is provided, a random name will be used.
108
109   svp_release
110       Arguments: $savepoint_name?
111
112       Release the savepoint provided as argument. If none is provided,
113       release the savepoint created most recently. This will implicitly
114       release all savepoints created after the one explicitly released as
115       well.
116
117   svp_rollback
118       Arguments: $savepoint_name?
119
120       Rollback to the savepoint provided as argument. If none is provided,
121       rollback to the savepoint created most recently. This will implicitly
122       release all savepoints created after the savepoint we rollback to.
123
124   txn_scope_guard
125       An alternative way of transaction handling based on
126       DBIx::Class::Storage::TxnScopeGuard:
127
128        my $txn_guard = $storage->txn_scope_guard;
129
130        $result->col1("val1");
131        $result->update;
132
133        $txn_guard->commit;
134
135       If an exception occurs, or the guard object otherwise leaves the scope
136       before "$txn_guard->commit" is called, the transaction will be rolled
137       back by an explicit "txn_rollback" call. In essence this is akin to
138       using a "txn_begin"/"txn_commit" pair, without having to worry about
139       calling "txn_rollback" at the right places. Note that since there is no
140       defined code closure, there will be no retries and other magic upon
141       database disconnection. If you need such functionality see "txn_do".
142
143   sql_maker
144       Returns a "sql_maker" object - normally an object of class
145       "DBIx::Class::SQLMaker".
146
147   debug
148       Causes trace information to be emitted on the "debugobj" object.  (or
149       "STDERR" if "debugobj" has not specifically been set).
150
151       This is the equivalent to setting "DBIC_TRACE" in your shell
152       environment.
153
154   debugfh
155       An opportunistic proxy to ->debugobj->debugfh(@_)
156
157       If the currently set "debugobj" does not have a "debugfh" method,
158       caling this is a no-op.
159
160   debugobj
161       Sets or retrieves the object used for metric collection. Defaults to an
162       instance of DBIx::Class::Storage::Statistics that is compatible with
163       the original method of using a coderef as a callback.  See the
164       aforementioned Statistics class for more information.
165
166   debugcb
167       Sets a callback to be executed each time a statement is run; takes a
168       sub reference.  Callback is executed as $sub->($op, $info) where $op is
169       SELECT/INSERT/UPDATE/DELETE and $info is what would normally be
170       printed.
171
172       See "debugobj" for a better way.
173
174   cursor_class
175       The cursor class for this Storage object.
176
177   deploy
178       Deploy the tables to storage (CREATE TABLE and friends in a SQL-based
179       Storage class). This would normally be called through "deploy" in
180       DBIx::Class::Schema.
181
182   connect_info
183       The arguments of "connect_info" are always a single array reference,
184       and are Storage-handler specific.
185
186       This is normally accessed via "connection" in DBIx::Class::Schema,
187       which encapsulates its argument list in an arrayref before calling
188       "connect_info" here.
189
190   select
191       Handle a select statement.
192
193   insert
194       Handle an insert statement.
195
196   update
197       Handle an update statement.
198
199   delete
200       Handle a delete statement.
201
202   select_single
203       Performs a select, fetch and return of data - handles a single row
204       only.
205
206   columns_info_for
207       Returns metadata for the given source's columns.  This is *deprecated*,
208       and will be removed before 1.0.  You should be specifying the metadata
209       yourself if you need it.
210

ENVIRONMENT VARIABLES

212   DBIC_TRACE
213       If "DBIC_TRACE" is set then trace information is produced (as when the
214       "debug" method is set).
215
216       If the value is of the form "1=/path/name" then the trace output is
217       written to the file "/path/name".
218
219       This environment variable is checked when the storage object is first
220       created (when you call connect on your schema).  So, run-time changes
221       to this environment variable will not take effect unless you also re-
222       connect on your schema.
223
224   DBIC_TRACE_PROFILE
225       If "DBIC_TRACE_PROFILE" is set,
226       DBIx::Class::Storage::Debug::PrettyTrace will be used to format the
227       output from "DBIC_TRACE".  The value it is set to is the "profile" that
228       it will be used.  If the value is a filename the file is read with
229       Config::Any and the results are used as the configuration for tracing.
230       See "new" in SQL::Abstract::Tree for what that structure should look
231       like.
232
233   DBIX_CLASS_STORAGE_DBI_DEBUG
234       Old name for DBIC_TRACE
235

SEE ALSO

237       DBIx::Class::Storage::DBI - reference storage implementation using DBI
238       and a subclass of SQL::Abstract::Classic ( or similar )
239

FURTHER QUESTIONS?

241       Check the list of additional DBIC resources.
242
244       This module is free software copyright by the DBIx::Class (DBIC)
245       authors. You can redistribute it and/or modify it under the same terms
246       as the DBIx::Class library.
247
248
249
250perl v5.38.0                      2023-07-20           DBIx::Class::Storage(3)
Impressum