1DBIx::Class::Storage(3)User Contributed Perl DocumentatioDnBIx::Class::Storage(3)
2
6 DBIx::Class::Storage - Generic Storage Handler
7
9 A base implementation of common Storage methods. For specific
10 information about DBI-based storage, see DBIx::Class::Storage::DBI.
11
13 new
14 Arguments: $schema
15 Instantiates the Storage object.
17 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 connected
23 Returns true if we have an open storage connection, false if it is not
24 (yet) open.
25 disconnect
27 Closes any open storage connection unconditionally.
28 ensure_connected
30 Initiate a connection to the storage if one isn't already open.
31 throw_exception
33 Throws an exception - croaks.
34 txn_do
36 Arguments: $coderef, @coderef_args?
37 Return Value: The return value of $coderef
38 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 For example,
46 my $author_rs = $schema->resultset('Author')->find(1);
48 my @titles = qw/Night Day It/;
49 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 return $author->books;
57 };
58 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 deal_with_failed_transaction();
69 };
70 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 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 txn_begin
86 Starts a transaction.
87 See the preferred "txn_do" method, which allows for an entire code
89 block to be executed transactionally.
90 txn_commit
92 Issues a commit of the current transaction.
93 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 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 svp_begin
104 Arguments: $savepoint_name?
105 Created a new savepoint using the name provided as argument. If no name
107 is provided, a random name will be used.
108 svp_release
110 Arguments: $savepoint_name?
111 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 svp_rollback
118 Arguments: $savepoint_name?
119 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 txn_scope_guard
125 An alternative way of transaction handling based on
126 DBIx::Class::Storage::TxnScopeGuard:
127 my $txn_guard = $storage->txn_scope_guard;
129 $result->col1("val1");
131 $result->update;
132 $txn_guard->commit;
134 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 sql_maker
144 Returns a "sql_maker" object - normally an object of class
145 "DBIx::Class::SQLMaker".
146 debug
148 Causes trace information to be emitted on the "debugobj" object. (or
149 "STDERR" if "debugobj" has not specifically been set).
150 This is the equivalent to setting "DBIC_TRACE" in your shell
152 environment.
153 debugfh
155 An opportunistic proxy to ->debugobj->debugfh(@_)
156 If the currently set "debugobj" does not have a "debugfh" method,
158 caling this is a no-op.
159 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 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 See "debugobj" for a better way.
173 cursor_class
175 The cursor class for this Storage object.
176 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 connect_info
183 The arguments of "connect_info" are always a single array reference,
184 and are Storage-handler specific.
185 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 select
191 Handle a select statement.
192 insert
194 Handle an insert statement.
195 update
197 Handle an update statement.
198 delete
200 Handle a delete statement.
201 select_single
203 Performs a select, fetch and return of data - handles a single row
204 only.
205 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
212 DBIC_TRACE
213 If "DBIC_TRACE" is set then trace information is produced (as when the
214 "debug" method is set).
215 If the value is of the form "1=/path/name" then the trace output is
217 written to the file "/path/name".
218 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 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 DBIX_CLASS_STORAGE_DBI_DEBUG
234 Old name for DBIC_TRACE
235
237 DBIx::Class::Storage::DBI - reference storage implementation using DBI
238 and a subclass of SQL::Abstract::Classic ( or similar )
239
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.
247perl v5.38.0 2023-07-20 DBIx::Class::Storage(3)