Documentation Source Text

Check-in [25a56d695c]
Login

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

Overview
Comment:Changes all references to the "tcl.tk" domain into "tcl-lang.org" as the maintainer of the "tk" top-level domain has been hacked and seems not to care.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 25a56d695c5e14e99972a6cf98a52f97932f1272
User & Date: drh 2015-11-01 18:01:34
Context
2015-11-02
13:51
Add version 3.9.2 to the change log. check-in: 938ebc6962 user: drh tags: trunk
2015-11-01
18:01
Changes all references to the "tcl.tk" domain into "tcl-lang.org" as the maintainer of the "tk" top-level domain has been hacked and seems not to care. check-in: 25a56d695c user: drh tags: trunk
2015-10-30
01:14
Fix a typo in the formatchng.in document. check-in: 13dc43c3a3 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/amalgamation.in.

125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

<p>In both cases, the split amalgamation can be obtained by
substituting "sqlite3-all.c" for "sqlite3.c" as the make target.

<h3>4.1 Dependencies</h3>

<p>The build process makes extensive use of the 
[http://www.tcl.tk/|Tcl] scripting language.  You will need to have a
copy of TCL installed in order for the make targets above to work.
Easy-to-use installers can be obtained from [http://www.tcl.tk/].
May unix workstations of Tcl installed by default.

<p>The build process also uses [http://en.wikipedia.org/wiki/AWK|AWK].
AWK is almost always installed by default on unix-like workstations,
but it may need to be downloaded and installed on Windows development
platforms.  There are many versions of AWK available for Windows.
Use a search engine to find one.

<h3>4.2 See Also</h3>

<p>Additional notes on compiling SQLite can be found on the
[How To Compile SQLite] page.







|

|












125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

<p>In both cases, the split amalgamation can be obtained by
substituting "sqlite3-all.c" for "sqlite3.c" as the make target.

<h3>4.1 Dependencies</h3>

<p>The build process makes extensive use of the 
[http://www.tcl-lang.org/|Tcl] scripting language.  You will need to have a
copy of TCL installed in order for the make targets above to work.
Easy-to-use installers can be obtained from [http://www.tcl-lang.org/].
May unix workstations of Tcl installed by default.

<p>The build process also uses [http://en.wikipedia.org/wiki/AWK|AWK].
AWK is almost always installed by default on unix-like workstations,
but it may need to be downloaded and installed on Windows development
platforms.  There are many versions of AWK available for Windows.
Use a search engine to find one.

<h3>4.2 See Also</h3>

<p>Additional notes on compiling SQLite can be found on the
[How To Compile SQLite] page.

Changes to pages/changes.in.

1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612

chng {2009-10-14 (3.6.19)} {
<li>Added support for [foreign key constraints].  Foreign key constraints
    are disabled by default.  Use the [foreign_keys pragma] to turn them on.
<li>Generalized the IS and IS NOT operators to take arbitrary expressions
    on their right-hand side.
<li>The [TCL Interface] has been enhanced to use the
    [http://www.tcl.tk/cgi-bin/tct/tip/322.html | Non-Recursive Engine (NRE)]
    interface to the TCL interpreter when linked against TCL 8.6 or later.
<li>Fix a bug introduced in 3.6.18 that can lead to a segfault when an
    attempt is made to write on a read-only database.
}

chng {2009-09-11 (3.6.18)} {
<li>Versioning of the SQLite source code has transitioned from CVS to







|







1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612

chng {2009-10-14 (3.6.19)} {
<li>Added support for [foreign key constraints].  Foreign key constraints
    are disabled by default.  Use the [foreign_keys pragma] to turn them on.
<li>Generalized the IS and IS NOT operators to take arbitrary expressions
    on their right-hand side.
<li>The [TCL Interface] has been enhanced to use the
    [http://www.tcl-lang.org/cgi-bin/tct/tip/322.html | Non-Recursive Engine (NRE)]
    interface to the TCL interpreter when linked against TCL 8.6 or later.
<li>Fix a bug introduced in 3.6.18 that can lead to a segfault when an
    attempt is made to write on a read-only database.
}

chng {2009-09-11 (3.6.18)} {
<li>Versioning of the SQLite source code has transitioned from CVS to

Changes to pages/download.in.

106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
...
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
  than 32767 lines of code.
}
#  See the <a href="http://www.sqlite.org/draft/releaselog/current.html">pending
#  change log</a> for details.
#Product {snapshot/sqlite-tea-DATE.zip} {
#  This is a snapshot (as of VERSION) of the current SQLite code under 
#  development, packaged and ready to build using the
#  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a>.
#  Use this snapshot for testing only.  This is not a release.
#}
Product {snapshot/sqlite-uap-DATE.vsix} {
  VSIX package for Universal App Platform development using Visual Studio 2015 CTP.
}

Heading {Pre-release Windows DLLs} {} $Caution
................................................................................

Product {YEAR/sqlite-amalgamation32k-VVV.zip} {
  C source code as the [split amalgamation], version VERSION.
}

Product {YEAR/sqlite-autoconf-VVV.tar.gz} {
  C source code as an [amalgamation].  Also includes a "configure" script
  and [http://www.tcl.tk/doc/tea/|TEA] makefiles for the [TCL Interface].
} {amalgtarball {amalgamation tarball}}


Product {YEAR/sqlite-tea-VVV.tar.gz} {
  A tarball of the [amalgamation] together with a
  <a href="http://www.tcl.tk/doc/tea/">Tcl Extension
  Architecture (TEA)</a>
  compatible configure script and makefile.
} {teatarball {TEA tarball}}

Heading {Documentation} docco

Product {YEAR/sqlite-doc-VVV.zip} {
................................................................................
available for anonymous read-only access.  Anyone can 
view the repository contents and download historical versions
of individual files or ZIP archives of historical check-ins.
You can also [clone the entire repository].</p>

<p>See the [How To Compile SQLite] page for additional information
on how to use the raw SQLite source code.
Note that a recent version of <a href="http://www.tcl.tk/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/src">http://www.sqlite.org/cgi/src</a> (Dallas)<br>







|







 







|





|







 







|







106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
...
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
...
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
  than 32767 lines of code.
}
#  See the <a href="http://www.sqlite.org/draft/releaselog/current.html">pending
#  change log</a> for details.
#Product {snapshot/sqlite-tea-DATE.zip} {
#  This is a snapshot (as of VERSION) of the current SQLite code under 
#  development, packaged and ready to build using the
#  <a href="http://www.tcl-lang.org/doc/tea/">Tcl Extension Architecture (TEA)</a>.
#  Use this snapshot for testing only.  This is not a release.
#}
Product {snapshot/sqlite-uap-DATE.vsix} {
  VSIX package for Universal App Platform development using Visual Studio 2015 CTP.
}

Heading {Pre-release Windows DLLs} {} $Caution
................................................................................

Product {YEAR/sqlite-amalgamation32k-VVV.zip} {
  C source code as the [split amalgamation], version VERSION.
}

Product {YEAR/sqlite-autoconf-VVV.tar.gz} {
  C source code as an [amalgamation].  Also includes a "configure" script
  and [http://www.tcl-lang.org/doc/tea/|TEA] makefiles for the [TCL Interface].
} {amalgtarball {amalgamation tarball}}


Product {YEAR/sqlite-tea-VVV.tar.gz} {
  A tarball of the [amalgamation] together with a
  <a href="http://www.tcl-lang.org/doc/tea/">Tcl Extension
  Architecture (TEA)</a>
  compatible configure script and makefile.
} {teatarball {TEA tarball}}

Heading {Documentation} docco

Product {YEAR/sqlite-doc-VVV.zip} {
................................................................................
available for anonymous read-only access.  Anyone can 
view the repository contents and download historical versions
of individual files or ZIP archives of historical check-ins.
You can also [clone the entire repository].</p>

<p>See the [How To Compile SQLite] page for additional information
on how to use the raw SQLite source code.
Note that a recent version of <a href="http://www.tcl-lang.org/">Tcl</a>
is required in order to build from the repository sources. 
The [amalgamation] source code files
(the "sqlite3.c" and "sqlite3.h" files) build products and are
not contained in raw source code tree.</p>

<blockquote>
<a href="http://www.sqlite.org/cgi/src">http://www.sqlite.org/cgi/src</a> (Dallas)<br>

Changes to pages/famous.in.

201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
There are 
[http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27326.html | multiple]
[http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27332.html|sightings]
of SQLite in the Skype client for Mac OS X and Windows.
</td></tr>

<tr><td valign="top">
<a href="http://www.tcl.tk/">
<img src="images/foreignlogos/tcl.gif" border="0"></a>
</td><td>
The Tcl/Tk programming language now comes with SQLite built-in.  SQLite works
particularly well with Tcl since SQLite was originally a Tcl extension that
subsequently "escaped" into the wild.
</td>








|







201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
There are 
[http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27326.html | multiple]
[http://www.mail-archive.com/sqlite-users%40sqlite.org/msg27332.html|sightings]
of SQLite in the Skype client for Mac OS X and Windows.
</td></tr>

<tr><td valign="top">
<a href="http://www.tcl-lang.org/">
<img src="images/foreignlogos/tcl.gif" border="0"></a>
</td><td>
The Tcl/Tk programming language now comes with SQLite built-in.  SQLite works
particularly well with Tcl since SQLite was originally a Tcl extension that
subsequently "escaped" into the wild.
</td>

Changes to pages/faq.in.

577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
  <tt>column1=column1</tt> which is obviously always true.
}

faq {
  How are the syntax diagrams (a.k.a. "railroad" diagrams) for
  SQLite generated?
} {
  The process is explained at [http://wiki.tcl.tk/21708].
}

faq {
  The SQL standard requires that a UNIQUE constraint be enforced even if
  one or more of the columns in the constraint are NULL, but SQLite does
  not do this.  Isn't that a bug?
} {







|







577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
  <tt>column1=column1</tt> which is obviously always true.
}

faq {
  How are the syntax diagrams (a.k.a. "railroad" diagrams) for
  SQLite generated?
} {
  The process is explained at [http://wiki.tcl-lang.org/21708].
}

faq {
  The SQL standard requires that a UNIQUE constraint be enforced even if
  one or more of the columns in the constraint are NULL, but SQLite does
  not do this.  Isn't that a bug?
} {

Changes to pages/howtocompile.in.

142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<h2>Compiling The TCL Interface</h2>

<p>The TCL interface for SQLite is a small module that is added into
the regular amalgamation.  The result is a new amalgamated source
file called "<b>tclsqlite3.c</b>".  This single source file is all that
is needed to generate a shared library that can be loaded into a
standard 
[http://wiki.tcl.tk/2541 | tclsh] or 
[http://wiki.tcl.tk/2364 | wish] using the 
[http://wiki.tcl.tk/9830 | TCL load command], or to generate a
standalone tclsh that comes with SQLite built in.
A copy of the tcl amalgamation
is included on the [download page] as a file in the [TEA tarball].</p>

<p>To generate a TCL-loadable library for SQLite on Linux, the following
command will suffice:</p>








|
|
|







142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
<h2>Compiling The TCL Interface</h2>

<p>The TCL interface for SQLite is a small module that is added into
the regular amalgamation.  The result is a new amalgamated source
file called "<b>tclsqlite3.c</b>".  This single source file is all that
is needed to generate a shared library that can be loaded into a
standard 
[http://wiki.tcl-lang.org/2541 | tclsh] or 
[http://wiki.tcl-lang.org/2364 | wish] using the 
[http://wiki.tcl-lang.org/9830 | TCL load command], or to generate a
standalone tclsh that comes with SQLite built in.
A copy of the tcl amalgamation
is included on the [download page] as a file in the [TEA tarball].</p>

<p>To generate a TCL-loadable library for SQLite on Linux, the following
command will suffice:</p>

Changes to pages/howtocorrupt.in.

376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
<tcl>hd_fragment fscorruption {filesystem corruption}</tcl>
<h3>6.3 Filesystem Corruption</h3>

<p>Since SQLite databases are ordinary disk files, any malfunction in the
filesystem can corrupt the database.  Filesystems in modern operating systems
are very reliable, but errors do still occur.  For example, on 2013-10-01
the SQLite database that holds the
<a href="http://wiki.tcl.tk/">Wiki for Tcl/Tk</a> went corrupt a few days
after the host computer was moved to a dodgy build of the (linux) kernel
that had issues in the filesystem layer.  In that event, the filesystem
eventually became so badly corrupted that the machine was unusable, but
the earliest symptom of trouble was the corrupted SQLite database.</p>

<h2>7.0 Bugs in SQLite</h2>








|







376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
<tcl>hd_fragment fscorruption {filesystem corruption}</tcl>
<h3>6.3 Filesystem Corruption</h3>

<p>Since SQLite databases are ordinary disk files, any malfunction in the
filesystem can corrupt the database.  Filesystems in modern operating systems
are very reliable, but errors do still occur.  For example, on 2013-10-01
the SQLite database that holds the
<a href="http://wiki.tcl-lang.org/">Wiki for Tcl/Tk</a> went corrupt a few days
after the host computer was moved to a dodgy build of the (linux) kernel
that had issues in the filesystem layer.  In that event, the filesystem
eventually became so badly corrupted that the machine was unusable, but
the earliest symptom of trouble was the corrupted SQLite database.</p>

<h2>7.0 Bugs in SQLite</h2>

Changes to pages/lang.in.

1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
</tr>
<tr>
<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
<td>^A dollar-sign followed by an identifier name also holds a spot for a named
parameter with the name $AAAA.  ^(The identifier name in this case can include
one or more occurrences of "::" and a suffix enclosed in "(...)" containing
any text at all.)^  This syntax is the form of a variable name in the
[http://www.tcl.tk/ | Tcl programming language].  The presence
of this syntax results from the fact that SQLite is really a 
[Tcl extension] that has escaped into the wild.</td>
</tr>
</table>
</blockquote>

<p>^Parameters that are not assigned values using







|







1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
</tr>
<tr>
<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
<td>^A dollar-sign followed by an identifier name also holds a spot for a named
parameter with the name $AAAA.  ^(The identifier name in this case can include
one or more occurrences of "::" and a suffix enclosed in "(...)" containing
any text at all.)^  This syntax is the form of a variable name in the
[http://www.tcl-lang.org/ | Tcl programming language].  The presence
of this syntax results from the fact that SQLite is really a 
[Tcl extension] that has escaped into the wild.</td>
</tr>
</table>
</blockquote>

<p>^Parameters that are not assigned values using

Changes to pages/oldnews.in.

1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
}


newsitem {2004-10-10} {SQLite at the 11<sup><small>th</small></sup>
Annual Tcl/Tk Conference} {
  There will be a talk on the use of SQLite in Tcl/Tk at the
  11<sup><small>th</small></sup> Tcl/Tk Conference this week in
  New Orleans.  Visit [http://www.tcl.tk/community/tcl2004/]
  for details.
  <a href="http://www.sqlite.org/tclconf2004/page-001.html">
  Slides</a> from the talk are available.
}

newsitem {2004-09-18} {Version 3.0.7} {
  Version 3.0 has now been in use by multiple projects for several







|







1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
}


newsitem {2004-10-10} {SQLite at the 11<sup><small>th</small></sup>
Annual Tcl/Tk Conference} {
  There will be a talk on the use of SQLite in Tcl/Tk at the
  11<sup><small>th</small></sup> Tcl/Tk Conference this week in
  New Orleans.  Visit [http://www.tcl-lang.org/community/tcl2004/]
  for details.
  <a href="http://www.sqlite.org/tclconf2004/page-001.html">
  Slides</a> from the talk are available.
}

newsitem {2004-09-18} {Version 3.0.7} {
  Version 3.0 has now been in use by multiple projects for several

Changes to pages/quickstart.in.

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<li><p>Additional documentation is available [CLI | here]</li>
</ul>

<h2>Write Programs That Use SQLite</h2>

<ul>
<li><p>Below is a simple 
[http://www.tcl.tk | TCL program] that demonstrates how to use
the TCL interface to SQLite.  The program executes the SQL statements
given as the second argument on the database defined by the first
argument.  The commands to watch for are the <b>sqlite3</b> command
on line 7 which opens an SQLite database and creates
a new object named "<b>db</b>" to access that database, the
use of the [eval method] on the <b>db</b> object on line 8 to run
SQL commands against the database, and the closing of the database connection







|







23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<li><p>Additional documentation is available [CLI | here]</li>
</ul>

<h2>Write Programs That Use SQLite</h2>

<ul>
<li><p>Below is a simple 
[http://www.tcl-lang.org | TCL program] that demonstrates how to use
the TCL interface to SQLite.  The program executes the SQL statements
given as the second argument on the database defined by the first
argument.  The commands to watch for are the <b>sqlite3</b> command
on line 7 which opens an SQLite database and creates
a new object named "<b>db</b>" to access that database, the
use of the [eval method] on the <b>db</b> object on line 8 to run
SQL commands against the database, and the closing of the database connection

Changes to pages/tclsqlite.in.

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
  hd_resolve $text
}
</tcl>

<h1 align=center>The Tcl interface to the SQLite library</h1>

<p>The SQLite library is designed to be very easy to use from
a [http://www.tcl.tk | Tcl or Tcl/Tk] script.  SQLite
began as a [http://www.tcl.tk/doc/tea/ | Tcl extension]
and the primary [test suite] for SQLite is written in TCL.  SQLite
can be used with any programming language, but its connections to
TCL run deep.</p>

<p>This document gives an overview of the Tcl
programming interface for SQLite.</p>








|
|







7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
  hd_resolve $text
}
</tcl>

<h1 align=center>The Tcl interface to the SQLite library</h1>

<p>The SQLite library is designed to be very easy to use from
a [http://www.tcl-lang.org | Tcl or Tcl/Tk] script.  SQLite
began as a [http://www.tcl-lang.org/doc/tea/ | Tcl extension]
and the primary [test suite] for SQLite is written in TCL.  SQLite
can be used with any programming language, but its connections to
TCL run deep.</p>

<p>This document gives an overview of the Tcl
programming interface for SQLite.</p>

Changes to pages/testing.in.

151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<li><p>
<tcl>hd_fragment tcl {TCL test suite}</tcl>
The <b>TCL Tests</b> are the oldest set of tests for SQLite.  
They are contained in the same source tree as the
SQLite core and like the SQLite core are in the public domain.  The
TCL tests are the primary tests used during development.
The TCL tests are written using the 
[http://www.tcl.tk/ | TCL scripting language].
The TCL test harness itself consists of <tcl>KB {$stat(tclcSLOC)}</tcl> KSLOC 
of C code used to create the TCL interface.  The test scripts are contained
in <tcl>N {$stat(tclsNFile)}</tcl> files totaling 
<tcl>MiB {$stat(tclsNByte)}</tcl>MB in size.  There are
<tcl>N {$stat(tclNTest)}</tcl> distinct test cases, but many of the test
cases are parameterized and run multiple times (with different parameters)
so that on a full test run millions of







|







151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
<li><p>
<tcl>hd_fragment tcl {TCL test suite}</tcl>
The <b>TCL Tests</b> are the oldest set of tests for SQLite.  
They are contained in the same source tree as the
SQLite core and like the SQLite core are in the public domain.  The
TCL tests are the primary tests used during development.
The TCL tests are written using the 
[http://www.tcl-lang.org/ | TCL scripting language].
The TCL test harness itself consists of <tcl>KB {$stat(tclcSLOC)}</tcl> KSLOC 
of C code used to create the TCL interface.  The test scripts are contained
in <tcl>N {$stat(tclsNFile)}</tcl> files totaling 
<tcl>MiB {$stat(tclsNByte)}</tcl>MB in size.  There are
<tcl>N {$stat(tclNTest)}</tcl> distinct test cases, but many of the test
cases are parameterized and run multiple times (with different parameters)
so that on a full test run millions of

Changes to pages/undoredo.in.

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<p>
Triggers such as the above could be entered manually, but that is tedious.
An important feature of the technique demonstrated below is 
that the triggers are generated automatically.

<p>
The implementation language for the example code is 
[http://www.tcl.tk|TCL], though you can easily do the same thing 
in another programming language.
Remember that the code here is a demonstration of the technique,
not a drop-in module that will automatically do everything for you.
The demonstration code shown below is derived from actual code 
in production use. But you will need to make changes to tailor it 
to your application.








|







82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<p>
Triggers such as the above could be entered manually, but that is tedious.
An important feature of the technique demonstrated below is 
that the triggers are generated automatically.

<p>
The implementation language for the example code is 
[http://www.tcl-lang.org|TCL], though you can easily do the same thing 
in another programming language.
Remember that the code here is a demonstration of the technique,
not a drop-in module that will automatically do everything for you.
The demonstration code shown below is derived from actual code 
in production use. But you will need to make changes to tailor it 
to your application.