System.Data.SQLite

Check-in [cf08e3867a]
Login

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

Overview
Comment:Pickup the SQLite core library 3.27.0 docs from upstream.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: cf08e3867a3bef1dea306be0fd08b08f51dbde66
User & Date: mistachkin 2019-02-08 02:11:35.304
Context
2019-02-08
02:14
Disable the production of 'fat binaries' on macOS. Fix for ticket [b41f1f002e]. check-in: 57ef270232 user: mistachkin tags: trunk
02:11
Pickup the SQLite core library 3.27.0 docs from upstream. check-in: cf08e3867a user: mistachkin tags: trunk
02:07
Update SQLite core library to the 3.27.0 release. Update version history docs. check-in: 07c06d7ebe user: mistachkin tags: trunk
Changes
Unified Diff Ignore Whitespace Patch
Changes to Doc/Extra/Core/images/syntax/expr.gif.

cannot compute difference between binary files

Changes to Doc/Extra/Core/images/syntax/select-core.gif.

cannot compute difference between binary files

Changes to Doc/Extra/Core/images/syntax/select-stmt.gif.

cannot compute difference between binary files

Changes to Doc/Extra/Core/images/syntax/vacuum-stmt.gif.

cannot compute difference between binary files

Changes to Doc/Extra/Core/lang_datefunc.html.
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
localtime_r() C function normally only works for years
between 1970 and 2037. For dates outside this range, SQLite 
attempts to map the year into an equivalent year within 
this range, do the calculation, then map the year back.</p>


<p>These functions only work for dates between 0000-01-01 00:00:00
and 9999-12-31 23:59:59 (julidan day numbers 1721059.5 through 5373484.5).
For dates outside that range, the results of these
functions are undefined.</p>

<p>Non-Vista Windows platforms only support one set of DST rules. 
Vista only supports two. Therefore, on these platforms, 
historical DST calculations will be incorrect. 
For example, in the US, in 2007 the DST rules changed. 







|







373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
localtime_r() C function normally only works for years
between 1970 and 2037. For dates outside this range, SQLite 
attempts to map the year into an equivalent year within 
this range, do the calculation, then map the year back.</p>


<p>These functions only work for dates between 0000-01-01 00:00:00
and 9999-12-31 23:59:59 (julian day numbers 1721059.5 through 5373484.5).
For dates outside that range, the results of these
functions are undefined.</p>

<p>Non-Vista Windows platforms only support one set of DST rules. 
Vista only supports two. Therefore, on these platforms, 
historical DST calculations will be incorrect. 
For example, in the US, in 2007 the DST rules changed. 
Changes to Doc/Extra/Core/lang_vacuum.html.
112
113
114
115
116
117
118








119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138






















































139
140
141
142
143
144
145
146
147




148
149
150
151
152
153
154

  <li> <p> Frequent inserts, updates, and deletes can cause the database file
     to become fragmented - where data for a single table or index is scattered 
     around the database file. Running VACUUM ensures that each table and
     index is largely stored contiguously within the database file. In some
     cases, VACUUM may also reduce the number of partially filled pages in
     the database, reducing the size of the database file further.









  <li> <p> Normally, the database <a href="pragma.html#pragma_page_size">page_size</a> and whether or not the database
     supports <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> must be configured before the database file is
     actually created. However, when not in <a href="wal.html">write-ahead log</a> mode, the 
     <a href="pragma.html#pragma_page_size">page_size</a> and/or <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> properties of an existing database may be
     changed by using the <a href="pragma.html#pragma_page_size">page_size</a>  and/or 
     <a href="pragma.html#pragma_auto_vacuum">pragma auto_vacuum</a> pragmas and then immediately VACUUMing
     the database. When in <a href="wal.html">write-ahead log</a> mode, only the <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a>
     support property can be changed using VACUUM.
</ul>

<p>By default, VACUUM only works only on the main database.
<a href="lang_attach.html">Attached databases</a> can be vacuumed by appending the appropriate
<span class='yyterm'>schema-name</span> to the VACUUM statement.

<p><b>Compatibility Warning:</b> The ability to vacuum attached databases was
added in <a href="releaselog/3_15_0.html">version 3.15.0</a> (2016-10-14).  Prior to that, a 
<span class='yyterm'>schema-name</span> added to the
VACUUM statement would be silently ignored and the "main" schema would be
vacuumed.</p>























































