DBIx::Class::Storage::DBI5.12 man page on Darwin

Man page or keyword search:  
man Server   23457 pages
apropos Keyword Search (all sections)
Output format
Darwin logo
[printable version]

DBIx::Class::Storage::User3Contributed Perl DocumeDBIx::Class::Storage::DBI(3)

NAME
       DBIx::Class::Storage::DBI - DBI storage handler

SYNOPSIS
	 my $schema = MySchema->connect('dbi:SQLite:my.db');

	 $schema->storage->debug(1);

	 my @stuff = $schema->storage->dbh_do(
	   sub {
	     my ($storage, $dbh, @args) = @_;
	     $dbh->do("DROP TABLE authors");
	   },
	   @column_list
	 );

	 $schema->resultset('Book')->search({
	    written_on => $schema->storage->datetime_parser->format_datetime(DateTime->now)
	 });

DESCRIPTION
       This class represents the connection to an RDBMS via DBI.  See
       DBIx::Class::Storage for general information.  This pod only documents
       DBI-specific methods and behaviors.

METHODS
   connect_info
       This method is normally called by "connection" in DBIx::Class::Schema,
       which encapsulates its argument list in an arrayref before passing them
       here.

       The argument list may contain:

       ·   The same 4-element argument set one would normally pass to
	   "connect" in DBI, optionally followed by extra attributes
	   recognized by DBIx::Class:

	     $connect_info_args = [ $dsn, $user, $password, \%dbi_attributes?, \%extra_attributes? ];

       ·   A single code reference which returns a connected DBI database
	   handle optionally followed by extra attributes recognized by
	   DBIx::Class:

	     $connect_info_args = [ sub { DBI->connect (...) }, \%extra_attributes? ];

       ·   A single hashref with all the attributes and the dsn/user/password
	   mixed together:

	     $connect_info_args = [{
	       dsn => $dsn,
	       user => $user,
	       password => $pass,
	       %dbi_attributes,
	       %extra_attributes,
	     }];

	     $connect_info_args = [{
	       dbh_maker => sub { DBI->connect (...) },
	       %dbi_attributes,
	       %extra_attributes,
	     }];

	   This is particularly useful for Catalyst based applications,
	   allowing the following config (Config::General style):

	     <Model::DB>
	       schema_class   App::DB
	       <connect_info>
		 dsn	      dbi:mysql:database=test
		 user	      testuser
		 password     TestPass
		 AutoCommit   1
	       </connect_info>
	     </Model::DB>

	   The "dsn"/"user"/"password" combination can be substituted by the
	   "dbh_maker" key whose value is a coderef that returns a connected
	   DBI database handle

       Please note that the DBI docs recommend that you always explicitly set
       "AutoCommit" to either 0 or 1.  DBIx::Class further recommends that it
       be set to 1, and that you perform transactions via our "txn_do" in
       DBIx::Class::Schema method.  DBIx::Class will set it to 1 if you do not
       do explicitly set it to zero.  This is the default for most DBDs. See
       "DBIx::Class and AutoCommit" for details.

       DBIx::Class specific connection attributes

       In addition to the standard DBI connection attributes, DBIx::Class
       recognizes the following connection options. These options can be mixed
       in with your other DBI connection attributes, or placed in a separate
       hashref ("\%extra_attributes") as shown above.

       Every time "connect_info" is invoked, any previous settings for these
       options will be cleared before setting the new ones, regardless of
       whether any options are specified in the new "connect_info".

       on_connect_do
	   Specifies things to do immediately after connecting or re-
	   connecting to the database.	Its value may contain:

	   a scalar
	       This contains one SQL statement to execute.

	   an array reference
	       This contains SQL statements to execute in order.  Each element
	       contains a string or a code reference that returns a string.

	   a code reference
	       This contains some code to execute.  Unlike code references
	       within an array reference, its return value is ignored.

       on_disconnect_do
	   Takes arguments in the same form as "on_connect_do" and executes
	   them immediately before disconnecting from the database.

	   Note, this only runs if you explicitly call "disconnect" on the
	   storage object.

       on_connect_call
	   A more generalized form of "on_connect_do" that calls the specified
	   "connect_call_METHOD" methods in your storage driver.

	     on_connect_do => 'select 1'

	   is equivalent to:

	     on_connect_call => [ [ do_sql => 'select 1' ] ]

	   Its values may contain:

	   a scalar
	       Will call the "connect_call_METHOD" method.

	   a code reference
	       Will execute "$code->($storage)"

	   an array reference
	       Each value can be a method name or code reference.

	   an array of arrays
	       For each array, the first item is taken to be the
	       "connect_call_" method name or code reference, and the rest are
	       parameters to it.

	   Some predefined storage methods you may use:

	   do_sql
	       Executes a SQL string or a code reference that returns a SQL
	       string. This is what "on_connect_do" and "on_disconnect_do"
	       use.

	       It can take:

	       a scalar
		   Will execute the scalar as SQL.

	       an arrayref
		   Taken to be arguments to "do" in DBI, the SQL string
		   optionally followed by the attributes hashref and bind
		   values.

	       a code reference
		   Will execute "$code->($storage)" and execute the return
		   array refs as above.

	   datetime_setup
	       Execute any statements necessary to initialize the database
	       session to return and accept datetime/timestamp values used
	       with DBIx::Class::InflateColumn::DateTime.

	       Only necessary for some databases, see your specific storage
	       driver for implementation details.

       on_disconnect_call
	   Takes arguments in the same form as "on_connect_call" and executes
	   them immediately before disconnecting from the database.

	   Calls the "disconnect_call_METHOD" methods as opposed to the
	   "connect_call_METHOD" methods called by "on_connect_call".

	   Note, this only runs if you explicitly call "disconnect" on the
	   storage object.

       disable_sth_caching
	   If set to a true value, this option will disable the caching of
	   statement handles via "prepare_cached" in DBI.

       limit_dialect
	   Sets a specific SQL::Abstract::Limit-style limit dialect,
	   overriding the default "sql_limit_dialect" setting of the storage
	   (if any). For a list of available limit dialects see
	   DBIx::Class::SQLMaker::LimitDialects.

       quote_names
	   When true automatically sets "quote_char" and "name_sep" to the
	   characters appropriate for your particular RDBMS. This option is
	   preferred over specifying "quote_char" directly.

       quote_char
	   Specifies what characters to use to quote table and column names.

	   "quote_char" expects either a single character, in which case is it
	   is placed on either side of the table/column name, or an arrayref
	   of length 2 in which case the table/column name is placed between
	   the elements.

	   For example under MySQL you should use "quote_char => '`'", and for
	   SQL Server you should use "quote_char => [qw/[ ]/]".

       name_sep
	   This parameter is only useful in conjunction with "quote_char", and
	   is used to specify the character that separates elements (schemas,
	   tables, columns) from each other. If unspecified it defaults to the
	   most commonly used ".".

       unsafe
	   This Storage driver normally installs its own "HandleError", sets
	   "RaiseError" and "ShowErrorStatement" on, and sets "PrintError" off
	   on all database handles, including those supplied by a coderef.  It
	   does this so that it can have consistent and useful error behavior.

	   If you set this option to a true value, Storage will not do its
	   usual modifications to the database handle's attributes, and
	   instead relies on the settings in your connect_info DBI options (or
	   the values you set in your connection coderef, in the case that you
	   are connecting via coderef).

	   Note that your custom settings can cause Storage to malfunction,
	   especially if you set a "HandleError" handler that suppresses
	   exceptions and/or disable "RaiseError".

       auto_savepoint
	   If this option is true, DBIx::Class will use savepoints when
	   nesting transactions, making it possible to recover from failure in
	   the inner transaction without having to abort all outer
	   transactions.

       cursor_class
	   Use this argument to supply a cursor class other than the default
	   DBIx::Class::Storage::DBI::Cursor.

       Some real-life examples of arguments to "connect_info" and "connect" in
       DBIx::Class::Schema

	 # Simple SQLite connection
	 ->connect_info([ 'dbi:SQLite:./foo.db' ]);

	 # Connect via subref
	 ->connect_info([ sub { DBI->connect(...) } ]);

	 # Connect via subref in hashref
	 ->connect_info([{
	   dbh_maker => sub { DBI->connect(...) },
	   on_connect_do => 'alter session ...',
	 }]);

	 # A bit more complicated
	 ->connect_info(
	   [
	     'dbi:Pg:dbname=foo',
	     'postgres',
	     'my_pg_password',
	     { AutoCommit => 1 },
	     { quote_char => q{"} },
	   ]
	 );

	 # Equivalent to the previous example
	 ->connect_info(
	   [
	     'dbi:Pg:dbname=foo',
	     'postgres',
	     'my_pg_password',
	     { AutoCommit => 1, quote_char => q{"}, name_sep => q{.} },
	   ]
	 );

	 # Same, but with hashref as argument
	 # See parse_connect_info for explanation
	 ->connect_info(
	   [{
	     dsn	 => 'dbi:Pg:dbname=foo',
	     user	 => 'postgres',
	     password	 => 'my_pg_password',
	     AutoCommit	 => 1,
	     quote_char	 => q{"},
	     name_sep	 => q{.},
	   }]
	 );

	 # Subref + DBIx::Class-specific connection options
	 ->connect_info(
	   [
	     sub { DBI->connect(...) },
	     {
		 quote_char => q{`},
		 name_sep => q{@},
		 on_connect_do => ['SET search_path TO myschema,otherschema,public'],
		 disable_sth_caching => 1,
	     },
	   ]
	 );

   on_connect_do
       This method is deprecated in favour of setting via "connect_info".

   on_disconnect_do
       This method is deprecated in favour of setting via "connect_info".

   dbh_do
       Arguments: ($subref | $method_name), @extra_coderef_args?

       Execute the given $subref or $method_name using the new exception-based
       connection management.

       The first two arguments will be the storage object that "dbh_do" was
       called on and a database handle to use.	Any additional arguments will
       be passed verbatim to the called subref as arguments 2 and onwards.

       Using this (instead of $self->_dbh or $self->dbh) ensures correct
       exception handling and reconnection (or failover in future subclasses).

       Your subref should have no side-effects outside of the database, as
       there is the potential for your subref to be partially double-executed
       if the database connection was stale/dysfunctional.

       Example:

	 my @stuff = $schema->storage->dbh_do(
	   sub {
	     my ($storage, $dbh, @cols) = @_;
	     my $cols = join(q{, }, @cols);
	     $dbh->selectrow_array("SELECT $cols FROM foo");
	   },
	   @column_list
	 );

   disconnect
       Our "disconnect" method also performs a rollback first if the database
       is not in "AutoCommit" mode.

   with_deferred_fk_checks
       Arguments: $coderef
       Return Value: The return value of $coderef

       Storage specific method to run the code ref with FK checks deferred or
       in MySQL's case disabled entirely.

   connected
       Arguments: none
       Return Value: 1|0

       Verifies that the current database handle is active and ready to
       execute an SQL statement (e.g. the connection did not get stale, server
       is still answering, etc.) This method is used internally by "dbh".

   dbh
       Returns a $dbh - a data base handle of class DBI. The returned handle
       is guaranteed to be healthy by implicitly calling "connected", and if
       necessary performing a reconnection before returning. Keep in mind that
       this is very expensive on some database engines. Consider using
       "dbh_do" instead.

   select
       Arguments: $ident, $select, $condition, $attrs

       Handle a SQL select statement.

   sql_limit_dialect
       This is an accessor for the default SQL limit dialect used by a
       particular storage driver. Can be overridden by supplying an explicit
       "limit_dialect" to "connect" in DBIx::Class::Schema. For a list of
       available limit dialects see DBIx::Class::SQLMaker::LimitDialects.

   sth
       Arguments: $sql

       Returns a DBI sth (statement handle) for the supplied SQL.

   last_insert_id
       Return the row id of the last insert.

   _native_data_type
       Arguments: $type_name

       This API is EXPERIMENTAL, will almost definitely change in the future,
       and currently only used by ::AutoCast and ::Sybase::ASE.

       The default implementation returns "undef", implement in your Storage
       driver if you need this functionality.

       Should map types from other databases to the native RDBMS type, for
       example "VARCHAR2" to "VARCHAR".

       Types with modifiers should map to the underlying data type. For
       example, "INTEGER AUTO_INCREMENT" should become "INTEGER".

       Composite types should map to the container type, for example
       "ENUM(foo,bar,baz)" becomes "ENUM".

   sqlt_type
       Returns the database driver name.

   bind_attribute_by_data_type
       Given a datatype from column info, returns a database specific bind
       attribute for "$dbh->bind_param($val,$attribute)" or nothing if we will
       let the database planner just handle it.

       Generally only needed for special case column types, like bytea in
       postgres.

   is_datatype_numeric
       Given a datatype from column_info, returns a boolean value indicating
       if the current RDBMS considers it a numeric value. This controls how
       "set_column" in DBIx::Class::Row decides whether to mark the column as
       dirty - when the datatype is deemed numeric a "!=" comparison will be
       performed instead of the usual "eq".

   create_ddl_dir
       Arguments: $schema \@databases, $version, $directory, $preversion,
       \%sqlt_args

       Creates a SQL file based on the Schema, for each of the specified
       database engines in "\@databases" in the given directory.  (note:
       specify SQL::Translator names, not DBI driver names).

       Given a previous version number, this will also create a file
       containing the ALTER TABLE statements to transform the previous schema
       into the current one. Note that these statements may contain "DROP
       TABLE" or "DROP COLUMN" statements that can potentially destroy data.

       The file names are created using the "ddl_filename" method below,
       please override this method in your schema if you would like a
       different file name format. For the ALTER file, the same format is
       used, replacing $version in the name with "$preversion-$version".

       See "METHODS" in SQL::Translator for a list of values for
       "\%sqlt_args".  The most common value for this would be "{
       add_drop_table => 1 }" to have the SQL produced include a "DROP TABLE"
       statement for each table created. For quoting purposes supply
       "quote_table_names" and "quote_field_names".

       If no arguments are passed, then the following default values are
       assumed:

       databases  - ['MySQL', 'SQLite', 'PostgreSQL']
       version	  - $schema->schema_version
       directory  - './'
       preversion - <none>

       By default, "\%sqlt_args" will have

	{ add_drop_table => 1, ignore_constraint_names => 1, ignore_index_names => 1 }

       merged with the hash passed in. To disable any of those features, pass
       in a hashref like the following

	{ ignore_constraint_names => 0, # ... other options }

       WARNING: You are strongly advised to check all SQL files created,
       before applying them.

   deployment_statements
       Arguments: $schema, $type, $version, $directory, $sqlt_args

       Returns the statements used by "deploy" and "deploy" in
       DBIx::Class::Schema.

       The SQL::Translator (not DBI) database driver name can be explicitly
       provided in $type, otherwise the result of "sqlt_type" is used as
       default.

       $directory is used to return statements from files in a previously
       created "create_ddl_dir" directory and is optional. The filenames are
       constructed from "ddl_filename" in DBIx::Class::Schema, the schema name
       and the $version.

       If no $directory is specified then the statements are constructed on
       the fly using SQL::Translator and $version is ignored.

       See "METHODS" in SQL::Translator for a list of values for $sqlt_args.

   datetime_parser
       Returns the datetime parser class

   datetime_parser_type
       Defines the datetime parser class - currently defaults to
       DateTime::Format::MySQL

   build_datetime_parser
       See "datetime_parser"

   is_replicating
       A boolean that reports if a particular DBIx::Class::Storage::DBI is set
       to replicate from a master database.  Default is undef, which is the
       result returned by databases that don't support replication.

   lag_behind_master
       Returns a number that represents a certain amount of lag behind a
       master db when a given storage is replicating.  The number is database
       dependent, but starts at zero and increases with the amount of lag.
       Default in undef

   relname_to_table_alias
       Arguments: $relname, $join_count

       DBIx::Class uses DBIx::Class::Relationship names as table aliases in
       queries.

       This hook is to allow specific DBIx::Class::Storage drivers to change
       the way these aliases are named.

       The default behavior is ""$relname_$join_count" if $join_count > 1",
       otherwise "$relname".

USAGE NOTES
   DBIx::Class and AutoCommit
       DBIx::Class can do some wonderful magic with handling exceptions,
       disconnections, and transactions when you use "AutoCommit => 1" (the
       default) combined with txn_do for transaction support.

       If you set "AutoCommit => 0" in your connect info, then you are always
       in an assumed transaction between commits, and you're telling us you'd
       like to manage that manually.  A lot of the magic protections offered
       by this module will go away.  We can't protect you from exceptions due
       to database disconnects because we don't know anything about how to
       restart your transactions.  You're on your own for handling all sorts
       of exceptional cases if you choose the "AutoCommit => 0" path, just as
       you would be with raw DBI.

AUTHORS
       Matt S. Trout <mst@shadowcatsystems.co.uk>

       Andy Grundman <andy@hybridized.org>

LICENSE
       You may distribute this code under the same terms as Perl itself.

perl v5.12.5			  2011-07-27	  DBIx::Class::Storage::DBI(3)
[top]

List of man pages available for Darwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net