Documentation Source Text

Check-in [a1807b9496]
Login

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

Overview
Comment:Updates to system requirements.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: a1807b9496f5cdd9a14408dfea27484a6b486378
User & Date: drh 2008-07-23 15:38:16
Context
2008-07-28
15:01
Start enumerating the assumptions sqlite makes related to the state of the file system following a power failure or OS crash. check-in: ac2c5476d0 user: dan tags: trunk
2008-07-23
15:38
Updates to system requirements. check-in: a1807b9496 user: drh tags: trunk
2008-07-22
18:55
Modify fileio.in to add requirements to the database as it is parsed. check-in: a9b591daa0 user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

    17     17   set rowbody {}     ;# Content of a row
    18     18   set rowtag {}      ;# 
    19     19   unset -nocomplain keyword
    20     20   
    21     21   # End a table row or the complete table.
    22     22   #
    23     23   proc endrow {} {
    24         -  global inrow body rowbody rowtag keyword
           24  +  global inrow body rowbody rowtag keyword dflt_parent
    25     25     if {$inrow} {
    26     26       set rowbody [string trim $rowbody]
    27     27       append body $rowbody</td></tr>\n
           28  +    if {$dflt_parent!=""} {
           29  +      append rowbody " <$dflt_parent>"
           30  +    }
    28     31       hd_requirement $rowtag $rowbody
    29     32       set keyword($rowtag) 1
    30     33       set inrow 0
    31     34       set rowbody {}
    32     35       set rowtag {}
    33     36     }
    34     37   }
