Update documentation for the 2.2.0 release. (CVS 335)

FossilOrigin-Name: 14392258c5b6385091be8d684e3ea6841941b483

Makefile.template

@@ -332,6 +332,9 @@ speed.html:	$(TOP)/www/speed.tcl
 faq.html:	$(TOP)/www/faq.tcl
 	tclsh $(TOP)/www/faq.tcl >faq.html
 
+formatchng.html:	$(TOP)/www/formatchng.tcl
+	tclsh $(TOP)/www/formatchng.tcl >formatchng.html
+
 download.html:	$(TOP)/www/download.tcl
 	tclsh $(TOP)/www/download.tcl >download.html
 
@@ -353,7 +356,8 @@ DOC = \
   tclsqlite.html \
   download.html \
   speed.html \
-  faq.html
+  faq.html \
+  formatchng.html
 
 doc:	$(DOC)
 	mkdir -p doc

manifest

@@ -1,7 +1,7 @@
-C Bug\sfixing\sin\sthe\snew\sinteger\sprimary\skey\scode.\s(CVS\s334)
+C Update\sdocumentation\sfor\sthe\s2.2.0\srelease.\s(CVS\s335)
-D 2001-12-22T14:49:25
+D 2001-12-22T19:27:40
 F Makefile.in 352fed589f09dd94347e0bb391d047118ebd6105
-F Makefile.template 0fbf0ee1fe38183d760170a13e91fffec64e73f5
+F Makefile.template c88ffcb9c339e718f434d0c7f045bcd7eea125af
 F README a4c0ba11354ef6ba0776b400d057c59da47a4cc0
 F VERSION 353ee68ca2468dce6464d331044643d350fd256f
 F aclocal.m4 11faa843caa38fd451bc6aeb43e248d1723a269d
@@ -65,7 +65,7 @@ F test/in.test 9323681388be301dc73f370b4cd62c5a33f79d1e
 F test/index.test c8a471243bbf878974b99baf5badd59407237cf3
 F test/insert.test a5c122aa726f1cef6f07d6767e8fd6f220994c11
 F test/insert2.test d6901ca931e308fea7fca8c95ebe7dc957cc9fc2
-F test/intpkey.test 1f3b36bcf772597809fb445202af77d1d17bb39f
+F test/intpkey.test 3f765f69c39af45f9324edcc6e14b201654e9790
 F test/ioerr.test 57d9bffaca18b34f9e976f786eadc2591d6efc6a
 F test/limit.test a930f3eba2a7691c8397ccab33710b931589566a
 F test/lock.test 19593689260c419efe7ced55b1418653a4b7bcd1
@@ -104,21 +104,22 @@ F tool/report1.txt 9eae07f26a8fc53889b45fc833a66a33daa22816
 F www/arch.fig d5f9752a4dbf242e9cfffffd3f5762b6c63b3bcf
 F www/arch.png 82ef36db1143828a7abc88b1e308a5f55d4336f4
 F www/arch.tcl 72a0c80e9054cc7025a50928d28d9c75c02c2b8b
-F www/c_interface.tcl 58922228e8fdb0f6af3561a051ee8ccec6dbfd17
+F www/c_interface.tcl 9123810452845783fac8e3184929463d9e70d609
-F www/changes.tcl 7718ad82090404f6a2a062dd534670996c2b82cc
+F www/changes.tcl a57ebb01b6bc941b5494a7b169576881c524cc53
 F www/crosscompile.tcl 3622ebbe518927a3854a12de51344673eb2dd060
 F www/download.tcl 1ea61f9d89a2a5a9b2cee36b0d5cf97321bdefe0
 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c
