NAME
DBIx::SQLEngine::Docs::ReadMe - About the DBIx::SQLEngine distribution
ABSTRACT
The DBIx::SQLEngine class provides an extended interface for the DBI
database framework. Each SQLEngine object is a wrapper around a DBI
database handle, adding methods that support ad-hoc SQL generation and
query execution in a single call. Dynamic subclassing based on database
server type enables cross-platform portability. An object mapping layer
provides classes for tables, columns, and records.
INTRODUCTION
DBIx::SQLEngine is the latest generation of a toolkit used by the
authors for several years to develop business data applications and
object-relational mapping toolkits. Its goal is to simplify dynamic
query execution with the following capabilities:
* Full DBI Access: Accepts arbitrary SQL queries with placeholder
parameters to be passed through, and delegates any unknown method
calls to the wrapped database handle, allowing access to the entire
DBI API for cases when high-level interfaces are insufficient
* High-Level Interface: Standard query operations are handled by a
single method call each. Error handling is standardized, and routine
annoyances like timed-out connections are retried automatically.
* Data-Driven SQL: Ad-hoc generation of SQL statements from Perl data
structures in a variety of formats; simple hash and array references
are flexibly converted to form clauses in standard SQL query syntax.
* Named Definitions: Enables pre-registration of a collection of names
for sets of connection parameters, and a collection of of names for
queries in either data-driven or plain-SQL formats. The definitions
may include placeholders to be replaced by additional values at
run-time.
* Portability Subclasses: Uses dynamic subclassing to allow
platform-specific support for driver idiosyncrasies and DBMS
workarounds. This release includes subclasses for connections to
MySQL, PostgreSQL, Oracle, and Microsoft SQL servers, as well as for
the standalone SQLite, AnyData, and CSV packages.
* Object Mapping: An optional layer provides classes for Record, Table
and Column objects which fetch and store information from a
SQLEngine. The Schema objects call methods on a SQLEngine to fetch
and store data, while the Record classes create new subclasses to
correspond to rows in a particular table.
SEE ALSO
See the DBIx::SQLEngine manpage for interface documentation.
See the DBIx::SQLEngine::Docs::Changes manpage for revision history.
See the DBIx::SQLEngine::Docs::Related manpage for notes on related
modules.
STATUS
Version
This version is a routine release of DBIx::SQLEngine intended for public
use.
Release Status
This module has been used in a variety of production systems and has
been available on CPAN for over a year, with several other distributions
dependant on it, so it would be fair to say that it is fully released.
However, while the commonly-used portions are well tested, some of the
more obscure combinations of options are less so, and new bug reports do
trickle in occasionally. If you do encounter any problems, please inform
the author and I'll endeavor to patch them promptly.
Additional features have been outlined for future development, but the
intent is support these by adding more options to the declaration
interface, while maintaining backward compatibility.
Tested Platforms
This release has been tested succesfully on the following platforms:
5.6.1 on darwin
Earlier releases have also tested OK on a wide variety of platforms. You
may review the current test results from CPAN-Testers:
* http://testers.cpan.org/show/DBIx-SQLEngine.html
BUGS
Some of the more advanced capabililities have only been added recently,
and have not yet been tested in real-world conditions.
Some types of databases are not yet directly supported. While most of
the default functionality should work with any DBI-accessible data
source, support for complex queries and advanced features will typically
require the addition of a Driver subclass which compensates for local
idiom.
See the DBIx::SQLEngine::ToDo manpage for a list of bugs and missing
features.
DISTRIBUTION
If you encounter any problems, please inform the author and I'll
endeavor to patch them promptly.
CPAN Registration
This module's CPAN registration should read:
Name DSLIP Description
-------------- ----- ---------------------------------------------
DBIx::
::SQLEngine Rdpop Extends DBI with high-level operations
This module should be categorized under group 7, Database Interfaces.
REQUIREMENTS
This package requires these other modules and libraries:
DBI 1.0
DBIx::AnyDBD 2.0
Class::MakeMethods 1.006
Class::MixinFactory 0.9
You must also have at least one working DBD module installed.
If you run into trouble, check that your DBI and DBD modules are
up-to-date; in particular, if you are using DBD::CSV or DBD::AnyData,
make sure you have upgraded to SQL::Statement 1.0 or later.
INSTALLATION
You should be able to install this module using the CPAN shell
interface:
perl -MCPAN -e 'install DBIx::SQLEngine'
Alternately, you may retrieve this package from CPAN
("http://search.cpan.org/~evo/") or from the author's site
("http://www.evoscript.org/DBIx-SQLEngine").
After downloading the distribution, follow the normal procedure to
unpack and install it, using the commands shown below or their local
equivalents on your system:
tar xzf DBIx-SQLEngine-*.tar.gz
cd DBIx-SQLEngine-*
perl Makefile.PL
make test && sudo make install
Furthermore, thanks to the kind generosity of other members of the Perl
community, this distribution is also available repackaged in the FreeBSD
"ports" and Linux "RPM" formats. This may simplify installation for some
users, but be aware that these alternate distributions may lag a few
versions behind the latest release on CPAN.
* http://www.freebsd.org/cgi/ports.cgi?query=DBIx-SQLEngine
* http://www.rpmfind.net/linux/rpm2html/search.php?query=perl-DBIx-SQLEn
gine
SUPPORT
If you have questions or feedback about this module, please feel free to
contact the author at the below address. Although there is no formal
support program, I do attempt to answer email promptly.
I would be particularly interested in any suggestions towards improving
the documentation, correcting any Perl-version or platform dependencies,
as well as general feedback and suggested additions.
Bug reports that contain a failing test case are greatly appreciated,
and suggested patches will be promptly considered for inclusion in
future releases.
To report bugs via the CPAN web tracking system, go to
"http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-SQLEngine" or send mail
to "Dist=DBIx-SQLEngine#rt.cpan.org", replacing "#" with "@".
If you've found this module useful or have feedback about your
experience with it, consider sharing your opinion with other Perl users
by posting your comment to CPAN's ratings system
("http://cpanratings.perl.org/rate/?distribution=DBIx-SQLEngine").
For more general discussion, you may wish to post a message on PerlMonks
("http://perlmonks.org/?node=Seekers%20of%20Perl%20Wisdom") or on the
comp.lang.perl.misc newsgroup
("http://groups.google.com/groups?group=comp.lang.perl.misc").
Some previous discussions of this distribution are archived online on
PerlMonks ("http://perlmonks.org/?node_id=3989&BIT=SQLEngine&go=1") and
the comp.lang.perl.misc newsgroup
("http://groups.google.com/groups?q=dbix+sqlengine+-ports&scoring=d").
AUTHOR
Developed by Matthew Simon Cavalletto at Evolution Softworks. You may
contact the author directly at "evo#cpan.org" or
"simonm#cavalletto.org", replacing "#" with "@".
Custom development and technical consulting are available at
"www.evolutionsoftworks.com". More free Perl software is available at
"www.evoscript.org".
THANKS
Many thanks to the kind people who have contributed code and other
feedback:
Eric Schneider, Evolution Online Systems
E. J. Evans, Evolution Online Systems
Matthew Sheahan, Evolution Online Systems
Eduardo Iturrate, Evolution Online Systems
Ron Savage
Christian Glahn, Innsbruck University
Michael Kroll, Innsbruck University
Peter (Stig) Edwards
SOURCE MATERIAL
Inspiration, tricks, and bits of useful code were mined from these CPAN
modules:
Alzabo by Dave Rolsky
DBIx::AnyDBD by Matt Sergeant
DBIx::Compat by G. Richter
DBIx::Datasource by Ivan Kohler
DBIx::Renderer by Marcel Grunauer
LICENSE
Copyright 2001, 2002, 2003, 2004 Matthew Cavalletto.
Portions copyright 1998, 1999, 2000, 2001 Evolution Online Systems, Inc.
Portions copyright 2002 ZID, Innsbruck University (Austria).
Portions of the documentation are copyright 2003 Ron Savage.
You may use, modify, and distribute this software under the same terms
as Perl.