From: dan <dan@noemail.net>
Date: Wed, 16 Dec 2009 14:49:15 +0000 (+0000)
Subject: Modify some comments in e_fkey.test. No changes to code or tests.
X-Git-Tag: version-3.7.2~699
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=27298ffde43441ceac83c2bdbee3def5741cb95c;p=thirdparty%2Fsqlite.git

Modify some comments in e_fkey.test. No changes to code or tests.

FossilOrigin-Name: 1ba4f412325fc2ce552ad7feecf93891f7f95059
---

diff --git a/manifest b/manifest
index d18a3a4bbc..bfc6dc5643 100644
--- a/manifest
+++ b/manifest
@@ -1,8 +1,5 @@
------BEGIN PGP SIGNED MESSAGE-----
-Hash: SHA1
-
-C Add\sa\sfew\ssimple\sevidence\scomments\sto\sthe\stokenizer.\s\sNo\sfunctional\schanges.
-D 2009-12-14T17:42:13
+C Modify\ssome\scomments\sin\se_fkey.test.\sNo\schanges\sto\scode\sor\stests.
+D 2009-12-16T14:49:16
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in c5827ead754ab32b9585487177c93bb00b9497b3
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -328,7 +325,7 @@ F test/descidx2.test 1310ed1326cdfed4ea2c55169631579f082d174f
 F test/descidx3.test 3394ad4d089335cac743c36a14129d6d931c316f
 F test/diskfull.test 0cede7ef9d8f415d9d3944005c76be7589bb5ebb
 F test/distinctagg.test 1a6ef9c87a58669438fc771450d7a72577417376
-F test/e_fkey.test fd1fcf89badd5f2773d7ac04775b5ff3488eda17
+F test/e_fkey.test 8bc42465248a1b9c8678f397add9b6823ca1dac4
 F test/e_fts3.test ad5d08ca8634b1636c6129d023a1139938b6be05
 F test/enc.test e54531cd6bf941ee6760be041dff19a104c7acea
 F test/enc2.test 6d91a5286f59add0cfcbb2d0da913b76f2242398
@@ -782,14 +779,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P 82b069998e10b1a9a1d5e6bd85877d7b654c78bd
-R a3172048751f7d271ccc9ffdf01b762b
-U drh
-Z eab8865b61b6cb01aedcbd33698aaacb
------BEGIN PGP SIGNATURE-----
-Version: GnuPG v1.4.6 (GNU/Linux)
-
-iD8DBQFLJnj4oxKgR168RlERAr/xAKCBg13EjEm3fYSYDg93HPgdpARWfQCfWlsL
-DwaP+p+ry7CMs8VkaGVaf9M=
-=UzH/
------END PGP SIGNATURE-----
+P 0daec3099d439ce8a8779260b12975f262037bc8
+R 45bbd6fcd1582d1baf524d507b053719
+U dan
+Z 4241a4f431ff69b9b947be1f424e2dae
diff --git a/manifest.uuid b/manifest.uuid
index 11260d5ab4..81911cb5f8 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-0daec3099d439ce8a8779260b12975f262037bc8
\ No newline at end of file
+1ba4f412325fc2ce552ad7feecf93891f7f95059
\ No newline at end of file
diff --git a/test/e_fkey.test b/test/e_fkey.test
index 76095d158b..543ca4b8cd 100644
--- a/test/e_fkey.test
+++ b/test/e_fkey.test
@@ -31,10 +31,9 @@ proc eqp {sql {db db}} { uplevel execsql [list "EXPLAIN QUERY PLAN $sql"] $db }
 ###########################################################################
 
 #-------------------------------------------------------------------------
