=head1 NAME

DBIx::SQLEngine::Docs::ReadMe - Welcome to DBIx::SQLEngine

=head1 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.


=head1 DESCRIPTION

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:

=over 4

=item *

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.

=item *

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.

=item *

Full DBI Access: Accepts arbitrary SQL queries with placeholder
parameters to be passed through, and delegates all other method
calls to a wrapped database handle, allowing access to the entire
DBI API for cases when high-level interfaces are insufficient

=item *

Portability Subclasses: Uses dynamic subclassing (via DBIx::AnyDBD)
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.

=back

=head2 Data-driven SQL

Several methods are responsible for converting their arguments into
commands and placeholder parameters in SQL, the Structured Query
Language.

The various methods whose names being with sql_, like sql_select
and sql_insert, each accept a hash of arguments and combines then
to return a SQL statement and corresponding parameters. Data for
each clause of the statement is accepted in multiple formats to
facilitate query abstraction, often including various strings,
array refs, and hash refs. Each method also supports passing
arbitrary queries through using a C<sql> parameter.

=head2 High-Level Interface

The combined query interface provides a useful high-level idiom to
perform the typical cycle of SQL generation, query execution, and
results fetching, all through a single method call.

The various fetch_*, visit_* and do_* methods that don't end in
_sql, like fetch_select and do_insert, are wrappers that combine
a SQL-generation and a SQL-execution method to provide a simple
ways to perform a query in one call.

=head2 Full DBI Access

Each DBIx::SQLEngine object is implemented as a wrapper around a
database handle provided by DBI, the Perl Database Interface.

Arbitrary queries can be executed, bypassing the SQL generation
capabilities. The methods whose names end in _sql, like fetch_sql
and do_sql, each accept a SQL statement and parameters, pass it to
the DBI data source, and return information about the results of
the query.

=head2 Portability Subclasses

Behind the scenes, different subclasses of SQLEngine are instantiated
depending on the type of server to which you connect, thanks to
DBIx::AnyData. As a result, some range of SQL dialect ideosyncracies
can be compensated for. 

For example, the sql_limit method controls the syntax for select
statements with limit and offset clauses, and both MySQL and Oracle
override this method to use their local syntax.

The only method that's actually provided by the DBIx::SQLEngine
class itself is the new() constructor. All of the other methods
are defined in DBIx::SQLEngine::Driver::Default, or in one of its
automatically-loaded subclasses.

The public interface of DBIx::SQLEngine is shared by all of its
subclasses. The superclass methods aim to produce and perform
generic queries in an database-independent fashion, using standard
SQL syntax.  Subclasses may override these methods to compensate
for idiosyncrasies of their database server or mechanism.  To
facilitate cross-platform subclassing, many of these methods are
implemented by calling combinations of other methods, which may
individually be overridden by subclasses.


=head1 DISTRIBUTION AND INSTALLATION

=head2 Version

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

=head2 Prerequisites

This package requires these other modules and libraries:

  DBI				1.0
  DBIx::AnyDBD			2.0
  Class::MakeMethods		1.003

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.

=head2 Installation

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:

=over 2

=item *

http://search.cpan.org/~evo/

=item *

http://www.cpan.org/modules/by-authors/id/E/EV/EVO

=item *

http://www.evoscript.org/DBIx-SQLEngine/

=back

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.

=over 2

=item *

http://www.freebsd.org/cgi/ports.cgi?query=DBIx-SQLEngine

=item *

http://www.rpmfind.net/linux/rpm2html/search.php?query=perl-DBIx-SQLEngine

=back

=head2 Tested Platforms

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:

=over 2

=item *

http://testers.cpan.org/show/DBIx-SQLEngine.html

=back


=head1 BUGS AND SUPPORT

=head2 Known Problems

Many types of database servers are not yet supported.

Database driver/server combinations that do not support placeholders
will fail.
(http://groups.google.com/groups?selm=dftza.3519%24ol.117790%40news.chello.at)

See L<DBIx::SQLEngine::ToDo> for additional bugs and missing
features.

=head2 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.

=head2 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 
C<http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-SQLEngine> or send mail 
to C<Dist=DBIx-SQLEngine#rt.cpan.org>, replacing the C<#> with C<@>.

=head2 Community

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:

=over 2

=item *

http://cpanratings.perl.org/rate/?distribution=DBIx-SQLEngine

=back

For more general discussion, you may wish to post a message on PerlMonks or the comp.lang.perl.misc newsgroup:

=over 2

=item *

http://www.perlmonks.org/index.pl?node=Seekers%20of%20Perl%20Wisdom

=item *

http://groups.google.com/groups?group=comp.lang.perl.misc

=back

There have been a few small discussions of this module on PerlMonks
and Usenet in the past:

=over 2

=item *

http://groups.google.com/groups?q=dbix+sqlengine+-ports&scoring=d

=item *

http://perlmonks.org/index.pl?node_id=3989&BIT=sqlengine&go=Search

=back


=head1 SEE ALSO 

See L<DBIx::SQLEngine> for interface documentation.

See L<DBIx::SQLEngine::Docs::Changes> for revision history.

See L<DBIx::SQLEngine::Docs::Related> for notes on related modules.


=head1 CREDITS AND COPYRIGHT

=head2 Author

Developed by Matthew Simon Cavalletto at Evolution Softworks.

You may contact the author directly at C<evo@cpan.org> or
C<simonm@cavalletto.org>. More free Perl software is available at
C<www.evoscript.org>.

=head2 Contributors 

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

=head2 Copyright

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.

=head2 License

You may use, modify, and distribute this software under the same terms as Perl.

=cut
