[svn:dbi] r14025 - in dbi/trunk/lib: DBD DBI/SQL

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