/ Check-in [84616a13]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update documentation to talk about the response to errors within an explicit transaction. (CVS 4460)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 84616a13af633700635ad2f91e92c2f7271e96d1
User & Date: drh 2007-10-03 20:15:28
Context
2007-10-03
20:32
Update documentation in preparation for the release of 3.5.1. (CVS 4461) check-in: a57b25a2 user: drh tags: trunk
20:15
Update documentation to talk about the response to errors within an explicit transaction. (CVS 4460) check-in: 84616a13 user: drh tags: trunk
18:45
Simplify the vdbeHalt logic slightly. (CVS 4459) check-in: b59f7bcb user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.265 2007/10/03 08:46:45 danielk1977 Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.266 2007/10/03 20:15:28 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
  2669   2669   /*
  2670   2670   ** CAPI3REF:  Test To See If The Database Is In Auto-Commit Mode
  2671   2671   **
  2672   2672   ** Test to see whether or not the database connection is in autocommit
  2673   2673   ** mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
  2674   2674   ** by default.  Autocommit is disabled by a BEGIN statement and reenabled
  2675   2675   ** by the next COMMIT or ROLLBACK.
         2676  +**
         2677  +** If certain kinds of errors occur on a statement within a multi-statement
         2678  +** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], 
         2679  +** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
         2680  +** transaction might be rolled back automatically.  The only way to
         2681  +** find out if SQLite automatically rolled back the transaction after
         2682  +** an error is to use this function.
  2676   2683   **
  2677   2684   ** If another thread changes the autocommit status of the database
  2678   2685   ** connection while this routine is running, then the return value
  2679   2686   ** is undefined.
  2680   2687   */
  2681   2688   int sqlite3_get_autocommit(sqlite3*);
  2682   2689   

Changes to www/lang.tcl.

     1      1   #
     2      2   # Run this Tcl script to generate the lang-*.html files.
     3      3   #
     4         -set rcsid {$Id: lang.tcl,v 1.135 2007/10/01 17:45:40 drh Exp $}
            4  +set rcsid {$Id: lang.tcl,v 1.136 2007/10/03 20:15:28 drh Exp $}
     5      5   source common.tcl
     6      6   
     7      7   if {[llength $argv]>0} {
     8      8     set outputdir [lindex $argv 0]
     9      9   } else {
    10     10     set outputdir ""
    11     11   }
................................................................................
   284    284   COMMIT [TRANSACTION [<name>]]
   285    285   }
   286    286   Syntax {sql-statement} {
   287    287   ROLLBACK [TRANSACTION [<name>]]
   288    288   }
   289    289   
   290    290   puts {
   291         -<p>Beginning in version 2.0, SQLite supports transactions with
   292         -rollback and atomic commit.</p>
   293         -
   294         -<p>The optional transaction name is ignored. SQLite currently 
   295         -does not allow nested transactions.</p>
   296    291   
   297    292   <p>
   298    293   No changes can be made to the database except within a transaction.
   299    294   Any command that changes the database (basically, any SQL command
   300    295   other than SELECT) will automatically start a transaction if
   301    296   one is not already in effect.  Automatically started transactions
   302    297   are committed at the conclusion of the command.
................................................................................
   313    308   conflict resolution algorithm.
   314    309   </p>
   315    310   
   316    311   <p>
   317    312   END TRANSACTION is an alias for COMMIT.
   318    313   </p>
   319    314   
          315  +<p>The optional transaction name is current ignored. SQLite 
          316  +does not recognize nested transactions at this time.
          317  +However, future versions of SQLite may be enhanced to support nested
          318  +transactions and the transaction name would then become significant.
          319  +Application are advised not to use the transaction name in order
          320  +to avoid future compatibility problems.</p>
          321  +
   320    322   <p>
   321         -In SQLite version 3.0.8 and later, transactions can be deferred,
   322         -immediate, or exclusive.  Deferred means that no locks are acquired
          323  +Transactions can be deferred, immediate, or exclusive.  
          324  +The default transaction behavior is deferred.
          325  +Deferred means that no locks are acquired
   323    326   on the database until the database is first accessed.  Thus with a
   324    327   deferred transaction, the BEGIN statement itself does nothing.  Locks
   325    328   are not acquired until the first read or write operation.  The first read
   326    329   operation against a database creates a SHARED lock and the first
   327    330   write operation creates a RESERVED lock.   Because the acquisition of
   328    331   locks is deferred until they are needed, it is possible that another
   329    332   thread or process could create a separate transaction and write to
................................................................................
   342    345   </p>
   343    346   
   344    347   <p>
   345    348   A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks
   346    349   is available <a href="lockingv3.html">separately</a>.
   347    350   </p>
   348    351   
   349         -<p>
   350         -The default behavior for SQLite version 3.0.8 is a
   351         -deferred transaction.  For SQLite version 3.0.0 through 3.0.7,
   352         -deferred is the only kind of transaction available.  For SQLite
   353         -version 2.8 and earlier, all transactions are exclusive.
   354         -</p>
   355         -
   356    352   <p>
   357    353   The COMMIT command does not actually perform a commit until all
   358    354   pending SQL commands finish.  Thus if two or more SELECT statements
   359    355   are in the middle of processing and a COMMIT is executed, the commit
   360    356   will not actually occur until all SELECT statements finish.
   361    357   </p>
   362    358   
................................................................................
   363    359   <p>
   364    360   An attempt to execute COMMIT might result in an SQLITE_BUSY return code.
   365    361   This indicates that another thread or process had a read lock on the database
   366    362   that prevented the database from being updated.  When COMMIT fails in this
   367    363   way, the transaction remains active and the COMMIT can be retried later
   368    364   after the reader has had a chance to clear.
   369    365   </p>
          366  +
          367  +<h3>Response To Errors Within A Transaction</h3>
          368  +
          369  +<p>If certain kinds of errors occur within a transaction, the
          370  +transaction may or may not be rolled back automatically.  The
          371  +errors that cause the behavior include:</p>
          372  +
          373  +<ul>
          374  +<li> SQLITE_FULL: database or disk full
          375  +<li> SQLITE_IOERR: disk I/O error
          376  +<li> SQLITE_BUSY: database in use by another process
          377  +<li> SQLITE_NOMEM: out or memory
          378  +<li> SQLITE_INTERRUPT: processing interrupted by user request
          379  +</ul>
          380  +
          381  +<p>
          382  +For all of these errors, SQLite attempts to undo just the one statement
          383  +it was working on and leave changes from prior statements within the
          384  +same transaction intact and continue with the transaction.  However, 
          385  +depending on the statement being evaluated and the point at which the
          386  +error occurs, it might be necessary for SQLite to rollback and
          387  +cancel the transaction.  An application can tell which
          388  +course of action SQLite took by using the
          389  +<a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a>
          390  +C-language interface.</p>
          391  +
          392  +<p>It is recommended that applications respond to the errors
          393  +listed above by explicitly issuing a ROLLBACK command.  If the 
          394  +transaction has already been rolled back automatically
          395  +by the error response, then the ROLLBACK command will fail with an
          396  +error, but no harm is caused by this.</p>
          397  +
          398  +<p>Future versions of SQLite may extend the list of errors which
          399  +might cause automatic transaction rollback.  Future versions of
          400  +SQLite might change the error response.  In particular, we may
          401  +choose to simplify the interface in future versions of SQLite by
          402  +causing the errors above to force an unconditional rollback.</p>
   370    403   }
   371    404   
   372    405   
   373    406   Section comment comment
   374    407   
   375    408   Syntax {comment} {<SQL-comment> | <C-comment>
   376    409   } {SQL-comment} {-- <single-line>