/ 
DBIx-Class-0.07999_01
River stage three • 347 direct dependents • 457 total dependents
/ DBIx::Class::Storage::DBI

NAME

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

SYNOPSIS

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

The arguments of connect_info are always a single array reference.

This is normally accessed via "connection" in DBIx::Class::Schema, 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 DBI, or a lone code reference which returns a connected database handle.

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:

on_connect_do

This can be set to an arrayref of literal sql statements, which will be executed immediately after making the connection to the database every time we [re-]connect.

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 the limit dialect. This is useful for JDBC-bridge among others where the remote SQL-dialect cannot be determined by the name of the driver alone.

quote_char

Specifies what characters to use to quote table and column names. If you use this you will want to specify name_sep as well.

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/[ ]/].

name_sep

This only needs to be used in conjunction with quote_char, and is used to specify the charecter that seperates elements (schemas, tables, columns) from each other. In most cases this is simply a ..

These options can be mixed in with your other DBI connection attributes, or placed in a seperate hashref after all other normal DBI 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.

Important note: DBIC expects the returned database handle provided by a subref argument to have RaiseError set on it. If it doesn't, things might not work very well, YMMV. If you don't use a subref, DBIC will force this setting for you anyways. Setting HandleError to anything other than simple exception object wrapper might cause problems too.

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 => 0 },
    { quote_char => q{"}, name_sep => q{.} },
  ]
);

# Equivalent to the previous example
->connect_info(
  [
    'dbi:Pg:dbname=foo',
    'postgres',
    'my_pg_password',
    { AutoCommit => 0, 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,
    },
  ]
);

on_connect_do

This method is deprecated in favor of setting via "connect_info".

dbh_do

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
);

disconnect

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

dbh

Returns the dbh - a data base handle of class DBI.

select

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

Handle a SQL select statement.

sth

Arguments: $sql

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

last_insert_id

Return the row id of the last insert.

sqlt_type

Returns the database driver name.

create_ddl_dir (EXPERIMENTAL)

Arguments: $schema \@databases, $version, $directory, $sqlt_args

Creates a SQL file based on the Schema, for each of the specified database types, in the given directory.

Note that this feature is currently EXPERIMENTAL and may not work correctly across all databases, or fully handle complex relationships.

deployment_statements

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

Returns the statements used by "deploy" and "deploy" in DBIx::Class::Schema. 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 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 (returns) the datetime parser class - currently hardwired to DateTime::Format::MySQL

build_datetime_parser

See "datetime_parser"

SQL METHODS

The module defines a set of methods within the DBIC::SQL::Abstract namespace. These build on SQL::Abstract::Limit to provide the SQL query functions.

The following methods are extended:-

delete
insert
select
update
limit_dialect

See "connect_info" for details. For setting, this method is deprecated in favor of "connect_info".

quote_char

See "connect_info" for details. For setting, this method is deprecated in favor of "connect_info".

name_sep

See "connect_info" for details. For setting, this method is deprecated in favor of "connect_info".

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.