DBIx::SQLEngine::Docs::ReadMe - Welcome to DBIx::SQLEngine
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.
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:
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.
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
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.
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.
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.
This version is a routine release of DBIx::SQLEngine intended for public use.
This module's proposed CPAN registration should read:
Name DSLIP Description -------------- ----- --------------------------------------------- DBIx:: ::SQLEngine Rdpop Extends DBI with high-level operations
This package requires these other modules and libraries:
DBI 1.0 DBIx::AnyDBD 2.0 Class::MakeMethods 1.006
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.
You should be able to install this module using the CPAN shell interface:
perl -MCPAN -e 'install DBIx::SQLEngine'
In order for the test to succeed, you must also have at least one working DBD module installed, and must provide a DSN to which the script can connect with permissions to create tables.
Alternately, you may retrieve this package from CPAN or from the author's site:
http://search.cpan.org/~evo/
http://www.cpan.org/modules/by-authors/id/E/EV/EVO
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-SQLEngine
This release has been tested succesfully on the following platforms:
5.6.1 on darwin
You may also review the current test results from CPAN-Testers:
http://testers.cpan.org/show/DBIx-SQLEngine.html
Many types of database servers are not yet supported.
See DBIx::SQLEngine::ToDo for additional bugs and missing features.
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.
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 the # with @.
http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-SQLEngine
Dist=DBIx-SQLEngine#rt.cpan.org
#
@
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 or the comp.lang.perl.misc newsgroup:
http://www.perlmonks.org/index.pl?node=Seekers%20of%20Perl%20Wisdom
http://groups.google.com/groups?group=comp.lang.perl.misc
There have been a few small discussions of this module on PerlMonks and Usenet in the past:
http://groups.google.com/groups?q=dbix+sqlengine+-ports&scoring=d
http://perlmonks.org/index.pl?node_id=3989&BIT=sqlengine&go=Search
See DBIx::SQLEngine for interface documentation.
See DBIx::SQLEngine::Docs::Changes for revision history.
See DBIx::SQLEngine::Docs::Related for notes on related modules.
Developed by Matthew Simon Cavalletto at Evolution Softworks.
You may contact the author directly at evo@cpan.org or simonm@cavalletto.org. More free Perl software is available at www.evoscript.org.
evo@cpan.org
simonm@cavalletto.org
www.evoscript.org
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
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
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.
To install DBIx::SQLEngine, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::SQLEngine
CPAN shell
perl -MCPAN -e shell install DBIx::SQLEngine
For more information on module installation, please visit the detailed CPAN module installation guide.