Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DBIx::Class::Storage(3User Contributed Perl DocumentatiDBIx::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 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::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.

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.

perl v5.24.1			  2016-06-20	       DBIx::Class::Storage(3)

NAME | DESCRIPTION | METHODS | ENVIRONMENT VARIABLES | SEE ALSO | FURTHER QUESTIONS? | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DBIx::Class::Storage&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help