-F www/faq.tcl 5c6fba68e238a52b4d9d86b0a63ed2d706fc7f1f
+F www/faq.tcl f475a9ca61697d6d9cdae5497fa1a539df3f7e05
-F www/index.tcl 6d6d847dd3e39e9aa7b0c9b8f3144819ff3f9f51
+F www/formatchng.tcl d96e5e937dcbbebd481720aa08745ca5a906a63f
-F www/lang.tcl 6482d90e40fb5ee004a86cf98f3007312a75444e
+F www/index.tcl bcb4ee777b9beef64b5482f12660d89960b486d6
+F www/lang.tcl 6843fd3f85cba95fd199a350533ce742c706603c
 F www/mingw.tcl f1c7c0a7f53387dd9bb4f8c7e8571b7561510ebc
 F www/opcode.tcl bdec8ef9f100dbd87bbef8976c54b88e43fd8ccc
 F www/speed.tcl 83457b2bf6bb430900bd48ca3dd98264d9a916a5
 F www/sqlite.tcl 8b5884354cb615049aed83039f8dfe1552a44279
 F www/tclsqlite.tcl 880ef67cb4f2797b95bf1368fc4e0d8ca0fda956
 F www/vdbe.tcl 2013852c27a02a091d39a766bc87cff329f21218
-P 236a54d289e858a1e0505a20d907a2a40c01b521
+P 29cab124b4f7eae9d9feb60d2f3a2c443fd9b9aa
-R 5707cbf46f7d3e66441cb3379d943ba9
+R c48343b6602223daa3e4640e717ebad9
 U drh
-Z 49b0682a1be06cb764aeb1e921e472ac
+Z df1fb6885750227397b1a0fd9aad25a2

manifest.uuid

@@ -1 +1 @@
-29cab124b4f7eae9d9feb60d2f3a2c443fd9b9aa
+14392258c5b6385091be8d684e3ea6841941b483

test/intpkey.test

@@ -13,7 +13,7 @@
 # This file implements tests for the special processing associated
 # with INTEGER PRIMARY KEY columns.
 #
-# $Id: intpkey.test,v 1.2 2001/12/22 14:49:26 drh Exp $
+# $Id: intpkey.test,v 1.3 2001/12/22 19:27:41 drh Exp $
 
 set testdir [file dirname $argv0]
 source $testdir/tester.tcl
@@ -366,5 +366,45 @@ do_test intpkey=5.2 {
   }
 } {-4 -4 0 0 5 5 6 6 11 11}
 
+# Test the ability of the COPY command to put data into a
+# table that contains an integer primary key.
+#
+do_test intpkey-6.1 {
+  set f [open ./data1.txt w]
+  puts $f "20\tb-20\tc-20"
+  puts $f "21\tb-21\tc-21"
+  puts $f "22\tb-22\tc-22"
+  close $f
+  execsql {
+    COPY t1 FROM 'data1.txt';
+    SELECT * FROM t1 WHERE a>=20;
+  }
+} {20 b-20 c-20 21 b-21 c-21 22 b-22 c-22}
+do_test intpkey-6.2 {
+  execsql {
+    SELECT * FROM t1 WHERE b=='hello'
+  }
+} {5 hello world 11 hello world}
+do_test intpkey-6.3 {
+  execsql {
+    DELETE FROM t1 WHERE b='b-21';
+    SELECT * FROM t1 WHERE b=='b-21';
+  }
+} {}
+do_test intpkey-6.4 {
+  execsql {
+    SELECT * FROM t1 WHERE a>=20
+  }
+} {20 b-20 c-20 22 b-22 c-22}
+
+# Do an insert of values with the columns specified out of order.
+#
+execsql {pragma vdbe_trace=on;}
+do_test intpkey-7.1 {
+  execsql {
+    INSERT INTO t1(c,b,a) VALUES('row','new',30);
+    SELECT * FROM t1 WHERE rowid>=30;
+  }
+} {30 new row}
 
 finish_test

www/c_interface.tcl

@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the sqlite.html file.
 #
