--- name: "DBIx::Class::Storage" section: "3pm" platform: "linux" package: "libdbix-class-perl" version: "0.082844-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/DBIx::Class::Storage" --- # DBIx::Class::Storage(3pm) Generic Storage Handler ## 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 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; $result->col1("val1"); $result->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 An opportunistic proxy to -\>debugobj-\>debugfh(@\_) If the currently set "debugobj" does not have a "debugfh" method, caling this is a no-op. ### 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::Debug::PrettyTrace 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 DBI and a subclass of SQL::Abstract::Classic ( or similar ) ## FURTHER QUESTIONS? Check the list of additional DBIC resources. ## COPYRIGHT AND LICENSE This module is free software copyright by the DBIx::Class (DBIC) authors. You can redistribute it and/or modify it under the same terms as the DBIx::Class library.