Documentation Source Text

Check-in [2ca5d3c1c4]
Login

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

Overview
Comment:Merge fixes from the 3.23.0 branch.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 2ca5d3c1c4d223f32425219e18b6a3dda1627c168fae27eef7e0e4a1affd5580
User & Date: drh 2018-04-10 01:09:53
Context
2018-04-10
12:36
Changes for the 3.23.1 patch release. check-in: 21ae80926f user: drh tags: trunk
01:09
Merge fixes from the 3.23.0 branch. check-in: 2ca5d3c1c4 user: drh tags: trunk
00:29
Fix a typo in the whynotgit.html document. Leaf check-in: 737022637a user: drh tags: version-3.23
00:21
Add the Why SQLite Does Not Use Git document. check-in: 1b4a90faa0 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/cli.in.

   912    912   For command-line usage, add the short style command-line options immediately
   913    913   following the "-A", without an intervening space.  All subsequent arguments
   914    914   are considered to be part of the .archive command.  For example, the following 
   915    915   commands are equivalent:
   916    916   
   917    917   <codeblock>
   918    918   sqlite3 new_archive.db -Acv file1 file2 file3
   919         -sqlite3 new_archive.db ".ar -tv file1 file2 file3"
          919  +sqlite3 new_archive.db ".ar -cv file1 file2 file3"
   920    920   </codeblock>
   921    921   
   922    922   <p>
   923    923   Long and short style options may be mixed. For example, the following are
   924    924   equivalent:
   925    925   
   926    926   <codeblock>

Changes to pages/cpu.in.

     3      3   
     4      4   <table_of_contents>
     5      5   
     6      6   <h1>Overview</h1>
     7      7   
     8      8   <p>The graph below shows the number of CPU cycles used by SQLite on a
     9      9   standard workload, for all versions of SQLite going back about 9 years.
    10         -Recent version so SQLite use less then a third of the CPU cycles 
           10  +Recent versions of SQLite use less than a third of the CPU cycles 
    11     11   compared to older versions.
    12     12   
    13     13   <p>
    14     14   This article describes how the SQLite developers measure CPU usage,
    15     15   what those measurements actually mean, and the techniques used by
    16     16   SQLite developers on their continuing quest to further reduce the
    17     17   CPU usage of the SQLite library.

Changes to pages/howtocorrupt.in.

   227    227   
   228    228   <p>Beginning with SQLite [version 3.10.0] ([dateof:3.10.0]), 
   229    229   the unix OS interface will
   230    230   attempt to resolve symbolic links and open the database file by its
   231    231   canonical name.  Prior to version 3.10.0, opening a database file 
   232    232   through a symbolic link was similar to opening a database file
   233    233   that had multiple hard links and resulted in undefined behavior.</p>
          234  +
          235  +<tcl>hd_fragment fork</tcl>
          236  +<h2> Carrying an open database connection across a fork() </h2>
          237  +
          238  +<p> Do not open an SQLite database connection, then fork(), then try
          239  +to use that database connection in the child process.  All kinds of
          240  +locking problems will result and you can easily end up with a corrupt
          241  +database.  SQLite is not designed to support that kind of behavior.
          242  +Any database connection that is used in a child process must be opened
          243  +in the child process, not inherited from the parent.
          244  +
          245  +<p> Do not even call [sqlite3_close()] on a database connection from a
          246  +child process if the connection was opened in the parent.  It is safe
          247  +to close the underlying file descriptor, but the [sqlite3_close()]
          248  +interface might invoke cleanup activities that will delete content out
          249  +from under the parent, leading to errors and perhaps even database
          250  +corruption.
   234    251   
   235    252   <h1> Failure to sync</h1>
   236    253   
   237    254   <p>In order to guarantee that database files are always consistent, SQLite
   238    255   will occasionally ask the operating system to flush all pending writes to
   239    256   persistent storage then wait for that flush to complete.  This is 
   240    257   accomplished using the <tt>fsync()</tt> system call under unix and

Changes to pages/lang.in.

   835    835   limited to the value set by
   836    836   [sqlite3_limit]([SQLITE_LIMIT_COLUMN],...).)^</p>
   837    837   
   838    838   <tcl>hd_fragment uniqueidx {unique index}</tcl>
   839    839   <p>^If the UNIQUE keyword appears between CREATE and INDEX then duplicate
   840    840   index entries are not allowed.  ^Any attempt to insert a duplicate entry
   841    841   will result in an error.  ^For the purposes of unique indices, all NULL values
   842         -are considered to different from all other NULL values and are thus unique.
          842  +are considered different from all other NULL values and are thus unique.
   843    843   This is one of the two possible interpretations of the SQL-92 standard
   844    844   (the language in the standard is ambiguous) and is the interpretation
   845    845   followed by PostgreSQL, MySQL, Firebird, and Oracle.  Informix and
   846    846   Microsoft SQL Server follow the other interpretation of the standard.</p>
   847    847   
   848    848   <p>^If the optional IF NOT EXISTS clause is present and another index
   849    849   with the same name already exists, then this command becomes a no-op.</p>