<p>The VACUUM command works by copying the contents of the database into
a temporary database file and then overwriting the original with the 
contents of the temporary file. When overwriting the original, a rollback
journal or <a href="wal.html">write-ahead log</a> WAL file is used just as it would be for any
other database transaction. This means that when VACUUMing a database, 
as much as twice the size of the original database file is required in free
disk space.





<p>The VACUUM command may change the <a href="lang_createtable.html#rowid">ROWIDs</a> of entries in any
tables that do not have an explicit <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a>.
</p>

<p>A VACUUM will fail if there is an open transaction, or if there are one or
more active SQL statements when it is run.








>
>
>
>
>
>
>
>




















>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>









>
>
>
>







112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

  <li> <p> Frequent inserts, updates, and deletes can cause the database file
     to become fragmented - where data for a single table or index is scattered 
     around the database file. Running VACUUM ensures that each table and
     index is largely stored contiguously within the database file. In some
     cases, VACUUM may also reduce the number of partially filled pages in
     the database, reducing the size of the database file further.

  <li> <p> When content is deleted from an SQLite database, the content is not
     usually erased but rather the space used to hold the content is marked as
     being available for reuse.  This can allow deleted content to be recovered
     by a hacker or by forensic analysis.  Running VACUUM will clean the database
     of all traces of deleted content, thus preventing an adversary from recovering
     deleted content.  Using VACUUM in this way is an alternative to setting
     <a href="pragma.html#pragma_secure_delete">PRAGMA secure_delete=ON</a>. 

  <li> <p> Normally, the database <a href="pragma.html#pragma_page_size">page_size</a> and whether or not the database
     supports <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> must be configured before the database file is
     actually created. However, when not in <a href="wal.html">write-ahead log</a> mode, the 
     <a href="pragma.html#pragma_page_size">page_size</a> and/or <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a> properties of an existing database may be
     changed by using the <a href="pragma.html#pragma_page_size">page_size</a>  and/or 
     <a href="pragma.html#pragma_auto_vacuum">pragma auto_vacuum</a> pragmas and then immediately VACUUMing
     the database. When in <a href="wal.html">write-ahead log</a> mode, only the <a href="pragma.html#pragma_auto_vacuum">auto_vacuum</a>
     support property can be changed using VACUUM.
</ul>

<p>By default, VACUUM only works only on the main database.
<a href="lang_attach.html">Attached databases</a> can be vacuumed by appending the appropriate
<span class='yyterm'>schema-name</span> to the VACUUM statement.

<p><b>Compatibility Warning:</b> The ability to vacuum attached databases was
added in <a href="releaselog/3_15_0.html">version 3.15.0</a> (2016-10-14).  Prior to that, a 
<span class='yyterm'>schema-name</span> added to the
VACUUM statement would be silently ignored and the "main" schema would be
vacuumed.</p>

<a name="vacuuminto"></a>

<h3>VACUUM with an INTO clause</h3>

<p>If the INTO clause is included, then the original database file is
unchanged and a new database is created in the filename given by the
argument to the INTO clause.  The new database will contain the same
logical content as the original database, fully vacuumed.

<p>
The VACUUM command with an INTO clause is an alternative to the
<a href="backup.html">backup API</a> for generating backup copies of a live database.
The advantage of using VACUUM INTO is that the resulting backup
database is minimal in size and hence the amount of filesystem
I/O may be reduced.  Also, all deleted content is purged from the
backup, leaving behind no forensic traces.  On the other hand,
the <a href="backup.html">backup API</a> uses fewer CPU cycles and can be executed
incrementally.

<p>
The filename in the INTO clause can be an arbitrary SQL expression
that evaluates to a string.
The file named by the INTO clause must not previously exist, or
else it must be an empty file, or the VACUUM INTO command will
fail with an error.

<p>
The argument to INTO can a <a href="uri.html">URI filename</a> if URI filenames
are enabled.
URL filenames are enabled if any of the following are true:
<ul>
<li> The SQLite library was compiled with <a href="compile.html#use_uri">-DSQLITE_USE_URI=1</a>.
<li> The <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_covering_index_scan.html#sqliteconfiguri">SQLITE_CONFIG_URI</a>,1) interfaces was
     invoked at start-time.
<li> The <a href="c3ref/sqlite3.html">database connection</a> that is running the VACUUM INTO
     statement was originally opened using the
     <a href="c3ref/c_open_autoproxy.html">SQLITE_OPEN_URI</a> flag.
</ul>