-# /* EV: R-33710-56344 */
-#
-# Test builds neither OMIT_FOREIGN_KEY or OMIT_TRIGGER defined have 
-# foreign key functionality.
+# EVIDENCE-OF: R-33710-56344 In order to use foreign key constraints in
+# SQLite, the library must be compiled with neither
+# SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER defined.
 #
 ifcapable trigger&&foreignkey {
   do_test e_fkey-1 {
@@ -51,16 +50,26 @@ ifcapable trigger&&foreignkey {
 }
 
 #-------------------------------------------------------------------------
-# /* EV: R-44697-61543 */
-#
 # Test the effects of defining OMIT_TRIGGER but not OMIT_FOREIGN_KEY.
 #
-# /* EV: R-22567-44039 */
-# /* EV: R-41784-13339 */
+# EVIDENCE-OF: R-44697-61543 If SQLITE_OMIT_TRIGGER is defined but
+# SQLITE_OMIT_FOREIGN_KEY is not, then SQLite behaves as it did prior to
+# version 3.6.19 - foreign key definitions are parsed and may be queried
+# using PRAGMA foreign_key_list, but foreign key constraints are not
+# enforced.
 #
 # Specifically, test that "PRAGMA foreign_keys" is a no-op in this case.
 # When using the pragma to query the current setting, 0 rows are returned.
 #
+# EVIDENCE-OF: R-22567-44039 The PRAGMA foreign_keys command is a no-op
+# in this configuration.
+#
+# EVIDENCE-OF: R-41784-13339 Tip: If the command "PRAGMA foreign_keys"
+# returns no data instead of a single row containing "0" or "1", then
+# the version of SQLite you are using does not support foreign keys
+# (either because it is older than 3.6.19 or because it was compiled
+# with SQLITE_OMIT_FOREIGN_KEY or SQLITE_OMIT_TRIGGER defined).
+#
 reset_db
 ifcapable !trigger&&foreignkey {
   do_test e_fkey-2.1 {
@@ -84,10 +93,12 @@ ifcapable !trigger&&foreignkey {
 
 
 #-------------------------------------------------------------------------
-# /* EV: R-58428-36660 */
-#
 # Test the effects of defining OMIT_FOREIGN_KEY.
 #
+# EVIDENCE-OF: R-58428-36660 If OMIT_FOREIGN_KEY is defined, then
+# foreign key definitions cannot even be parsed (attempting to specify a
+# foreign key definition is a syntax error).
+#
 # /* EV: R-58428-36660 */
 #
 # Specifically, test that foreign key constraints cannot even be parsed 
@@ -120,15 +131,16 @@ reset_db
 
 
 #-------------------------------------------------------------------------
-# /* EV: R-07280-60510 */
-#
-# Test that even if foreign keys are supported by the build, they must
-# be enabled using "PRAGMA foreign_keys = ON" (or similar).
-#
-# /* EV: R-59578-04990 */
+# EVIDENCE-OF: R-07280-60510 Assuming the library is compiled with
+# foreign key constraints enabled, it must still be enabled by the
+# application at runtime, using the PRAGMA foreign_keys command.
 #
 # This also tests that foreign key constraints are disabled by default.
 #
+# EVIDENCE-OF: R-59578-04990 Foreign key constraints are disabled by
+# default (for backwards compatibility), so must be enabled separately
+# for each database connection separately.
+#
 drop_all_tables
 do_test e_fkey-4.1 {
   execsql {
@@ -153,13 +165,14 @@ do_test e_fkey-4.2 {
 } {world}
 
 #-------------------------------------------------------------------------
-# /* EV: R-15278-54456 */
-# /* EV: R-11255-19907 */
+# EVIDENCE-OF: R-15278-54456 The application can can also use a PRAGMA
+# foreign_keys statement to determine if foreign keys are currently
+# enabled.
 #
-# Test that the application can use "PRAGMA foreign_keys" to query for
-# whether or not foreign keys are currently enabled. This also tests
-# the example code in section 2 of foreignkeys.in.
+# This also tests the example code in section 2 of foreignkeys.in.
 #
+# EVIDENCE-OF: R-11255-19907
+# 
 reset_db
 do_test e_fkey-5.1 {
   execsql { PRAGMA foreign_keys }
@@ -178,11 +191,14 @@ do_test e_fkey-5.3 {
 } {0}
 
 #-------------------------------------------------------------------------
-# /* EV: R-46649-58537 */
-#
 # Test that it is not possible to enable or disable foreign key support
 # while not in auto-commit mode.
 #
+# EVIDENCE-OF: R-46649-58537 It is not possible to enable or disable
+# foreign key constraints in the middle of a multi-statement transaction
+# (when SQLite is not in autocommit mode). Attempting to do so does not
+# return an error; it simply has no effect.
+#
 reset_db
 do_test e_fkey-6.1 {
   execsql {
@@ -221,10 +237,14 @@ do_test e_fkey-6.4 {
 execsql "PRAGMA foreign_keys = ON"
 
 #-------------------------------------------------------------------------
-# /* EV: R-04042-24825 */
-#
 # Verify that the syntax in the first example in section 1 is valid.
 #
+# EVIDENCE-OF: R-04042-24825 To do so, a foreign key definition may be
+# added by modifying the declaration of the track table to the
+# following: CREATE TABLE track( trackid INTEGER, trackname TEXT,
+# trackartist INTEGER, FOREIGN KEY(trackartist) REFERENCES
+# artist(artistid) );
+#
 do_test e_fkey-7.1 {
   execsql {
     CREATE TABLE artist(
@@ -241,10 +261,9 @@ do_test e_fkey-7.1 {
 } {}
 
 #-------------------------------------------------------------------------
-# /* EV: R-61362-32087 */
-#
-# Attempting to insert a row into the 'track' table that corresponds
-# to no row in the 'artist' table fails.
+# EVIDENCE-OF: R-61362-32087 Attempting to insert a row into the track
+# table that does not correspond to any row in the artist table will
+# fail,
 #
 do_test e_fkey-8.1 {
   catchsql { INSERT INTO track VALUES(1, 'track 1', 1) }
@@ -258,11 +277,12 @@ do_test e_fkey-8.2 {
 } {}
 
 #-------------------------------------------------------------------------
-# /* EV: R-24401-52400 */
-#
 # Attempting to delete a row from the 'artist' table while there are 
 # dependent rows in the track table also fails.
 #
+# EVIDENCE-OF: R-24401-52400 as will attempting to delete a row from the
+# artist table when there exist dependent rows in the track table
+#
 do_test e_fkey-9.1 {
   catchsql { DELETE FROM artist WHERE artistid = 2 }
 } {1 {foreign key constraint failed}}
@@ -274,11 +294,13 @@ do_test e_fkey-9.2 {
 } {}
 
 #-------------------------------------------------------------------------
-# /* EV: R-23980-48859 */
-#
 # If the foreign key column (trackartist) in table 'track' is set to NULL,
 # there is no requirement for a matching row in the 'artist' table.
 #
+# EVIDENCE-OF: R-23980-48859 There is one exception: if the foreign key
+# column in the track table is NULL, then no corresponding entry in the
+# artist table is required.
+#
 do_test e_fkey-10.1 {
   execsql {
     INSERT INTO track VALUES(1, 'track 1', NULL);
@@ -314,6 +336,10 @@ do_test e_fkey-10.5 {
 #   trackartist IS NULL OR 
 #   EXISTS(SELECT 1 FROM artist WHERE artistid=trackartist)
 #
+# EVIDENCE-OF: R-52486-21352 Expressed in SQL, this means that for every
+# row in the track table, the following expression evaluates to true:
+# trackartist IS NULL OR EXISTS(SELECT 1 FROM artist WHERE
+# artistid=trackartist)
 
 # This procedure executes a test case to check that statement 
 # R-52486-21352 is true after executing the SQL statement passed.
@@ -367,6 +393,11 @@ for {set i 0} {$i < 500} {incr i} {
 # Check that a NOT NULL constraint can be added to the example schema
 # to prohibit NULL child keys from being inserted.
 #
+# EVIDENCE-OF: R-42412-59321 Tip: If the application requires a stricter
+# relationship between artist and track, where NULL values are not
+# permitted in the trackartist column, simply add the appropriate "NOT
+# NULL" constraint to the schema.
+#
 drop_all_tables
 do_test e_fkey-12.1 {
   execsql {
@@ -387,7 +418,7 @@ do_test e_fkey-12.2 {
 } {1 {track.trackartist may not be NULL}}
 
 #-------------------------------------------------------------------------
-# /* EV: R-17902-59250 */
+# EVIDENCE-OF: R-17902-59250
 #
 # Test an example from foreignkeys.html.
 #
@@ -431,7 +462,7 @@ do_test e_fkey-13.5 {
 } {}
 
 #-------------------------------------------------------------------------
-# /* EV: R-15034-64331 */
+# EVIDENCE-OF: R-15034-64331
 #
 # Test the second example from the first section of foreignkeys.html.
 #
@@ -460,18 +491,18 @@ do_test e_fkey-14.4 {
 
 
 #-------------------------------------------------------------------------
-# /* EV: R-56032-24923 */
-#
-# Test that a foreign key constraint is satisifed if "for each row in the child
-# table either one or more of the child key columns are NULL, or there exists a
-# row in the parent table for which each parent key column contains a value
-# equal to the value in its associated child key column".
-#
-# /* EV: R-57765-12380 */
+# EVIDENCE-OF: R-56032-24923 The foreign key constraint is satisfied if
+# for each row in the child table either one or more of the child key
+# columns are NULL, or there exists a row in the parent table for which
+# each parent key column contains a value equal to the value in its
+# associated child key column.
 #
-# Test also that the comparison rules are used when testing if there 
+# Test also that the usual comparison rules are used when testing if there 
 # is a matching row in the parent table of a foreign key constraint.
 #
+# EVIDENCE-OF: R-57765-12380 In the above paragraph, the term "equal"
+# means equal when values are compared using the rules specified here.
+#
 drop_all_tables
 do_test e_fkey-15.1 {
   execsql {
@@ -508,11 +539,12 @@ test_efkey_45 8 0 "INSERT INTO chi VALUES(X'31')"
 test_efkey_45 9 1 "INSERT INTO chi VALUES(X'32')"
 
 #-------------------------------------------------------------------------
-# /* EV: R-15796-47513 */
-#
 # Specifically, test that when comparing child and parent key values the
 # default collation sequence of the parent key column is used.
 #
+# EVIDENCE-OF: R-15796-47513 When comparing text values, the collating
+# sequence associated with the parent key column is always used.
+#
 drop_all_tables
 do_test e_fkey-16.1 {
   execsql {
@@ -537,12 +569,14 @@ do_test e_fkey-16.4 {
 } {1 {foreign key constraint failed}}
 
 #-------------------------------------------------------------------------
-# /* EV: R-04240-13860 */
-#
 # Specifically, test that when comparing child and parent key values the
 # affinity of the parent key column is applied to the child key value
 # before the comparison takes place.
 #
+# EVIDENCE-OF: R-04240-13860 When comparing values, if the parent key
+# column has an affinity, then that affinity is applied to the child key
+# value before the comparison is performed.
+#
 drop_all_tables
 do_test e_fkey-17.1 {
   execsql {
@@ -571,18 +605,23 @@ do_test e_fkey-17.4 {
 ###########################################################################
 
 #-------------------------------------------------------------------------
-# /* EV: R-13435-26311 */
-#
 # A parent key must be either a PRIMARY KEY, subject to a UNIQUE 
 # constraint, or have a UNIQUE index created on it.
-# 
-# /* EV: R-00376-39212 */
 #
+# EVIDENCE-OF: R-13435-26311 Usually, the parent key of a foreign key
+# constraint is the primary key of the parent table. If they are not the
+# primary key, then the parent key columns must be collectively subject
+# to a UNIQUE constraint or have a UNIQUE index.
+# 
 # Also test that if a parent key is not subject to a PRIMARY KEY or UNIQUE
 # constraint, but does have a UNIQUE index created on it, then the UNIQUE index
 # must use the default collation sequences associated with the parent key
 # columns.
 #
+# EVIDENCE-OF: R-00376-39212 If the parent key columns have a UNIQUE
+# index, then that index must use the collation sequences that are
+# specified in the CREATE TABLE statement for the parent table.
+#
 drop_all_tables
 do_test e_fkey-18.1 {
   execsql {
@@ -616,21 +655,27 @@ test_efkey_57 9 1 {
 # This block tests an example in foreignkeys.html. Several testable
 # statements refer to this example, as follows
 #
-# /* EV: R-27484-01467 */
+# EVIDENCE-OF: R-27484-01467
 #
 # FK Constraints on child1, child2 and child3 are Ok.
 #
-# /* EV: R-51039-44840 */
+# Problem with FK on child4:
 #
-# Problem with FK on child4.
+# EVIDENCE-OF: R-51039-44840 The foreign key declared as part of table
+# child4 is an error because even though the parent key column is
+# indexed, the index is not UNIQUE.
 #
-# /* EV: R-01060-48788 */
+# Problem with FK on child5:
 #
-# Problem with FK on child5.
+# EVIDENCE-OF: R-01060-48788 The foreign key for table child5 is an
+# error because even though the parent key column has a unique index,
+# the index uses a different collating sequence.
 #
-# /* EV: R-63088-37469 */
+# Problem with FK on child6 and child7:
 #
-# Problem with FK on child6 and child7.
+# EVIDENCE-OF: R-63088-37469 Tables child6 and child7 are incorrect
+# because while both have UNIQUE indices on their parent keys, the keys
+# are not an exact match to the columns of a single UNIQUE index.
 #
 drop_all_tables
 do_test e_fkey-19.1 {
@@ -671,15 +716,33 @@ do_test e_fkey-19.5 {
 } {1 {foreign key mismatch}}
 
 #-------------------------------------------------------------------------
-# /* EV: R-45488-08504 */
-# /* EV: R-48391-38472 */
-# /* EV: R-03108-63659 */
-# /* EV: R-60781-26576 */
-#
 # Test errors in the database schema that are detected while preparing
 # DML statements. The error text for these messages always matches 
 # either "foreign key mismatch" or "no such table*" (using [string match]).
 #
+# EVIDENCE-OF: R-45488-08504 If the database schema contains foreign key
+# errors that require looking at more than one table definition to
+# identify, then those errors are not detected when the tables are
+# created.
+#
+# EVIDENCE-OF: R-48391-38472 Instead, such errors prevent the
+# application from preparing SQL statements that modify the content of
+# the child or parent tables in ways that use the foreign keys.
+#
+# EVIDENCE-OF: R-03108-63659 The English language error message for
+# foreign key DML errors is usually "foreign key mismatch" but can also
+# be "no such table" if the parent table does not exist.
+#
+# EVIDENCE-OF: R-60781-26576 Foreign key DML errors are may be reported
+# if: The parent table does not exist, or The parent key columns named
+# in the foreign key constraint do not exist, or The parent key columns
+# named in the foreign key constraint are not the primary key of the
+# parent table and are not subject to a unique constraint using
+# collating sequence specified in the CREATE TABLE, or The child table
+# references the primary key of the parent without specifying the
+# primary key columns and the number of primary key columns in the
+# parent do not match the number of child key columns.
+#
 do_test e_fkey-20.1 {
   execsql {
     CREATE TABLE c1(c REFERENCES nosuchtable, d);
@@ -739,7 +802,7 @@ foreach {tn tbl ptbl err} {
 }
 
 #-------------------------------------------------------------------------
-# /* EV: R-19353-43643 */
+# EVIDENCE-OF: R-19353-43643
 #
 # Test the example of foreign key mismatch errors caused by implicitly
 # mapping a child key to the primary key of the parent table when the
@@ -781,18 +844,23 @@ do_test e_fkey-21.8 {
 } {1 {foreign key mismatch}}
 
 #-------------------------------------------------------------------------
-# /* EV: R-23682-59820 */
-#
 # Test errors that are reported when creating the child table. 
 # Specifically:
 #
 #   * different number of child and parent key columns, and
 #   * child columns that do not exist.
 #
-# /* EV: R-33883-28833 */
+# EVIDENCE-OF: R-23682-59820 By contrast, if foreign key errors can be
+# recognized simply by looking at the definition of the child table and
+# without having to consult the parent table definition, then the CREATE
+# TABLE statement for the child table fails.
 #
 # These errors are reported whether or not FK support is enabled.
 #
+# EVIDENCE-OF: R-33883-28833 Foreign key DDL errors are reported
+# regardless of whether or not foreign key constraints are enabled when
+# the table is created.
+#
 drop_all_tables
 foreach fk [list OFF ON] {
   execsql "PRAGMA foreign_keys = $fk"
@@ -841,11 +909,12 @@ test_efkey_60 6 0 "INSERT INTO p2 VALUES(239, 231)"
 test_efkey_60 7 0 "INSERT INTO c2 VALUES(239, 231)"
 
 #-------------------------------------------------------------------------
-# /* EV: R-15417-28014 */
-#
 # Test that an index on on the child key columns of an FK constraint
 # is optional.
 #
+# EVIDENCE-OF: R-15417-28014 Indices are not required for child key
+# columns
+#
 # /* EV: R-15741-50893 */
 #
 # Also test that if an index is created on the child key columns, it does
@@ -876,17 +945,16 @@ foreach {tn c} [list 2 c1 3 c2 4 c3] {
 }
 
 #-------------------------------------------------------------------------
-# /* EV: R-00279-52283 */
+# EVIDENCE-OF: R-00279-52283
 #
 # Test an example showing that when a row is deleted from the parent 
 # table, the child table is queried for orphaned rows as follows:
 #
 #   SELECT rowid FROM track WHERE trackartist = ?
 #
-# /* EV: R-23302-30956 */
-#
-# Also test that if the SELECT above would return any rows, a foreign
-# key constraint is violated.
+# EVIDENCE-OF: R-23302-30956 If this SELECT returns any rows at all,
+# then SQLite concludes that deleting the row from the parent table
+# would violate the foreign key constraint and returns an error.
 #
 do_test e_fkey-25.1 {
   execsql {
@@ -944,7 +1012,7 @@ do_test e_fkey-25.7 {
 } {2 1 {foreign key constraint failed}}
 
 #-------------------------------------------------------------------------
-# /* EV: R-54172-55848 */
+# EVIDENCE-OF: R-54172-55848
 #
 # Test that when a row is deleted from the parent table of an FK 
 # constraint, the child table is queried for orphaned rows. The
@@ -961,6 +1029,10 @@ do_test e_fkey-25.7 {
 #
 #   SELECT rowid FROM <child-table> WHERE <child-key> = :parent_key_value
 #
+# EVIDENCE-OF: R-61616-46700 Similar queries may be run if the content
+# of the parent key is modified or a new row is inserted into the parent
+# table.
+#
 #
 drop_all_tables
 do_test e_fkey-26.1 {