| DBIx::Class::Storage::DBI - DBI storage handler |
DBIx::Class::Storage::DBI - DBI storage handler
This class represents the connection to an RDBMS via the DBI manpage. See the DBIx::Class::Storage manpage for general information. This pod only documents DBI-specific methods and behaviors.
The arguments of connect_info are always a single array reference.
This is normally accessed via connection in the DBIx::Class::Schema manpage, which
encapsulates its argument list in an arrayref before calling
connect_info here.
The arrayref can either contain the same set of arguments one would
normally pass to connect in the DBI manpage, or a lone code reference which returns
a connected database handle. Please note that the the DBI manpage docs
recommend that you always explicitly set AutoCommit to either
0 or 1. the DBIx::Class manpage further recommends that it be set
to 1, and that you perform transactions via our txn_do
method. the DBIx::Class manpage will set it to 1 if you do not do explicitly
set it to zero. This is the default for most DBDs. See below for more
details.
In either case, if the final argument in your connect_info happens
to be a hashref, connect_info will look there for several
connection-specific options:
Note, this only runs if you explicitly call the disconnect manpage on the storage object.
quote_char expects either a single character, in which case is it is placed on either side of the table/column, or an arrayref of length 2 in which case the table/column name is placed between the elements.
For example under MySQL you'd use quote_char => '`', and user SQL Server you'd
use quote_char => [qw/[ ]/].
..
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.
These options can be mixed in with your other the DBI manpage connection attributes, or placed in a seperate hashref after all other normal the DBI manpage connection arguments.
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.
Another Important Note:
DBIC can do some wonderful magic with handling exceptions,
disconnections, and transactions when you use AutoCommit => 1
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 DBIC's magic protections
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.
Examples:
# Simple SQLite connection ->connect_info([ 'dbi:SQLite:./foo.db' ]);
# Connect via subref
->connect_info([ sub { DBI->connect(...) } ]);
# A bit more complicated
->connect_info(
[
'dbi:Pg:dbname=foo',
'postgres',
'my_pg_password',
{ AutoCommit => 1 },
{ quote_char => q{"}, name_sep => q{.} },
]
);
# Equivalent to the previous example
->connect_info(
[
'dbi:Pg:dbname=foo',
'postgres',
'my_pg_password',
{ AutoCommit => 1, quote_char => q{"}, name_sep => q{.} },
]
);
# Subref + DBIC-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,
},
]
);
This method is deprecated in favor of setting via connect_info.
Arguments: $subref, @extra_coderef_args?
Execute the given subref 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
);
Our disconnect method also performs a rollback first if the
database is not in AutoCommit mode.
Returns the dbh - a data base handle of class the DBI manpage.
Handle a SQL select statement.
Returns a the DBI manpage sth (statement handle) for the supplied SQL.
Return the row id of the last insert.
Returns the database driver name.
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.
Creates a SQL file based on the Schema, for each of the specified database types, in the given directory.
Returns the statements used by deploy and deploy in the DBIx::Class::Schema manpage.
The database driver name is given by $type, though the value from
sqlt_type is used if it is not specified.
$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 the DBIx::Class::Schema manpage, the schema name and the $version.
If no $directory is specified then the statements are constructed on the
fly using the SQL::Translator manpage and $version is ignored.
See METHODS in the SQL::Translator manpage for a list of values for $sqlt_args.
Returns the datetime parser class
Defines (returns) the datetime parser class - currently hardwired to the DateTime::Format::MySQL manpage
See datetime_parser
The module defines a set of methods within the DBIC::SQL::Abstract namespace. These build on the SQL::Abstract::Limit manpage to provide the SQL query functions.
The following methods are extended:-
Matt S. Trout <mst@shadowcatsystems.co.uk>
Andy Grundman <andy@hybridized.org>
You may distribute this code under the same terms as Perl itself.
| DBIx::Class::Storage::DBI - DBI storage handler |