Author: timbo
Date: Wed Jul 28 17:53:41 2004
New Revision: 415
Modified:
dbi/trunk/ToDo
Log:
Updated and reordered to better indicate goals for 2.0
Modified: dbi/trunk/ToDo
==============================================================================
--- dbi/trunk/ToDo (original)
+++ dbi/trunk/ToDo Wed Jul 28 17:53:41 2004
@@ -1,34 +1,129 @@
-*** Changes for DBI v2 ***
---- Changes that may impact applications:
+DBI Version 2
+=============
+
+v2.0 - infrastructure changes, mainly relevant for driver authors
+v2.x - incremental features
-Redefine tables() to default to tables accessible from current
-schema without further qualification.
+Change plan for DBI v2.0
+========================
-Turning AutoCommit on should trigger rollback not commit.
-(ODBC does a commit) This will break code that assumes a commit.
+--- Changes that may impact applications:
+
+Turning AutoCommit on, such as when { local $dbh->{AutoCommit} = 0; ... }
+goes out of scope, should trigger rollback not commit. (ODBC does a commit)
+RISK: This will break code that assumes a commit.
+REMEDY: Explicitly $dbh->commit where required.
Always taint check the $sql for do() and prepare()
if perl is in taint mode (can't be disabled).
-Default TaintIn=>1 in perl taint mode?
-Default TaintOut=>1 in perl taint mode but exclude placeholders?
+RISK: May impact code running with taint enabled but not DBI TaintIn/Out
+Also consider other changes to TaintIn/TaintOut attribute semantics.
-Remove support for "old-style" connect syntax
-(where the driver name is the 4th parameter).
+Alter tables() to default $schema to $dbh->current_schema.
+So tables() will default to returning tables in the current schema.
+(Should include public synonyms)
+RISK: This will impact code requiring tables from multiple schema.
+REMEDY: specify $schema parameter ("%" for all?)
-Change undocumented DBI->err and DBI->errstr methods to warn.
+Add $dbh->current_schema (default to $dbh->{Username})
Remove old informix fudge in tables() (would only impact people
using very old DBD::Informix versions as it now has it's own).
-Increase size of com struct (requires driver rebuild)
-and improve size sanity checks.
+Remove "old-style" connect syntax (where driver name is 4th parameter).
-Reconsider clone() API
+Change undocumented DBI->err and DBI->errstr methods to warn.
+
+--- Internal Changes
+
+Increase size of DBIS (dbistate) structure and imp_xxh.com structures
+and improve size/version sanity checks.
+
+Make ShowErrorStatement=>1 the default when handle is created
+
+Mandate use of dbivport.h and related macros.
+
+Drivers to alter trace level behaviour (no output at low levels
+and use named trace topics).
+
+Mandate that NUM_OF_FIELDS must be set by execute() and
+can't be deferred till $sth->{NUM_OF_FIELDS} or fetch*_*() called.
+
+Add PERL_NO_GET_CONTEXT for multiplicity/threads?
+
+Remove DBIS global and related macros.
+Add dDBIS to be used in functions (eg like dTHR) that can't access it via a imp_xxh
+
+Remove PERL_POLLUTE (so some names will require PL_ or Perl_ prefixes)
+
+Add function pointers for setting fetched field values into DBIS.
+IV, UV, NV, PV and SV?
+Drivers to use this instead of calling sv_setpv (etc) themselves.
+Use internally for set_fbav().
+
+Add function pointer to indicate 'all fields set'.
+Use for both per-field and per-row OnFetch hooks.
+
+New reset() method:
+$dbh->reset - disconnects + discards all state related to the particular connection
+$sth->reset - finish + discards all state related to the particular statement
+Effectively think of a handle as having two parts:
+attributes related to a particular connection/statement (CachedKids/NUM_OF_PARAMS)
+and attribute not-related (AutoCommit/RaiseError).
+The reset method resets the first set but not the second.
+
+Rework handle creation to use methods:
+Maybe $h->new_child(\%handle_attr)
+ dr::connect =>
+ $dbh = $drh->new_child(\%attr);
+ $dbh->connect(...) - calls $dbh->reset()
+& db::prepare =>
+ sub ...::db::prepare {
+ my ($dbh, $sql, $attr) = @_;
+ $sth = $dbh->new_child($attr)
+ my @statements = $dbh->preparse($sql);
+ $sth->{PendingStatements} = [EMAIL PROTECTED] if @statements > 1;
+ $sth->prepare( shift @statements ) or return;
+ return $sth;
+ }
+ sub prepare_cached - no change, calls $dbh->prepare.
+ sub ...::st::prepare {
+ $sth->reset;
+ ...
+ }
+Also need to consider $sth->more_results and its need for reset()-like behaviour.
+
+Need to enable drivers to work with DBI v1 or v2:
+means having both ::db::prepare and ::st::prepare
+In DBI v2 when a driver is loaded the ::db::prepare() method
+will be deleted if a ::st::reset method exists.
+
+Make $DBI::err etc plain (untied) variables.
+Set them in set_err() and when returing from dispatch.
+Clear them, if appropriate, when entering dispatch dispatch().
+
+Unified test suite infrastructure to be reused by all drivers.
+A big project.
+
+-- others --
+
+Fixup @DBD::Foo::ISA and ?->setup_driver issues
+
+Add "imp_xxh_t* imp_xxh;" element to com struct that points back at
+itself so macros can be written to work with imp_??h without needing casts.
+ALso make it cheap to get h from imp_xxh so only imp_xxh needs
+to be passed around.
+
+Add utility function that does SvUTF8_on(sv) if the sv contains
+valid-looking utf8. To be used (perhaps via OnFetch hook) where
+utf8 data is being stored in a non-utf8 aware database.
+
+Remove _not_impl. Alias debug to trace in DBI::(dr/db/st) and remove
+debug() method from internals.
---- Additions and other changes visible to applications:
-Make ShowErrorStatement=>1 the default
+====== LATER ======
Define expected uft8 behaviour. Basically drivers need to set the
uft8 flag on returned strings themselves when appropriate.
@@ -64,46 +159,29 @@
Document DbTypeSubclass (ala DBIx::AnyDBD)
Polish up and document _dbtype_names with an external interface and using get_info.
-Count do()'s and execute()s (that aren't called by do()s) in imp_dbh.
-Make available as an ExecuteCount attribute.
-Reset count in commit/rollback.
-Add InTransaction attribute that defaults to: !AutoCommit && ExecuteCount>0
-Drivers are expected to implement InTransaction if they can.
-In $dbh->DESTROY if !AutoCommit don't rollback&warning
-unless InTransaction is true.
-
FetchHashReuse attrib (=1 or ={}) copy from dbh to sth
and use to optimise fetchrow_hash
--- Changes that may affect driver authors
-Mandate the NUM_OF_FIELDS must be set by execute() and
-can't be deferred till $sth->{NUM_OF_FIELDS} or fetch*_*() called.
-
Add PERL_NO_GET_CONTEXT for multiplicity/threads?
force it for drivers?
And enable xsbypass in dispatch if possible.
-Remove PERL_POLLUTE
-
-Add function pointer for setting fetched field values into DBIS.
-Drivers would use this instead of calling sv_setpv (etc) themselves.
Add log_where() to "trace level set to" log message.
-Add "imp_xxh_t* imp_xxh;" element to com struct that points back at
-itself so macros can be written to work with imp_??h without needing casts.
-
Add bind_col($n, \$foo, { OnFetch => sub { ... } });
Add way to specify default bind_col attributes for each TYPE
-e.g. $dbh->{BindColumnTypes} = {
- SQL_DATE => SQL_DATE,
+e.g. $dbh->{DefaultBindTypeArgs} = {
+ SQL_DATE => { TYPE => SQL_DATE },
SQL_DATETIME => { TYPE => SQL_DATETIME, OnFetch => \&foo },
- }
-
-Add utility function that does SvUTF8_on(sv) if the sv contains
-valid-looking utf8. To be used (perhaps via OnFetch hook) where
-utf8 data is being stored in a non-utf8 aware database.
+ };
+ # effectively automatically adds these as defaults:
+ $sth->bind_col(1, \$foo, {
+ %{ $dbh->{DefaultBindTypeArgs}{$sth->{TYPE}->[1]}, # <==
+ OnFetch => sub { ... }
+ }); # YYYY-MM-DD
Add a handle flag to say that the driver has a hash that maps error
codes into SQLSTATE values. The error event mechanism could check for
@@ -117,26 +195,6 @@
Add dbh active checks to some more sth methods where reasonable.
-Rework handle creation to use methods.
-Maybe $h->new_child(\%override_attr)
- dr::connect =>
- $dbh = $drh->new_child(\%attr);
- $dbh->reset(...) - revert to 'virgin' state
- $dbh->connect(...)
-& db::prepare =>
- $sth = $dbh->new_child(\%attr);
- $sth->reset(...) - revert to 'virgin' state
- $sth->prepare($statement) # once only?
- $sth->close(???) # to 'reset' before a different prepare()?
-need to think through prepare_cached and connect_cached
-and relationship to preparse().
-
-Fixup @DBD::Foo::ISA and ?->setup_driver issues
-
-Sort out DBIcDBISTATE() and DBIS mess. dDBIS?
-Make it cheap to get h from imp_xxh so only imp_xxh needs
-to be passed around?
-
Define consise DBI<>DBD interface with view towards parrot.
note that parrot will use more method calls instead of
'sideways' hooks into DBIS and the driver C code.
@@ -144,27 +202,19 @@
Update DBI::DBD with overview and (at least) recommend Driver.xst strongly.
Find XS drivers that don't use it and talk to authors.
-Review drivers for handling of multiple result sets
-to define common api for all.
-$sth->more_results, maybe via $sth->become($sth2) later (or transplant/swap)
-Also standard way to 'reset/reconfigure' a statement handle.
-
#define a large negative number to mean 'error' from st_execute and
change *.xst to treat either that or -2 as an error. (The -2 is
a transition for old drivers.)
-Consider making $DBI::err etc plain (untied) variables and setting them
-in set_err() and clearing them, if appropriate, in dispatch().
-Requires drivers to use set_err but they'll have to to get full
-error/warn/info semantics anyway.
-
--- Other changes
+Reconsider clone() API
+
See comment under $drh->$connect_meth in DBI.pm about $drh->errstr
Ensure child $h has err reset after connect_cached() or prepare_cached()
or else document that $DBI:err may be true after those methods even
-though they haven't failed. Umm.
+though they haven't failed. Umm. Fixed if $DBI::err isn't tied.
Change t/zz_*_pp.t to be t/zXX_*.t where XX is a combination of:
- 'pp' (for DBI_PUREPERL=2)
@@ -178,9 +228,6 @@
Add OnConnect attribute to connect() esp. for connect_cached()
-Remove _not_impl. Alias debug to trace in DBI::(dr/db/st) ad remove
-debug() method from internals.
-
Macro to get new statement handle for XS code
Trace to tied file handle.
@@ -231,7 +278,7 @@
Consider closer mapping to SQL3 CLI API for driver API.
-Phalanx?
+Phalanx - test coverage
=cut
@@ -289,7 +336,7 @@
keep_error? Perhaps some way to make the current keep_error value
in the dispatch code available to change (via pointer in DBIS?) so
a method can change the value of keep_error that's used when the
-method returns.
+method returns. Fixed since 1.43?
BINDING:
@@ -353,9 +400,6 @@
Add hook to DBI::DBD to write a myconfig.txt file into the
source directory containing key driver and config info.
-test suite
-http://www.mipt.sw.ru/en/products/ots/
-
Add $h->swap_internal_handle($other_h)
dbish - state AutoCommit status clearly at connect time.
@@ -455,16 +499,17 @@
to be sure. [Does perl's looks_like_number() do this already, if not what code do
callers of looks_like_number() use?]
-Record attrib STOREs so can be replayed (or use subclass?)
+Record attrib STOREs so can be replayed/copied to new or cloned handle.
--- Test suite (random thoughts beyond the basic architecture in my head)
one test file = one scenario setup (fixture)
-random order of subtests
cleanup (destroy all data, disconnect etc)
-leak detection after cleanup
-repeat tests with different data types (implies changing fixtures?)
+repeat tests with different data types (CHAR vs NCHAR) (implies changing fixtures?)
+repeat tests with contextual changes (pureperl/proxy/multiplex etc)
test with overloaded and other kinds of 'magical' values
-Good to have 'behavior' tests were the outcome is noted but doesn't trigger failure
-e.g. limitation tests: data values out of range, eg truncation, may or may not
-cause an error depending on the database.
+Good to have 'behavior' tests were the outcome is noted but doesn't
+ trigger failure e.g. limitation tests: data values out of range,
+ eg truncation, may or may not cause an error depending on the database.
+random order of subtests
+leak detection after cleanup