................................................................................
   930    930   
   931    931   <center><table border=1>
   932    932     <tr><th>Expression Affinity   <th>Column Declared Type
   933    933     <tr><td>TEXT                  <td>"TEXT"
   934    934     <tr><td>NUMERIC               <td>"NUM"
   935    935     <tr><td>INTEGER               <td>"INT"
   936    936     <tr><td>REAL                  <td>"REAL"
   937         -  <tr><td>NONE                  <td>"" (empty string)
          937  +  <tr><td>BLOB (a.k.a "NONE")   <td>"" (empty string)
   938    938   </table></center>)^
   939    939   
   940    940   <p>^(A table created using CREATE TABLE AS has no PRIMARY KEY and no
   941    941   constraints of any kind. The default value of each column is NULL. The default
   942    942   collation sequence for each column of the new table is BINARY.)^
   943    943   
   944    944   <p>^Tables created using CREATE TABLE AS are initially populated with the

Changes to pages/whentouse.in.

    63     63   
    64     64   <p>There are many benefits to this approach, including improved
    65     65   performance, reduced cost and complexity, and
    66     66   improved reliability.  See technical notes
    67     67   [file-format benefits|"aff_short.html"] and 
    68     68   [application file-format|"appfileformat.html"] and
    69     69   [faster than the filesystem|"fasterthanfs.html"] for more information.
           70  +This use case is closely related to the
           71  +<a href="#wireproto">data transfer format</a> and
           72  +<a href="#container">data container</a> use cases below.
           73  +</li>
    70     74   
    71     75   <tcl>hd_fragment website {using SQLite for websites}</tcl>
    72     76   <li><p><b>Websites</b></p>
    73     77   
    74     78   <p>SQLite works great as the database engine for most low to
    75     79   medium traffic websites (which is to say, most websites).
    76     80   The amount of web traffic that SQLite can handle depends
................................................................................
   151    155   SQL database engine in this scenario.
   152    156   Database requests are serialized by the server, so concurrency is not
   153    157   an issue.  Concurrency is also improved by "database sharding":
   154    158   using separate database files for different subdomains.  For
   155    159   example, the server might have a separate SQLite database for each
   156    160   user, so that the server can handle hundreds or thousands of simultaneous
   157    161   connections, but each SQLite database is only used by one connection.</p>
   158         -
   159         -
   160    162   </li>
   161    163   
          164  +<tcl>hd_fragment wireproto {data transfer format}</tcl>
          165  +<li><p><b>Data transfer format</b><p>
          166  +
          167  +<p>Because an SQLite database is a single compact file in a
          168  +[file format|well-defined cross-platform format], it is often used
          169  +as a container for transfering content from one system to another.
          170  +The sender gathers content into an SQLite database file, transfers
          171  +that one file to the receiver, then the receiver uses SQL to extract
          172  +the content as needed.
          173  +
          174  +<p>An SQLite database facilitates data transfer between systems even
          175  +when the endpoints have different word sizes and/or byte orders.
          176  +The data can be a complex mix of large binary blobs, text, and small
          177  +numeric or boolean values.  The data format can be easily extended
          178  +by adding new tables and/or columns, without breaking legacy receivers.
          179  +The SQL query language means that receivers are not required to parse
          180  +the entire transfer all at once, but can instead query the
          181  +received content as needed.  The data format is "transparent" in the
          182  +sense that it is easily decoded for human viewing using 
          183  +a variety of universally available, open-source tools, from multiple
          184  +vendors.
          185  +</li>
          186  +
          187  +<tcl>hd_fragment container {data container}</tcl>
   162    188   <li><p><b>File archive and/or data container</b></p>
   163    189   
   164    190   <p>
   165    191   The [SQLite Archive] idea shows how
   166    192   SQLite can be used as a substitute for ZIP archives or Tarballs.
   167    193   An archive of files stored in SQLite is only very slightly larger, and
   168    194   in some cases actually smaller, than the equivalent ZIP archive.
................................................................................
   303    329   </li>
   304    330   
   305    331   <li><p><b>High Concurrency</b></p>
   306    332   
   307    333   <p>
   308    334   SQLite supports an unlimited number of simultaneous readers, but it 
   309    335   will only allow one writer at any instant in time.
   310         -For many situations, this is not a problem.  Writer queue up. Each application
          336  +For many situations, this is not a problem.  Writers queue up. Each application
   311    337   does its database work quickly and moves on, and no lock lasts for more
   312    338   than a few dozen milliseconds. But there are some applications that require
   313    339   more concurrency, and those applications may need to seek a different
   314    340   solution.
   315    341   </p>
   316    342   </li>
   317    343   

Changes to pages/whynotgit.in.

     1         -<title>Why SQLite Does Not Use Git?</title>
            1  +<title>Why SQLite Does Not Use Git</title>
     2      2   
     3      3   <table_of_contents>
     4      4   
     5      5   <h1>Introduction</h1>
     6      6   
     7      7   <p>
     8      8   SQLite does not use the