DBIx::Factory - a simple factory class for DBI database handle

NAME

DBIx::Factory - a simple factory class for DBI database handle

SYNOPSIS

  # ... preparing to use ...

  $ cat > /config/base/dir/oracle/xe.yaml
  userid: bahoo
  passwd: typer
  dsn:    dbi:Oracle:XE
  attr:
    RaiseError:  0
    PrintError:  1
    LongReadLen: 2079152
  # ... and in your script ...

  # as a class method
  my $dbh = DBIx::Factory->get_dbh(
      config_base => "/config/base/dir",
      config_file => "oracle/xe.yaml"
  );

  # or simply...
  # (in this case, $ENV{DBIF_BASE} is used as config_base.
  #  if not also defined $ENV{DBIF_BASE}, the argument specified
  #  is assumed as a relative path from your current directory)
  my $dbh = DBIx::Factory->get_dbh("oracle/xe.yaml");

  # you can also specify it as an absolute path from '/'
  # (and config_base is ignored even if it is specified)
  my $dbh = DBIx::Factory->get_dbh("/config/base/dir/oracle/xe.yaml");

  # or you can even do just like DBI::connect
  my $dbh = DBIx::Factory->get_dbh("dbi:Oracle:XE", "bahoo", "typer");

  # as an instance method
  my $factory = DBIx::Factory->new("/config/base/dir");
  my $dbh     = $factory->get_dbh("oracle/xe.yaml");

  # when you set RaiseError attr to 1 in your config file
  my $dbh = eval { $factory->get_dbh("oracle/xe.yaml") };
  die $@ if $@;

ABSTRACT

When you release applications which use DBI, you're putting the same database connection info into different files every time, aren't you? This module is useful for collecting up those info into a single file, simplifying managing them, and also a little bit simplifies making connection to the databases.

PREPARATION

After installation, you can first decide which directory is the base directory where connection info files reside. Then, you can create file(s) that contain database connection info, one info per one file.

Each connection info can be described in any format which the Config::Any manpage covers, parsed properly according to the file extension, but must contain some items as follows:

  userid
  passwd
  dsn
  attr

These items must be hash keys that contain simple string values, except attr must contain hash for connection attributes such as RaiseError, AutoCommit or so. See SYNOPSIS for a simple example.

Created connection info file(s), you can place them under the base directory. You can create any level of subdirectories (such as "oracle", "host1/mysql" and so on) to simplify managing those files.

You can also place connection info file(s) anywhere else, when you don't decide the base directory. In this case, you would use connection info file(s) by specifying their absolute paths from "/", or relative paths from your current directory.

Besides, you can get connection without any connection info file, by passing args to the get_dbh manpage just like the DBI::connect manpage.

METHODS

new

Creates a new instance of DBIx::Factory. It can take one argument, which is the base directory of the connection info files. If no argument is specified, it assumes that $ENV{DBIF_BASE} or an empty string (which is later assumed as your current directory) are specified as the base directory.

When the get_dbh manpage method is invoked as a class method, new will then be invoked internally.

get_dbh

There are two ways that you can invoke this method. The first is to invoke this method as a class method. Doing so, this method will take either hash argument which contains two keys, config_base (which is the base directory of the connection info files) and config_file (path from config_base to the specific connection info file) with their values, or a simple string value which is used as config_file, while $ENV{DBIF_BASE} or an empty string (if the $ENV is not defined) are used as config_base. Both config_base and config_file are passed to the new manpage method which will then be invoked.

The second way is to invoke this method as an instance method. Doing so, this method will take a single string argument which is used as config_file.

Either way, please note that if you specify an absolute path (which leads with '/') as config_file, then config_base is always ignored.

If the specified connection info file is unreadable, this method will throw an exception. The same is true when RaiseError attribute is on and actually error happened while connecting to the database.

Besides, when invoking as either a class method or an instance method, you can even pass the args just like when you call the DBI::connect manpage.

AUTHOR

Bahootyper, <bahootyper at gmail.com>

BUGS

Please report any bugs or feature requests, or funny english found in this documentation to bug-dbix-factory at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc DBIx::Factory

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Bahootyper.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

 DBIx::Factory - a simple factory class for DBI database handle