NAME

DBIx::Dictionary - Support for query dictionaries in DBI

SYNOPSIS

  use DBIx::Dictionary;
  
  my $dbh = DBIx::Dictionary->connect(
      $dsn, $user,
      $password,
      {
          DictionaryFile => 'dictionary.ini',
          DictionaryName => 'mysql',
      }
  ) or die DBIx::Dictionary->errstr;
  
  # Will prepare query 'insert' from dictionary
  my $sth = $dbh->prepare('insert')
    or die $dbh->errstr;
  
  $sth->execute(@bind);

ABSTRACT

The DBIx::Dictionary implements a common practice of database development called "query dictionary". It makes the programmer's life easier by adding support to those query dictionaries directly into DBI.

Instead of add common SQL queries inside a program using heredocs or concatenating strings, the programmer can put those queries into a query dictionary and use it all over the application.

This can be also a substitute for underlying smart code, allowing one to construct applications which can be deployed to different database queries without relying on heavy logic to maintain the SQL queries compatible.

With DBIx::Dictionary, one can have a mysql, postgre and oracle sections with specific queries translated to each database dialect.

A typical dictionary.ini content, in Config::General format would be like this:

  <Dictionary mysql>
  
      insert <<SQL
          INSERT INTO sometable VALUES (?, ?)
  SQL

  </Dictionary>

  <Dictionary oracle>

      insert <<SQL
          INSERT INTO sometable VALUES (?, ?)
  SQL

  </Dictionary>

Please be advised that it is planned to support more than one dictionary storage format.

API

DBIx::Dictionary

This class provides the necessary glue to add support for query dictionaries on top of DBI.

connect( $dsn, $username, $password, \%attributes )

This method overloads DBI connect method. It can parse two more attributes other than DBI: DictionaryFile which is a valid path to some Config::General file and DictionaryName is the section name we want to load. Default value for DictionaryName is default.

  my $dbh = DBIx::Dictionary->connect(
      $dsn, 
      $username,
      $password,
      {
          DictionaryFile => 'dictionary.ini',
          DictionaryName => 'mysql',
      }
  );

The above example loads the dictionary file dictionary.ini and will look up the named queries in the section mysql.

connect() can also receive a RootClass attribute as DBI does. It will load the module, and make DBIx::Dictionary::db and DBIx::Dictionary::st subclasses of the given RootClass as well.

This is useful for using named placeholders with DBIx::Placeholder::Named, like:

  my $dbh = DBIx::Dictionary->connect(
      $dsn, 
      $username,
      $password,
      {
          DictionaryFile => 'dictionary.ini',
          RootClass      => 'DBIx::Placeholder::Named',
      }
  );

DBIx::Dictionary::db

This is a DBI::db subclass.

prepare( $query )

prepare() accepts the a query name from dictionary as parameter, otherwise will assume it is a SQL query.

  my $sth;
  $sth = $dbh->prepare('insert_customer');
  $sth = $dbh->prepare($some_dynamic_query);

On the above example, both prepare() statements should work as expected.

DBIx::Dictionary::st

This is a DBI::st subclass.

CAVEATS

DBIx::Dictionary won't work if you use it using the RootClass attribute with DBI. It is expect not to work, because when connecting to database like this:
```
  my $dbh = DBI->connect(
      $dsn,
      $username,
      $password,
      {
          RootClass => 'DBIx::Dictionary, 
      }
  );
```
DBI won't call DBIx::Dictionary::connect(). Calling DBIx::Dictionary::connect() is important because the dictionary setup is done there. This can change in the future, but not for now.

AUTHOR

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

CPAN RT