................................................................................
    57     60     if {$phase==0} {
    58     61       # Looking for the CAPI3REF: keyword.  This marks the beginning of
    59     62       # an interface definition.  When the CAPI3REF keywords is seen, 
    60     63       # record the interface title and then switch to "phase 1".
    61     64       #
    62     65       if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
    63     66         set title $tx
           67  +      set dflt_parent {}
           68  +      regexp {<([AHLS]\d\d\d\d\d)>} $title all dflt_parent
    64     69         set title_lineno $lineno
    65     70         set phase 1
    66     71       }
    67     72     } elseif {$phase==1} {
    68     73       if {[string range $line 0 1]=="**"} {
    69     74         # Record all lines of column following the CAPI3REF keyword as the
    70     75         # description of the interface.  Except, look for special keywords

Changes to pages/sysreq.in.

   147    147     information can be transfered from from one database to another 
   148    148     atomically, or so that queries can join data across multiple
   149    149     databases.
   150    150   } {  
   151    151     The SQLite library shall support simultaneous access to multiple
   152    152     database files on the same database connection.
   153    153   }
          154  +
          155  +sysreq S10700 S10000 {
          156  +  A database is of little practical use if one is unable to obtain
          157  +  information from the database.  Hence:
          158  +} {
          159  +  The SQLite library shall provide interfaces that allow the application
          160  +  to obtain the status and results of SQL operations.
          161  +}
   154    162   
   155    163   </tcl>
   156    164   <h2>2.0 SQLite is designed to be extensible by the application</h2>
   157    165   <tcl>
   158    166   
   159    167   sysreq S20000 {} {
   160    168     SQLite is intended to be an embedded database that functions well
................................................................................
   171    179     SQLite works on common workstations and in embedded systems.
   172    180     Sometimes these devices, particularly embedded systems,
   173    181     have odd and unusual operating systems.  In order to support
   174    182     this level of portability, SQLite allows the interface to the operating
   175    183     system to be defined at run-time.
   176    184   } {
   177    185     The SQLite library shall provide interfaces that permit the application
   178         -  to override operating-system interfaces.
          186  +  to override interfaces to the platform on which the application is running.
   179    187   }
   180    188   sysreq S20110 S20100 {} {
   181    189     The SQLite library shall provide interfaces that permit the application
   182    190     to override the interfaces used to read and write persistent storage.
   183    191   }
   184    192   sysreq S20120 S20100 {} {
   185    193     The SQLite library shall provide interfaces that permit the application
................................................................................
   484    492     The SQLite library shall automatically control access to common
   485    493     databases from different connections in different threads or processes.
   486    494   }
   487    495   sysreq S40400 S40000 {} {
   488    496     The SQLite library shall notify the application if an operation can
   489    497     not be completed due to concurrent access constraints.
   490    498   }
          499  +sysreq S40410 S40000 {
          500  +  If an SQL statement cannot be completed because another process is
          501  +  holding a lock on the database, then the application needs to be able
          502  +  to take corrective action, such waiting for the lock to clear.
          503  +} {
          504  +  The SQLite library shall provide interfaces to assist the application
          505  +  in responding appropriately when an operation can
          506  +  not be completed due to concurrent access constraints.
          507  +}
   491    508   
   492    509   </tcl>
   493    510   <h2>5.0 SQLite is cross-platform</h2>
   494    511   <tcl>
   495    512   
   496    513   sysreq S50000 {} {
   497    514     Cross-platform in this context means that the SQLite 
................................................................................
   527    544     different size integers, and different byte orders.  The same
   528    545     database file should work on any machine.
   529    546   } {
   530    547     SQLite database files shall by processor and byte-order independent.
   531    548   }
   532    549   
   533    550   </tcl>
   534         -<h2>6.0 Other Features</h2>
          551  +<h2>6.0 Introspection</h2>
   535    552   <tcl>
   536    553   
   537    554   sysreq S60000 {} {
   538    555     Some applications need to be able to discover characteristics of
   539    556     their environment at run-time and to make appropriate adjustments to
   540    557     their processing to accommodate the environment they find themselves in.
   541    558     SQLite attempts to support this need.
................................................................................
   560    577   
   561    578   sysreq S60200 S60000 {
   562    579     In addition to the compile-time characteristics, SQLite allows
   563    580     the run-time settings of the library and of the underlying
   564    581     database file to be interrogated.
   565    582   } {
   566    583     The SQLite library shall provide interfaces that an application can
   567         -  use to find run-time performance characteristics of the
          584  +  use to find run-time performance characteristics and status of the
   568    585     SQLite library.
   569    586   }
   570    587   sysreq S60300 S60000 {} {
   571    588     The SQLite library shall provide interfaces that permit an application
   572    589     to query the schema of a database.
   573    590   }
   574    591   sysreq S60400 S60000 {} {
................................................................................
   576    593     to monitor sequence of queries and progress of submitted to SQLite.
   577    594   }
   578    595   sysreq S60500 S60000 {} {
   579    596     The SQLite library shall provide interfaces that allow an application
   580    597     to discover the algorithms that SQLite has chosen to implement specific
   581    598     SQL statements.
   582    599   }
          600  +
          601  +sysreq S60600 {S60000 S20200} {
          602  +  SQLite objects are often related.  For example, every prepared
          603  +  statement is associated with a database connection.  And every
          604  +  function context is associated with a prepared statement.  
          605  +  Applications and extensions frequently find it useful to be able
          606  +  to discover these relationships at runtime.  Hence:
          607  +} {
          608  +  The SQLite library shall provide interfaces that allow an application
          609  +  to discover relationships between SQLite objects.
          610  +}
          611  +
          612  +</tcl>
          613  +<h2>7.0 Features to promote safe and robust application coding practices</h2>
          614  +<tcl>
   583    615   
   584    616   sysreq S70000 {} {
   585    617     Many applications need to be able to safely process data or
   586    618     even SQL statements that are received from untrusted sources.
   587    619     An "SQL Injection Attack" occurs when an adversary intentionally
   588    620     introduces data that is designed to have undesirable side effects
   589    621     on the database files.  For example, suppose an application generates
................................................................................
   635    667     SQLite supports interfaces that allow the CLI and similar applications
   636    668     to know if the input it has gathered so far is complete or if it needs
   637    669     to await additional input before processing the SQL.
   638    670   } {
   639    671     The SQLite library shall provide interfaces that test to see if an
   640    672     SQL statement being received incrementally is complete.
   641    673   }
          674  +
          675  +sysreq S70300 {S70000 S30000} {
          676  +  The concept of a "prepared statement" allows an SQL statement to be
          677  +  parsed and compiled once and then reused many times.  This is a performance
          678  +  advantage in many applications.  In addition, binding values to variables
          679  +  in the prepared statement is safer than embedding values as literals because
          680  +  bound values do not need to be quoted in order to avoid an SQL injection
          681  +  attack.
          682  +} {
          683  +  The SQLite library shall support prepared statement objects with
          684  +  late parameter binding
          685  +}
   642    686   
   643    687   </tcl>
   644         -<h2>7.0 Summary Of System Requirements</h2>
          688  +<h2>8.0 Summary Of System Requirements</h2>
   645    689   
   646    690   <p>The foregoing contained both system requirements and explanatory
   647    691   text interspersed.  The following is a reproduction of the system
   648    692   requirements without the explanatory text, as a convenient reference.
   649    693   The top-level system requirements are shown first, followed by lower-level
   650    694   system requirements that provide additional detail.</p>
   651    695   
   652         -<h3>7.1 Top-level System Requirements</h3>
          696  +<h3>8.1 Top-level System Requirements</h3>
   653    697   
   654    698   <tcl>
   655    699   foreach {id derivedfrom text} $sysreq_list {
   656    700     if {[llength $derivedfrom]>0} continue
   657    701     hd_puts "<blockquote><b>$id:</b>"
   658    702     hd_resolve $text
   659    703     hd_puts </blockquote>
   660    704   }
   661    705   </tcl>
   662    706   
   663         -<h3>7.2 Derived System Requirements</h3>
          707  +<h3>8.2 Derived System Requirements</h3>
   664    708   
   665    709   <tcl>
   666    710   foreach {id derivedfrom text} $sysreq_list {
   667    711     if {[llength $derivedfrom]==0} continue
   668    712     hd_puts "<blockquote><b>$id:</b>"
   669    713     hd_resolve $text
   670    714     hd_puts </blockquote>
   671    715   }
   672    716   </tcl>