<p>
The VACUUM INTO command is transactional in the sense that
the generated output database is a consistent snapshot of the
original database.  However, if the VACUUM INTO command is
interrupted by a unplanned shutdown or power lose, then
the generated output database might be incomplete and corrupt.
Also, SQLite does not invoke fsync() or FlushFileBuffers()
on the generated database to ensure that it has reached
non-volatile storage before completing.


<a name="howvacuumworks"></a>

<h3>How VACUUM works</h3>

<p>The VACUUM command works by copying the contents of the database into
a temporary database file and then overwriting the original with the 
contents of the temporary file. When overwriting the original, a rollback
journal or <a href="wal.html">write-ahead log</a> WAL file is used just as it would be for any
other database transaction. This means that when VACUUMing a database, 
as much as twice the size of the original database file is required in free
disk space.

<p>The VACUUM INTO command works the same way except that it uses the file
named on the INTO clause in place of the temporary database and omits the
step of copying the vacuumed database back over top of the original database.

<p>The VACUUM command may change the <a href="lang_createtable.html#rowid">ROWIDs</a> of entries in any
tables that do not have an explicit <a href="lang_createtable.html#rowid">INTEGER PRIMARY KEY</a>.
</p>

<p>A VACUUM will fail if there is an open transaction, or if there are one or
more active SQL statements when it is run.

Changes to Doc/Extra/Core/pragma.html.
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
    returned by the same database connection at two different points in
    time.
<a name="pragma_database_list"></a>
<h _id=pragma_database_list style="display:none"> PRAGMA database_list</h><hr>
    <p><b>PRAGMA database_list;</b></p>
    <p>This pragma works like a query to return one row for each database
    attached to the current database connection.
    The second column is the "main" for the main database file, "temp"
    for the database file used to store TEMP objects, or the name of the
    ATTACHed database for other database files.
    The third column is the name of the database file itself, or an empty
    string if the database is not associated with a file.</p>
<a name="pragma_default_cache_size"></a>
<h _id=pragma_default_cache_size style="display:none"> PRAGMA default_cache_size</h><hr>
    <b>PRAGMA </b><i>schema.</i><b>default_cache_size;







|







662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
    returned by the same database connection at two different points in
    time.
<a name="pragma_database_list"></a>
<h _id=pragma_database_list style="display:none"> PRAGMA database_list</h><hr>
    <p><b>PRAGMA database_list;</b></p>
    <p>This pragma works like a query to return one row for each database
    attached to the current database connection.
    The second column is "main" for the main database file, "temp"
    for the database file used to store TEMP objects, or the name of the
    ATTACHed database for other database files.
    The third column is the name of the database file itself, or an empty
    string if the database is not associated with a file.</p>
<a name="pragma_default_cache_size"></a>
<h _id=pragma_default_cache_size style="display:none"> PRAGMA default_cache_size</h><hr>
    <b>PRAGMA </b><i>schema.</i><b>default_cache_size;
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
    flag.  When this flag is on, the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a>
    command (for changing the name of a table) works as it did
    in SQLite 3.24.0 (2018-06-04) and earlier.  More specifically,
    when this flag is on
    the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command only rewrites the initial occurrence
    of the table name in its <a href="lang_createtable.html">CREATE TABLE</a> statement and in any associated
    <a href="lang_createindex.html">CREATE INDEX</a> and <a href="lang_createtrigger.html">CREATE TRIGGER</a> statements.  Other references to the
    table are unmodifed, including:
    <ul>
    <li> References to the table within the bodies of triggers and views.
    <li> References to the table within CHECK constraints in the original
         CREATE TABLE statement.
    <li> References to the table within the WHERE clauses of <a href="partialindex.html">partial indexes</a>.
    </ul>
    The default setting for this pragma is OFF, which means that all







|







1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
    flag.  When this flag is on, the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a>
    command (for changing the name of a table) works as it did
    in SQLite 3.24.0 (2018-06-04) and earlier.  More specifically,
    when this flag is on
    the <a href="lang_altertable.html#altertabrename">ALTER TABLE RENAME</a> command only rewrites the initial occurrence
    of the table name in its <a href="lang_createtable.html">CREATE TABLE</a> statement and in any associated
    <a href="lang_createindex.html">CREATE INDEX</a> and <a href="lang_createtrigger.html">CREATE TRIGGER</a> statements.  Other references to the
    table are unmodified, including:
    <ul>
    <li> References to the table within the bodies of triggers and views.
    <li> References to the table within CHECK constraints in the original
         CREATE TABLE statement.
    <li> References to the table within the WHERE clauses of <a href="partialindex.html">partial indexes</a>.
    </ul>
    The default setting for this pragma is OFF, which means that all