Author: REHSACK Date: Mon May 24 07:41:43 2010 New Revision: 14025 Modified: dbi/trunk/lib/DBD/File.pm dbi/trunk/lib/DBI/SQL/Nano.pm
Log: Add some documentation, especially bugs and limitations Modified: dbi/trunk/lib/DBD/File.pm ============================================================================== --- dbi/trunk/lib/DBD/File.pm (original) +++ dbi/trunk/lib/DBD/File.pm Mon May 24 07:41:43 2010 @@ -952,7 +952,7 @@ SQL engine. See L<DBI> for details on DBI, L<SQL::Statement> for details on -SQL::Statement and L<DBD::CSV> or L<DBD::IniFile> for example +SQL::Statement and L<DBD::CSV>, L<DBD::DBM> or L<DBD::AnyData> for example drivers. =head2 Metadata @@ -1143,7 +1143,19 @@ =back -=head1 KNOWN BUGS +=head1 SQL ENGINES + +DBD::File currently supports two SQL engines: L<DBI::SQL::Nano> and +L<SQL::Statement>. DBI::SQL::Nano supports a I<very> limited subset +of SQL statements, but it might be faster in for some very simple +tasks. SQL::Statement in contrast supports a large subset of ANSI +SQL. + +To use SQL::Statement, the module version 1.28 of SQL::Statement is +a prerequisite and the environment variable C<< DBI_SQL_NANO >> must +not be set on a true value. + +=head1 KNOWN BUGS AND LIMITATIONS =over 8 @@ -1154,6 +1166,29 @@ Windows 95: There's no locking at all (perhaps not so important on MacOS and Windows 95, as there's a single user anyways). +=item * + +The module stores details about the handled tables in a private area +of the driver handle (C<< $drh >>). This data area isn't shared between +different driver instances, so several C<< DBI->connect() >> calls will +cause different table instances and private data areas. + +This data area is filled first time when a table is accessed - either +via an SQL statement or via C<< table_info >> and is not destroyed +before the table is dropped or the driver handle is released. + +=item * + +When used with SQL::Statement and the feature of temporary tables is +used with + + CREATE TEMP TABLE ... + +the table data processing passes DBD::File::Table. No file system calls +will be made, no influence with existing (file based) tables with the same +name will occur. Temporary tables are choosen in favor over file tables, +but they will not covered by C<< table_info >>. + =back =head1 AUTHOR @@ -1167,9 +1202,9 @@ =head1 COPYRIGHT AND LICENSE -Copyright (C) 2009-2010 by H.Merijn Brand & Jens Rehsack -Copyright (C) 2004-2009 by Jeff Zucker -Copyright (C) 1998-2004 by Jochen Wiedmann + Copyright (C) 2009-2010 by H.Merijn Brand & Jens Rehsack + Copyright (C) 2004-2009 by Jeff Zucker + Copyright (C) 1998-2004 by Jochen Wiedmann All rights reserved. Modified: dbi/trunk/lib/DBI/SQL/Nano.pm ============================================================================== --- dbi/trunk/lib/DBI/SQL/Nano.pm (original) +++ dbi/trunk/lib/DBI/SQL/Nano.pm Mon May 24 07:41:43 2010 @@ -917,6 +917,29 @@ relying on DBI::SQL::Nano or SQL::Eval::Table (see L<SQL::Eval> for details) otherwise. +=head1 BUGS AND LIMITATIONS + +There are no know bugs in DBI::SQL::Nano::Statement. If you find a one +and want to report, please see L<DBI> how to report bugs. + +DBI::SQL::Nano::Statement is designed to provide a minimal subset for +executing SQL statements. + +The most important limitation might be the restriction to one table per +statement. This implies, that no JOINs are supported and there can no +foreign key relation between tables. + +The where clause evaluation of DBI::SQL::Nano::Statement is very slow +(SQL::Statement uses a precompiled evaluation). + +INSERT can handle only one row per statement. To insert multiple rows, +use parameters as explained in DBI. + +The parser of DBI::SQL::Nano is very limited and support no extras as +brackets, comments, functions, aggregations etc. + +In contrast to SQL::Statement, temporary tables are not supported. + =head1 ACKNOWLEDGEMENTS Tim Bunce provided the original idea for this module, helped me out of the
