DBIx::Class specific connection attributes

In addition to the standard DBIconnection 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.

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.

on_connect_do

on_disconnect_do

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.

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.

last_insert_id

_native_data_type

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.

This method is always called after the driver has been determined and a DBI connection has been established. Therefore you can refer to DBI::$constant and/or DBD::$driver::$constant directly, without worrying about loading the correct modules.

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

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:

datetime_parser

datetime_parser_type

build_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

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.

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.