Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Enhancements to the SQL language documentation. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
c8dc1e13d76c761223a9511137b37959 |
User & Date: | drh 2009-02-05 02:33:57.000 |
Context
2009-02-05
| ||
19:43 | Add a page with some backup API examples. (check-in: 0c996cb98b user: dan tags: trunk) | |
02:33 | Enhancements to the SQL language documentation. (check-in: c8dc1e13d7 user: drh tags: trunk) | |
2009-02-04
| ||
23:29 | Documentation changes in preparation for the 3.6.11 release. (check-in: b9fd0996f1 user: drh tags: trunk) | |
Changes
Changes to art/syntax/attach-stmt.gif.
cannot compute difference between binary files
Changes to art/syntax/bubble-generator.tcl.
︙ | ︙ | |||
58 59 60 61 62 63 64 | {line ADD {optx COLUMN} column-def} } } analyze-stmt { line ANALYZE {optx /database-name .} /table-name } attach-stmt { | | | 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | {line ADD {optx COLUMN} column-def} } } analyze-stmt { line ANALYZE {optx /database-name .} /table-name } attach-stmt { line ATTACH {or DATABASE nil} /filename AS /database-name } begin-stmt { line BEGIN {or nil DEFERRED IMMEDIATE EXCLUSIVE} {optx TRANSACTION} } commit-stmt { line {or COMMIT END} {optx TRANSACTION} |
︙ | ︙ |
Changes to art/syntax/syntax_linkage.tcl.
1 2 | set syntax_linkage(alter-table-stmt) {column-def sql-stmt} set syntax_linkage(analyze-stmt) {{} sql-stmt} | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | set syntax_linkage(alter-table-stmt) {column-def sql-stmt} set syntax_linkage(analyze-stmt) {{} sql-stmt} set syntax_linkage(attach-stmt) {{} sql-stmt} set syntax_linkage(begin-stmt) {{} sql-stmt} set syntax_linkage(column-constraint) {{conflict-clause expr foreign-key-clause literal-value signed-number} column-def} set syntax_linkage(column-def) {{column-constraint type-name} {alter-table-stmt create-table-stmt}} set syntax_linkage(comment-syntax) {{} {}} set syntax_linkage(commit-stmt) {{} sql-stmt} set syntax_linkage(compound-operator) {{} select-stmt} set syntax_linkage(conflict-clause) {{} {column-constraint table-constraint}} set syntax_linkage(create-index-stmt) {indexed-column sql-stmt} set syntax_linkage(create-table-stmt) {{column-def select-stmt table-constraint} sql-stmt} set syntax_linkage(create-trigger-stmt) {{delete-stmt expr insert-stmt select-stmt update-stmt} sql-stmt} set syntax_linkage(create-view-stmt) {select-stmt sql-stmt} set syntax_linkage(create-virtual-table-stmt) {{} sql-stmt} set syntax_linkage(delete-stmt) {{expr qualified-table-name} {create-trigger-stmt sql-stmt}} set syntax_linkage(delete-stmt-limited) {{expr ordering-term qualified-table-name} sql-stmt} set syntax_linkage(detach-stmt) {{} sql-stmt} set syntax_linkage(drop-index-stmt) {{} sql-stmt} set syntax_linkage(drop-table-stmt) {{} sql-stmt} set syntax_linkage(drop-trigger-stmt) {{} sql-stmt} set syntax_linkage(drop-view-stmt) {{} sql-stmt} set syntax_linkage(expr) {{literal-value raise-function select-stmt type-name} {column-constraint create-trigger-stmt delete-stmt delete-stmt-limited insert-stmt join-constraint ordering-term result-column select-stmt table-constraint update-stmt update-stmt-limited}} set syntax_linkage(foreign-key-clause) {{} {column-constraint table-constraint}} set syntax_linkage(indexed-column) {{} {create-index-stmt table-constraint}} set syntax_linkage(insert-stmt) {{expr select-stmt} {create-trigger-stmt sql-stmt}} set syntax_linkage(join-constraint) {expr join-source} set syntax_linkage(join-op) {{} join-source} set syntax_linkage(join-source) {{join-constraint join-op single-source} {select-stmt single-source}} set syntax_linkage(literal-value) {{} {column-constraint expr}} |
︙ | ︙ |
Changes to pages/compile.in.
︙ | ︙ | |||
670 671 672 673 674 675 676 | functions. This option is sometimes useful when trying to compile the date and time functions on a platform that does not support the concept of local time. } COMPILE_OPTION {SQLITE_OMIT_MEMORYDB} { When this is defined, the library does not respect the special database | | | 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 | functions. This option is sometimes useful when trying to compile the date and time functions on a platform that does not support the concept of local time. } COMPILE_OPTION {SQLITE_OMIT_MEMORYDB} { When this is defined, the library does not respect the special database name ":memory:" (normally used to create an [in-memory database]). If ":memory:" is passed to [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()], a file with this name will be opened or created. } COMPILE_OPTION {SQLITE_OMIT_OR_OPTIMIZATION} { This option disables the ability of SQLite to use an index together |
︙ | ︙ |
Added pages/inmemorydb.in.
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 | <title>In-Memory Databases</title> <tcl>hd_keywords {in-memory database} {in-memory databases} {memory}</tcl> <h1 align="center">In-Memory Databases</h1> <p>An SQLite database is normally stored in a single ordinary disk file. However, in certain circumstances, the database might be stored in memory.</p> <p>The most common way to force an SQLite database to exist purely in memory is to open the database using the special filename "<b>:memory:</b>". In other words, instead of passing the name of a real disk file into one of the [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()] functions, pass in the string ":memory:". For example:</p> <blockquote><pre> rc = sqlite3_open(":memory:", &db); </pre></blockquote> <p>When this is done, no disk file is opened. Instead, a new database is created purely in memory. The database ceases to exist as soon as the database connection is closed. Every :memory: database is distinct from every other. So, opening two database connections each with the filename ":memory:" will create two independent in-memory databases.</p> <p>The special filename ":memory:" can be used anywhere that a database filename is permitted. For example, it can be used as the <i>filename</i> in an [ATTACH] command:</p> <blockquote> <b>ATTACH DATABASE ':memory:' AS aux1;</b> </blockquote> <p>Note that in order for the special ":memory:" name to apply and to create a pure in-memory database, there must be no additional text in the filename. Thus, a disk-based database can be created in a file by prepending a pathname, like this: "./:memory:".</p> <tcl>hd_fragment temp_db {temporary tables} {temporary databases}</tcl> <h2>Temporary Databases</h2> <p>When the name of the database file handed to [sqlite3_open()] or to [ATTACH] is an empty string, then a new temporary file is created to hold the database.</p> <blockquote><pre> rc = sqlite3_open("", &db); </pre></blockquote> <blockquote><b> ATTACH DATABASE '' AS aux2; </b></blockquote> <p>A different temporary file is created each time, so that just like as with the special ":memory:" string, two database connections to temporary databases each have their own private database. Temporary databases are automatically deleted when the connection that created them closes.</p> <p>Even though a disk file is allocated for each temporary database, in practice the temporary database usually resides in the in-memory pager cache and hence is very little difference between a pure in-memory database created by ":memory:" and a temporary database created by an empty filename. The sole difference is that a ":memory:" database must remain in memory at all times whereas parts of a temporary database might be flushed to disk if database becomes large or if SQLite comes under memory pressure.</p> <p>The previous paragraphs describe the behavior of temporary databases under the default SQLite configuration. An application can use the [temp_store pragma] and the [SQLITE_TEMP_STORE] compile-time parameter to force temporary databases to behave as pure in-memory databases, if desired. </p> |
Changes to pages/lang.in.
︙ | ︙ | |||
201 202 203 204 205 206 207 | Section {ATTACH DATABASE} attach ATTACH BubbleDiagram attach-stmt 1 </tcl> <p>The ATTACH DATABASE statement adds another database file to the current database connection. If the filename contains | | | | | | 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | Section {ATTACH DATABASE} attach ATTACH BubbleDiagram attach-stmt 1 </tcl> <p>The ATTACH DATABASE statement adds another database file to the current database connection. If the filename contains punctuation characters it must be quoted. The database-names 'main' and 'temp' refer to the main database and the database used for temporary tables. These cannot be detached. Attached databases are removed using the [DETACH] statement.</p> <p>You cannot create a new table with the same name as a table in an attached database, but you can attach a database which contains tables whose names are duplicates of tables in the main database. It is also permissible to attach the same database file multiple times.</p> <p>Tables in an attached database can be referred to using the syntax <i>database-name.table-name</i>. If an attached table doesn't have a duplicate table name in the main database, it does not require a <i>database-name</i> prefix. When a database is attached, all of its tables which don't have duplicate names become the default table of that name. Any tables of that name attached afterwards require the database prefix. If the default table of a given name is detached, then the last table of that name attached becomes the new default.</p> <p> Transactions involving multiple attached databases are atomic, assuming that the main database is not "[:memory:]". If the main database is ":memory:" then transactions continue to be atomic within each individual database file. But if the host computer crashes in the middle of a [COMMIT] where two or more database files are updated, some of those files might get the changes where others might not. </p> |
︙ | ︙ | |||
404 405 406 407 408 409 410 | the ROLLBACK TO command restarts the transaction again at the beginning. All intervening SAVEPOINTs are cancelled, however.</p> <p>The RELEASE is like a [COMMIT] for a SAVEPOINT. The RELEASE command causes all savepoints back to and including the first savepoint with a matching name to be removed from the transaction stack. The RELEASE of an inner transaction | | | 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 | the ROLLBACK TO command restarts the transaction again at the beginning. All intervening SAVEPOINTs are cancelled, however.</p> <p>The RELEASE is like a [COMMIT] for a SAVEPOINT. The RELEASE command causes all savepoints back to and including the first savepoint with a matching name to be removed from the transaction stack. The RELEASE of an inner transaction does not cause any changes to be written to the database file; it merely removes savepoints from the transaction stack such that it is no longer possible to ROLLBACK TO those savepoints. If a RELEASE command releases the outermost savepoint, so that the transaction stack becomes empty, then RELEASE is the same as [COMMIT]. The [COMMIT] command may used to release all savepoints and commit the transaction even if the transaction was originally started |
︙ | ︙ | |||
555 556 557 558 559 560 561 | <p>There are no arbitrary limits on the number of indices that can be attached to a single table. The number of columns in an index is limited to [SQLITE_MAX_COLUMN].</p> <p>If the UNIQUE keyword appears between CREATE and INDEX then duplicate index entries are not allowed. Any attempt to insert a duplicate entry will result in an error. For the purposes of unique indices, all NULL values | | > > > > | 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 | <p>There are no arbitrary limits on the number of indices that can be attached to a single table. The number of columns in an index is limited to [SQLITE_MAX_COLUMN].</p> <p>If the UNIQUE keyword appears between CREATE and INDEX then duplicate index entries are not allowed. Any attempt to insert a duplicate entry will result in an error. For the purposes of unique indices, all NULL values are considered to different from all other NULL values and are thus unique. This is one of the two possible interpretations of the SQL-92 standard (the language in the standard is ambiguious) and is the interpretation followed by PostgreSQL, MySQL, Firebird, and Oracle. Informix and Microsoft SQL Server follow the other interpretation of the standard.</p> <p>The text of each CREATE INDEX statement is stored in the <b>sqlite_master</b> or <b>sqlite_temp_master</b> table, depending on whether the table being indexed is temporary. Every time the database is opened, all CREATE INDEX statements are read from the <b>sqlite_master</b> table and used to regenerate |
︙ | ︙ | |||
2241 2242 2243 2244 2245 2246 2247 | ############################################################################## Section VACUUM vacuum VACUUM BubbleDiagram vacuum-stmt 1 </tcl> <p>When an object (table, index, or trigger) is dropped from the | | > > | | | > | 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 | ############################################################################## Section VACUUM vacuum VACUUM BubbleDiagram vacuum-stmt 1 </tcl> <p>When an object (table, index, or trigger) is dropped from the database, it leaves behind empty space. This empty space will be reused the next time new information is added to the database. But in the meantime, the database file might be larger than strictly necessary. Also, frequent inserts, updates, and deletes can cause the information in the database to become fragmented - scrattered out all across the database file rather than clustered together in one place.</p> <p>The VACUUM command cleans the main database by copying its contents to a temporary database file and reloading the original database file from the copy. This eliminates free pages, aligns table data to be contiguous, and otherwise cleans up the database file structure.</p> |
︙ | ︙ | |||
2269 2270 2271 2272 2273 2274 2275 | <p>As of SQLite version 3.1, an alternative to using the VACUUM command is auto-vacuum mode, enabled using the [auto_vacuum] pragma. When [auto_vacuum] is enabled for a database, large deletes cause the size of the database file to shrink. However, [auto_vacuum] also causes excess fragmentation of the database file. And [auto_vacuum] does not compact partially filled pages of the database as VACUUM | | | > > > > | 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 | <p>As of SQLite version 3.1, an alternative to using the VACUUM command is auto-vacuum mode, enabled using the [auto_vacuum] pragma. When [auto_vacuum] is enabled for a database, large deletes cause the size of the database file to shrink. However, [auto_vacuum] also causes excess fragmentation of the database file. And [auto_vacuum] does not compact partially filled pages of the database as VACUUM does.</p> <p>The [page_size] and/or [auto_vacuum] mode of a database can be changed by invoking the [page_size pragma] and/or [auto_vacuum pragma] and then immediately VACUUMing the database.</p> <tcl> ############################################################################## Section {INDEXED BY} indexedby {{INDEXED BY} {NOT INDEXED}} </tcl> <p>The INDEXED BY phrase is a SQL extension found only in SQLite which can be used to verify that the correct indices are being used on a [DELETE], |
︙ | ︙ | |||
2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 | to change. The INDEXED BY clause is designed to help detect undesirable query plan changes during regression testing. Developers are admonished to omit all use of INDEXED BY during application design, implementation, testing, and tuning. If INDEXED BY is to be used at all, it should be inserted at the very end of the development process when "locking down" a design.</p> <tcl> ############################################################################# # A list of keywords. A asterisk occurs after the keyword if it is on # the fallback list. # set keyword_list [lsort { ABORT* | > > > > > > > > > | 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 | to change. The INDEXED BY clause is designed to help detect undesirable query plan changes during regression testing. Developers are admonished to omit all use of INDEXED BY during application design, implementation, testing, and tuning. If INDEXED BY is to be used at all, it should be inserted at the very end of the development process when "locking down" a design.</p> <h3>See Also:</h3> <p>The [sqlite3_stmt_status()] C/C++ interface together with the [SQLITE_STMTSTATUS_FULLSCAN_STEP] and [SQLITE_STMTSTATUS_SORT] verbs can be used to detect at run-time when an SQL statement is not making effective use of indices. Many applications may prefer to use the [sqlite3_stmt_status()] interface to detect index misuse rather than the INDEXED BY phrase described here.</p> <tcl> ############################################################################# # A list of keywords. A asterisk occurs after the keyword if it is on # the fallback list. # set keyword_list [lsort { ABORT* |
︙ | ︙ |
Changes to pages/pragma.in.
︙ | ︙ | |||
549 550 551 552 553 554 555 | <br>PRAGMA temp_store = DEFAULT;</b> (0)<b> <br>PRAGMA temp_store = FILE;</b> (1)<b> <br>PRAGMA temp_store = MEMORY;</b> (2)</p> <p>Query or change the setting of the "<b>temp_store</b>" parameter. When temp_store is DEFAULT (0), the compile-time C preprocessor macro [SQLITE_TEMP_STORE] is used to determine where temporary tables and indices are stored. When | | > | | 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 | <br>PRAGMA temp_store = DEFAULT;</b> (0)<b> <br>PRAGMA temp_store = FILE;</b> (1)<b> <br>PRAGMA temp_store = MEMORY;</b> (2)</p> <p>Query or change the setting of the "<b>temp_store</b>" parameter. When temp_store is DEFAULT (0), the compile-time C preprocessor macro [SQLITE_TEMP_STORE] is used to determine where temporary tables and indices are stored. When temp_store is MEMORY (2) [temporary tables] and indices are kept in as if they were pure [in-memory databases] memory. When temp_store is FILE (1) [temporary tables] and indices are stored in a file. The <a href="#pragma_temp_store_directory"> temp_store_directory</a> pragma can be used to specify the directory containing this file. <b>FILE</b> is specified. When the temp_store setting is changed, all existing temporary tables, indices, triggers, and views are immediately deleted.</p> |
︙ | ︙ | |||
602 603 604 605 606 607 608 | </li> <br> <tcl>Subsection temp_store_directory</tcl> <li><p><b>PRAGMA temp_store_directory; <br>PRAGMA temp_store_directory = 'directory-name';</b></p> <p>Query or change the setting of the "temp_store_directory" - the | | | > | 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 | </li> <br> <tcl>Subsection temp_store_directory</tcl> <li><p><b>PRAGMA temp_store_directory; <br>PRAGMA temp_store_directory = 'directory-name';</b></p> <p>Query or change the setting of the "temp_store_directory" - the directory where files used for storing [temporary tables] and indices are kept. This setting lasts for the duration of the current connection only and resets to its default value for each new connection opened. <p>When the temp_store_directory setting is changed, all existing temporary tables, indices, triggers, and viewers are immediately deleted. In practice, temp_store_directory should be set immediately after the database is opened. </p> <p>The value <i>directory-name</i> should be enclosed in single quotes. To revert the directory to the default, set the <i>directory-name</i> to an empty string, e.g., <i>PRAGMA temp_store_directory = ''</i>. An error is raised if <i>directory-name</i> is not found or is not writable. </p> <p>The default directory for temporary files depends on the OS. For Unix (Linux and Mac OS X), the default is the is the first writable directory found in the list of: <b>/var/tmp, /usr/tmp, /tmp,</b> and <b> <i>current-directory</i></b>. For Windows, the default directory is determined by the O/S, generally <b>C:\Documents and Settings\<i>user-name</i>\Local Settings\Temp\</b>. Temporary files created by SQLite are unlinked immediately after opening, so that the operating system can automatically delete the files when the SQLite process exits. Thus, temporary files are not |
︙ | ︙ |
Changes to pages/sqlite.in.
︙ | ︙ | |||
560 561 562 563 564 565 566 | to that function.</p> <h3>Compiling the sqlite3 program from sources</h3> <p> | | > > | < > > | > > | 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 | to that function.</p> <h3>Compiling the sqlite3 program from sources</h3> <p> The source code to the sqlite3 command line interface is in a single file named "shell.c" which you can <a href="http://www.sqlite.org/cvstrac/rlog?f=sqlite/src/shell.c"> download</a> from the SQLite website. Compile this file (together with the [amalgamation | sqlite3 library source code] to generate the executable. For example:</p> <blockquote><pre> gcc -o sqlite3 shell.c sqlite3.c -ldl -lpthread </pre></blockquote> |
Changes to pages/tclsqlite.in.
︙ | ︙ | |||
34 35 36 37 38 39 40 | command to control the database. The name of the new Tcl command is given by the first argument. This approach is similar to the way widgets are created in Tk. </p> <p> The name of the database is just the name of a disk file in which | | | | > > | 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | command to control the database. The name of the new Tcl command is given by the first argument. This approach is similar to the way widgets are created in Tk. </p> <p> The name of the database is just the name of a disk file in which the database is stored. If the name of the database is the special name "[:memory:]" then a new database is created in memory. If the name of the database is an empty string, then the database is created in an empty file that is automatically deleted when the database connection closes. </p> <p> Once an SQLite database is open, it can be controlled using methods of the <i>dbcmd</i>. There are currently 22 methods defined.</p> |
︙ | ︙ |