-set rcsid {$Id: c_interface.tcl,v 1.21 2001/11/24 13:36:30 drh Exp $}
+set rcsid {$Id: c_interface.tcl,v 1.22 2001/12/22 19:27:41 drh Exp $}
 
 puts {<html>
 <head>
@@ -185,6 +185,7 @@ the type of error.  Here is a complete list of the return codes:
 #define SQLITE_SCHEMA      17   /* The database schema changed */
 #define SQLITE_TOOBIG      18   /* Too much data for one row of a table */
 #define SQLITE_CONSTRAINT  19   /* Abort due to contraint violation */
+#define SQLITE_MISMATCH    20   /* Data type mismatch */
 </pre></blockquote>
 
 <p>
@@ -287,6 +288,12 @@ in a single row, this is the return code you get.
 <dd><p>This constant is returned if the SQL statement would have violated
 a database constraint.
 </p></dd>
+<dt>SQLITE_MISMATCH</dt>
+<dd><p>This error occurs when there is an attempt to insert non-integer
+data into a column labeled INTEGER PRIMARY KEY.  For most columns, SQLite
+ignores the data type and allows any kind of data to be stored.  But
+an INTEGER PRIMARY KEY column is only allowed to store integer data.
+</p></dd>
 </dl>
 </blockquote>
 

www/changes.tcl

@@ -17,7 +17,11 @@ proc chng {date desc} {
   puts "<DD><P><UL>$desc</UL></P></DD>"
 }
 
-chng {2001 Dec 16 (2.1.8)} {
+chng {2001 Dec 22 (2.2.0)} {
+<li>Columns of type INTEGER PRIMARY KEY are actually used as the primary
+    key in underlying B-Tree representation of the table.</li>
+<li>Several obscure, unrelated bugs were found and fixed while 
+    implemented the integer primary key change of the previous bullet.</li>
 <li>Added the ability to specify "*" as part of a larger column list in
     the result section of a SELECT statement.  For example:
     <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li>

www/faq.tcl

@@ -1,7 +1,7 @@
 #
 # Run this script to generated a faq.html output file
 #
-set rcsid {$Id: faq.tcl,v 1.4 2001/12/15 14:22:19 drh Exp $}
+set rcsid {$Id: faq.tcl,v 1.5 2001/12/22 19:27:41 drh Exp $}
 
 puts {<html>
 <head>
@@ -44,6 +44,43 @@ COMMIT;
 </pre></blockquote>
   There are other ways of simulating the effect of AUTOINCREMENT but
   this approach seems to be the easiest and most efficient.
+
+  <p><i>New in SQLite version 2.2.0:</i>
+  If one of the columns in a table has type INTEGER PRIMARY KEY and
+  you do an INSERT on that table that does not specify a value for
+  the primary key, then a unique random number is inserted automatically
+  in that column.  This automatically generated key is random, not 
+  sequential, but you can still use it as a unique identifier.</p>
+
+  <p>Here is an example of how the INTEGER PRIMARY KEY feature can be
+  used:</p>
+
+  <blockquote><pre>
+CREATE TABLE ex2(
+  cnum INTEGER PRIMARY KEY,
+  name TEXT,
+  email TEXT
+);
+INSERT INTO ex2(name,email) VALUES('drh','drh@hwaci.com');
+INSERT INTO ex2(name,email) VALUES('alle','alle@hwaci.com');
+SELECT * FROM ex1;
+</pre></blockquote>
+
+  <p>Notice that the primary key column <b>cnum</b> is not specified on
+  the INSERT statements.  The output of the SELECT on the last line will
+  be something like this:</p>
+
+  <blockquote>
+     1597027670|drh|drh@hwaci.com<br>
+     1597027853|alle|alle@hwaci.com
+  </blockquote>
+
+  <p>The randomly generated keys in this case are 1597027670 and
+  1597027853.  You will probably get different keys every time you
+  try this.  The keys will often be ascending, but this is not always
+  the case and you cannot count on that behavior.  The keys will never
+  be sequential.  If you need sequential keys, use the counter implemention
+  described first.</p>
 }
 
 faq {
@@ -54,7 +91,10 @@ faq {
   integer columns, floating point numbers in boolean columns, or dates
   in character columns.  The datatype you assign to a column in the
   CREATE TABLE command is (mostly) ignored.  Every column is able to hold
-  an arbitrary length string.</p>
+  an arbitrary length string.  (There is one exception: Columns of
+  type INTEGER PRIMARY KEY may only hold an integer.  An error will result
+  if you try to put anything other than an integer into an
+  INTEGER PRIMARY KEY column.)</p>
 
   <p>Because SQLite ignores data types, you can omit the data type definition
   from columns in CREATE TABLE statements.  For example, instead of saying
@@ -176,6 +216,12 @@ faq {
   If you change them so that they actually implement a mutex, then SQLite
   will be threadsafe.  But because these routines are stubs, the default
   SQLite distribution is not threadsafe.</p>
+
+  <p>"Threadsafe" in the previous paragraph means that two or more threads
+  can run SQLite at the same time on different "<b>sqlite</b>" structures
+  returned from separate calls to <b>sqlite_open()</b>.  It is never safe
+  to use the same <b>sqlite</b> structure pointer simultaneously in two
+  or more threads.</p>
 }
 
 faq {

www/formatchng.tcl

@@ -0,0 +1,108 @@
+#
+# Run this Tcl script to generate the formatchng.html file.
+#
+set rcsid {$Id: formatchng.tcl,v 1.1 2001/12/22 19:27:41 drh Exp $ }
+
+puts {<html>
+<head>
+  <title>File Format Changes in SQLite</title>
+</head>
+<body bgcolor=white>
+<h1 align=center>
+File Format Changes in SQLite
+</h1>}
+puts "<p align=center>
+(This page was last modified on [lrange $rcsid 3 4] UTC)
+</p>"
+
+puts {
+<p>
+From time to time, enhancements or bug fixes require a change to
+the underlying file format for SQLite.  When this happens and you
+want to upgrade your library, you must convert the contents of your
+databases into a portable ASCII representation using the old version
+of the library then reload the data using the new version of the
+library.
+</p>
+
+<p>
+You can tell if you should reload your databases by comparing the
+version numbers of the old and new libraries.  If either of the
+first two digits in the version number change, then a reload is
+either required or recommended.  For example, upgrading from
+version 1.0.32 to 2.0.0 requires a reload.  So does going from
+version 2.0.8 to 2.1.0.
+</p>
+
+<p>
+The following table summarizes the SQLite file format changes that have
+occurred since version 1.0.0:
+</p>
+
+<blockquote>
+<table border=2 cellpadding=5>
+<tr>
+  <th>Version Change</th>
+  <th>Approx. Date</th>
+  <th>Description Of File Format Change</th>
+</tr>
+<tr>
+  <td valign="top">1.0.32 to 2.0.0</td>
+  <td valign="top">2001-Sep-20</td>
+  <td>Version 1.0.X of SQLite used the GDBM library as its backend
+  interface to the disk.  Beginning in version 2.0.0, GDBM was replaced
+  by a custom B-Tree library written especially for SQLite.  The new
+  B-Tree backend is twice as fast as GDBM, supports atomic commits and
+  rollback, and stores an entire database in a single disk file instead
+  using a separate file for each table as GDBM does.  The two
+  file formats are not even remotely similar.</td>
+</tr>
+<tr>
+  <td valign="top">2.0.8 to 2.1.0</td>
+  <td valign="top">2001-Nov-12</td>
+  <td>The same basic B-Tree format is used but the details of the 
+  index keys were changed in order to provide better query 
+  optimization opportunities.  Some of the headers were also changed in order
+  to increase the maximum size of a row from 64KB to 24MB.</td>
+</tr>
+<tr>
+  <td valign="top">2.1.7 to 2.2.0</td>
+  <td valign="top">2001-Dec-21</td>
+  <td>Beginning with version 2.2.0, SQLite no longer builds an index for
+  an INTEGER PRIMARY KEY column.  Instead, it uses that column as the actual
+  B-Tree key for the main table.<p>Version 2.2.0 and later of the library
+  will automatically detect when it is reading a 2.1.x database and will
+  disable the new INTEGER PRIMARY KEY feature.   In other words, version
+  2.2.x is backwards compatible to version 2.1.x.  But version 2.1.x is not
+  forward compatible with version 2.2.x. If you try to open
+  a 2.2.x database with an older 2.1.x library and that database contains
+  an INTEGER PRIMARY KEY, you will likely get a coredump.  If the database
+  schema does not contain any INTEGER PRIMARY KEYs, then the version 2.1.x
+  and version 2.2.x database files will be identical and completely
+  interchangeable.</p>
+</tr>
+</table>
+</blockquote>
+
+<p>
+To perform a database reload, have ready versions of the
+<b>sqlite</b> command-line utility for both the old and new
+version of SQLite.  Call these two executables "<b>sqlite-old</b>"
+and "<b>sqlite-new</b>".  Suppose the name of your old database
+is "<b>old.db</b>" and you want to create a new database with
+the same information named "<b>new.db</b>".  The command to do
+this is as follows:
+</p>
+
+<blockquote>
+  echo .dump | sqlite-old old.db | sqlite-new new.db
+</blockquote>
+}
+
+puts {
+<p><hr /></p>
+<p><a href="index.html"><img src="/goback.jpg" border=0 />
+Back to the SQLite Home Page</a>
+</p>
+
+</body></html>}

www/index.tcl

@@ -1,7 +1,7 @@
 #
 # Run this TCL script to generate HTML for the index.html file.
 #
-set rcsid {$Id: index.tcl,v 1.49 2001/11/24 13:23:05 drh Exp $}
+set rcsid {$Id: index.tcl,v 1.50 2001/12/22 19:27:41 drh Exp $}
 
 puts {<html>
 <head><title>SQLite: An SQL Database Engine In A C Library</title></head>
@@ -66,38 +66,15 @@ The latest source code is
 <a href="download.html">available for download</a>.
 There are currently no known memory leaks or bugs
 in the library.
-SQLite 2.1.0 is currently being used in several mission-critical
+SQLite 2.1.7 is currently being used in several mission-critical
-applications.
+applications.  SQLite 2.2.0 is in beta-test.
 </p>
 
 <p>
-The SQLite file format changed beginning with version 2.1.0.  The
+Whenever either of the first two digits in the version number
-same basic B-Tree structure from version 2.0.0 is used but the
+for SQLite change, it means that the underlying file format
-details of indices where altered to permit better query optimization
+has changed.  See <a href="formatchng.html">formatchng.html</a>
-and the B-Tree table entry headers where changed slightly to expand the
+for additional information.
-maximum amount of data on a row from 64KB to 16MB.  
-The file format changes
-between 2.0.8 and 2.1.0 are small but they still require that you
-dump and restore your old databases.  The following command should
-suffice:
-</p>
-
-<blockquote><pre>
-echo .dump | sqlite2.0 old.db | sqlite2.1 new.db
-</pre></blockquote>
-
-<p>
-The above command assumes that <b>sqlite2.0</b> is any of the
-2.0 series of sqlite command-line tools and <b>sqlite2.1</b> is the
-new version 2.1 sqlite command-line tool.
-</p>
-
-<p>
-Version 1.0.X of SQLite used GDBM as its backend and so its
-file format is complete incompatable with all version 2.0 and
-version 2.1 SQLite releases.  Legacy databases must be dumped to
-ASCII and reloaded, as shown above, before they can be used with
-newer versions of SQLite.
 </p>
 
 <h2>Documentation</h2>

www/lang.tcl

@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the sqlite.html file.
 #
-set rcsid {$Id: lang.tcl,v 1.17 2001/11/24 13:50:53 drh Exp $}
+set rcsid {$Id: lang.tcl,v 1.18 2001/12/22 19:27:41 drh Exp $}
 
 puts {<html>
 <head>
@@ -239,12 +239,25 @@ datatype for that column, then one or more optional column constraints.
 The datatype for the column is ignored.  All information
 is stored as null-terminated strings.
 The UNIQUE constraint causes an index to be created on the specified
-columns.  This index must contain unique keys.  The PRIMARY KEY constraint
+columns.  This index must contain unique keys.
-is an alias for UNIQUE.
 The DEFAULT constraint
 specifies a default value to use when doing an INSERT.
 </p>
 
+<p>Specifying a PRIMARY KEY normally just creates a UNIQUE index
+on the primary key.  However, if primary key is on a single column
+that has datatype INTEGER, then that column is used internally
+as the actual key of the B-Tree for the table.  This means that the column
+may only hold unique integer values.  (Except for this one case,
+SQLite ignores the datatype specification of columns and allows
+any kind of data to be put in a column regardless of its declared
+datatype.)  If a table does not have an INTEGER PRIMARY KEY column,
+then the B-Tree key will be a randomly generated integer.  The
+B-Tree key for a row can always be accessed using one of the
+special names "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>".
+This is true regardless of whether or not there is an INTEGER
+PRIMARY KEY.</p>
+
 <p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE"
 and "TABLE" then the table that is created is only visible to the
 process that opened the database and is automatically deleted when