Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Fix a few spelling typos. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
c3ed16c6d33ba2e348f788ee05f957b8 |
User & Date: | dan 2009-08-10 11:46:56.000 |
Context
2009-08-14
| ||
18:26 | Update hyperlinks to point at the fossil-scm rather than CVSTrac. (check-in: 8de414fe8f user: drh tags: trunk) | |
2009-08-10
| ||
11:46 | Fix a few spelling typos. (check-in: c3ed16c6d3 user: dan tags: trunk) | |
11:26 | Fix typo in serverless.html. (check-in: 1ac9233c15 user: dan tags: trunk) | |
Changes
Changes to pages/backup.in.
︙ | ︙ | |||
125 126 127 128 129 130 131 | ** connection pFile to the main database of connection pInMemory. ** If something goes wrong, pBackup will be set to NULL and an error ** code and message left in connection pTo. ** ** If the backup object is successfully created, call backup_step() ** to copy data from pFile to pInMemory. Then call backup_finish() ** to release resources associated with the pBackup object. If an | | | | 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 | ** connection pFile to the main database of connection pInMemory. ** If something goes wrong, pBackup will be set to NULL and an error ** code and message left in connection pTo. ** ** If the backup object is successfully created, call backup_step() ** to copy data from pFile to pInMemory. Then call backup_finish() ** to release resources associated with the pBackup object. If an ** error occurred, then an error code and message will be left in ** connection pTo. If no error occurred, then the error code belonging ** to pTo is set to SQLITE_OK. */ pBackup = sqlite3_backup_init(pTo, "main", pFrom, "main"); if( pBackup ){ (void)sqlite3_backup_step(pBackup, -1); (void)sqlite3_backup_finish(pBackup); } |
︙ | ︙ |
Changes to pages/fileformat.in.
︙ | ︙ | |||
258 259 260 261 262 263 264 | The table B-Tree with root-page 1 used to store database records describing the database schema. Accessible as the "sqlite_master" table from within SQLite. <tr><td>Schema version <td> A 32-bit integer field stored at byte offset 40 of the database file header (see section <cite>database_header</cite>). Normally, SQLite | | | 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 | The table B-Tree with root-page 1 used to store database records describing the database schema. Accessible as the "sqlite_master" table from within SQLite. <tr><td>Schema version <td> A 32-bit integer field stored at byte offset 40 of the database file header (see section <cite>database_header</cite>). Normally, SQLite increments this value each time it modifies the database schema. <tr><td>Table B-Tree <td> One of two variants on the B-Tree data structure used within SQLite database files. A table B-Tree (section <cite>table_btrees</cite>) uses 64 bit integers as key values and stores an associated database record along with each key value. |
︙ | ︙ | |||
435 436 437 438 439 440 441 | the relationships between various database image substructures, invariants that are true for all well-formed database images. <p> A well-formed SQLite database image is defined as an image for which all of the statements itemized as requirements within this section are true. <span class=todo>mention the requirements numbering scheme | | | 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 | the relationships between various database image substructures, invariants that are true for all well-formed database images. <p> A well-formed SQLite database image is defined as an image for which all of the statements itemized as requirements within this section are true. <span class=todo>mention the requirements numbering scheme here.</span> A software system that wishes to inter-operate with other systems using the SQLite database image format should only ever output well-formed SQLite databases. In the case of SQLite itself, the system should ensure that the database file contains a well-formed database image the conclusion of each transaction. [h2 "Image Format Overview" "fileformat_overview"] <p> |
︙ | ︙ | |||
462 463 464 465 466 467 468 | the contents of the <i>sqlite_master</i> table, and one B-Tree for each database table or index created by the user. If the database uses auto-increment integer primary keys, then the database file also contains a B-Tree to store the contents of the automatically created <i>sqlite_sequence</i> table. <p> SQLite uses two distinct variants of the B-Tree structure. One variant, | | | 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 | the contents of the <i>sqlite_master</i> table, and one B-Tree for each database table or index created by the user. If the database uses auto-increment integer primary keys, then the database file also contains a B-Tree to store the contents of the automatically created <i>sqlite_sequence</i> table. <p> SQLite uses two distinct variants of the B-Tree structure. One variant, hereafter referred to as a "table B-Tree" uses signed 64-bit integer values as keys. Each entry has an associated variable length blob of data used to store a database record (see section <cite>record_format</cite>). Each SQLite database file contains one table B-Tree for the schema table and one table B-Tree for each additional database table created by the user. If it is present, the sqlite_sequence table is also stored as a table B-Tree. <p> |
︙ | ︙ | |||
1032 1033 1034 1035 1036 1037 1038 | </table> <p> When using the full 9 byte representation, the first byte contains the 7 most significant bits of the 64-bit value. The final byte of the 9 byte representation contains the 8 least significant bits of the 64-bit value. When using one of the other representations, the final byte contains the 7 least significant bits of the 64-bit value. | | | | 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 | </table> <p> When using the full 9 byte representation, the first byte contains the 7 most significant bits of the 64-bit value. The final byte of the 9 byte representation contains the 8 least significant bits of the 64-bit value. When using one of the other representations, the final byte contains the 7 least significant bits of the 64-bit value. The second last byte, if present, contains the 7 next least significant bits of the value, and so on. The significant bits of the 64-bit value for which no storage is provided are assumed to be zero. <p> When encoding a variable length integer, SQLite usually selects the most compact representation that provides enough storage to accommodate the most significant set bit of the value. This is not required however, using more bytes than is strictly necessary when encoding an integer is valid. [Table] [Tr]<th>Decimal<th>Hexadecimal <th>Variable Length Integer [Tr]<td>43 <td>0x000000000000002B <td>0x2B |
︙ | ︙ | |||
1606 1607 1608 1609 1610 1611 1612 | [fancyformat_import_requirement H31130] [fancyformat_import_requirement H31140] <p> Most of the requirements specified in section <cite>index_btree_page_format</cite> also apply to table B-Tree pages. The wording of the requirements make it clear when this is | | | 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 | [fancyformat_import_requirement H31130] [fancyformat_import_requirement H31140] <p> Most of the requirements specified in section <cite>index_btree_page_format</cite> also apply to table B-Tree pages. The wording of the requirements make it clear when this is the case, either by referring to generic "B-Tree pages" or by explicitly stating that the statement applies to both "table and index B-Tree pages". [h4 "Table B-Tree Cell Format" table_btree_cell_format] <p> Cells stored on internal table B-Tree nodes consist of exactly two fields. The associated child page number, stored as a 4-byte |
︙ | ︙ | |||
2400 2401 2402 2403 2404 2405 2406 | The following requirements dictate the way in which the data for each page of the database image can be located within the file-system by a database reader. [fancyformat_import_requirement H32070] [fancyformat_import_requirement H32080] | | | 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 | The following requirements dictate the way in which the data for each page of the database image can be located within the file-system by a database reader. [fancyformat_import_requirement H32070] [fancyformat_import_requirement H32080] [h1 "SQLite Interoperability Requirements" interoperability_requirements] <p> This section contains requirements that further constrains the behaviour of software that accesses (reads and/or writes) SQLite databases stored within the file-system. These requirements need only be implemented by systems that access databases while other clients may also be doing so. More specifically, they need only be implemented by software operating |
︙ | ︙ | |||
2454 2455 2456 2457 2458 2459 2460 | processing. For example, SQLite itself runs in several different modes with various levels of guarantees on how failures are handled as follows: <ul> <li> <b>In-memory journal mode</b> (PRAGMA journal_mode=memory). In this mode any failure may cause database file-system corruption, including an application crash or unexpected exit. | | | | 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 | processing. For example, SQLite itself runs in several different modes with various levels of guarantees on how failures are handled as follows: <ul> <li> <b>In-memory journal mode</b> (PRAGMA journal_mode=memory). In this mode any failure may cause database file-system corruption, including an application crash or unexpected exit. <li> <b>Non-synchronous mode</b> (PRAGMA synchronous=off). In this mode an application crash or unexpected exit may not cause database corruption, however an operating system crash or power failure may. <li> <b>Synchronous mode</b> (PRAGMA synchronous=full). In this mode neither an application crash, operating system crash or power failure may cause database file-system corruption. </ul> <p> If a process attempts to modify a database so as to replace database image A with database image B and a failure occurs while doing so, |
︙ | ︙ | |||
2587 2588 2589 2590 2591 2592 2593 | valid, so the database image consists of the contents of the database file, database image B. <p> Figure <cite>figure_filesystem2</cite> depicts a possible interim state of the database file-system representation used while committing a transaction that replaces a four page database image with a three page database image. The contents of the initial database image pages are A, B, C and D respectively. | | | | 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 | valid, so the database image consists of the contents of the database file, database image B. <p> Figure <cite>figure_filesystem2</cite> depicts a possible interim state of the database file-system representation used while committing a transaction that replaces a four page database image with a three page database image. The contents of the initial database image pages are A, B, C and D respectively. The final database image content is A, E and C. The interim state depicted is that reached at the end of step 4 in the above procedure. In this state, the file-system contains the initial database image, ABCD. However, if the journal file were to be somehow invalidated, then the file-system would contain the final database image, AEC. [Figure filesystem2.gif figure_filesystem2 "Interim file-system state used to atomically overwrite database image ABCD with AEC"] <p> The procedure described above can be onerous to implement, as it requires that the data for all modified pages of database image B be available (presumably in main memory) at the same time, when step 4 is performed. For transactions that write to a large number of database pages, this may be undesirable. A solution is to create a journal-file containing two or more journal headers. If, while modifying a database image within main-memory, a client wishes to reduce the amount of data held in memory, it may perform steps 3 and 4 of the above procedure in order to write |
︙ | ︙ |
Changes to pages/testing.in.
︙ | ︙ | |||
327 328 329 330 331 332 333 | <p>There are numerous test cases that verify that SQLite is able to deal with malformed database files. These tests first build a well-formed database file, then add corruption by changing one or more bytes in the file by some means other than SQLite. Then SQLite is used to read the database. In some cases, the bytes changes are in the middle of data. | | | 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 | <p>There are numerous test cases that verify that SQLite is able to deal with malformed database files. These tests first build a well-formed database file, then add corruption by changing one or more bytes in the file by some means other than SQLite. Then SQLite is used to read the database. In some cases, the bytes changes are in the middle of data. This causes the content of the database to change while keeping the database well-formed. In other cases, unused bytes of the file are modified, which as no effect on the integrity of the database. The interesting cases are when bytes of the file that define database structure get changed. The malformed database tests verify that SQLite finds the file format errors and reports them using the SQLITE_CORRUPT return code without overflowing |
︙ | ︙ | |||
484 485 486 487 488 489 490 | should yield exactly the same result. There is a run-time test using the [sqlite3_test_control]([SQLITE_TESTCTRL_ALWAYS], ...) interface that can be used to verify that the macros are correctly set to the first form (the pass-through form) for deployment.</p> <h3>7.3 Forcing coverage of boundary values and boolean vector tests</h3> | | | 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 | should yield exactly the same result. There is a run-time test using the [sqlite3_test_control]([SQLITE_TESTCTRL_ALWAYS], ...) interface that can be used to verify that the macros are correctly set to the first form (the pass-through form) for deployment.</p> <h3>7.3 Forcing coverage of boundary values and boolean vector tests</h3> <p>Another macro used in conjunction with test coverage measurement is the <tt>testcase()</tt> macro. The argument is a condition for which we want test cases that evaluate to both true and false. In non-coverage builds (that is to so, in release builds) the testcase() macro is a no-op:</p> <blockquote><pre> #define testcase(X) |
︙ | ︙ | |||
554 555 556 557 558 559 560 | <li> Each decision tries every possible outcome. <li> Each condition in a decision takes on every possible outcome. <li> Each entry and exit point is invoked. <li> Each condition in a decision is shown to independently affect the outcome of the decision. </ul> | | | | 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 | <li> Each decision tries every possible outcome. <li> Each condition in a decision takes on every possible outcome. <li> Each entry and exit point is invoked. <li> Each condition in a decision is shown to independently affect the outcome of the decision. </ul> <p>In the C programming language where the <tt>&&</tt> and <tt>||</tt> operator are "short-circuit" operators, MC/DC and branch coverage are very nearly the same thing. The primary difference is in boolean vector tests. One can test for any of several bits in bit-vector and still obtain 100% branch test coverage even though the second element of MC/DC - the requirement that each condition in a decision take on every possible outcome - might not be satisfied.</p> <p>SQLite uses <tt>testcase()</tt> macros as described in the previous subsection to make sure that every condition in a bit-vector decision takes on every possible outcome. In this way, SQLite also achieves 100% MC/DC in addition to 100% branch coverage.</p> <h3>7.5 Experience with full test coverage</h3> <p>The developers of SQLite have found that full coverage testing is an extremely productive method for preventing the introduction of new bugs as the system evolves. Because every single branch instruction in SQLite core code is covered by test cases, the developers can be confident that changes they make in one part of the code do not have unintended consequences in other parts of the code. It would extremely difficult maintain the quality of SQLite without such assurances.</p> <h2>8.0 Dynamic Analysis</h2> |
︙ | ︙ |
Changes to pages/unlock_notify.in.
︙ | ︙ | |||
196 197 198 199 200 201 202 | wait_for_unlock_notify(), it is possible that the blocking connection that prevented the sqlite3_step() or sqlite3_prepare_v2() call from succeeding has already finished its transaction. In this case, the unlock-notify callback is invoked immediately, before [sqlite3_unlock_notify()] returns. Or, it is possible that the unlock-notify callback is invoked by a second thread after [sqlite3_unlock_notify()] is called but before the thread starts waiting | | | 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 | wait_for_unlock_notify(), it is possible that the blocking connection that prevented the sqlite3_step() or sqlite3_prepare_v2() call from succeeding has already finished its transaction. In this case, the unlock-notify callback is invoked immediately, before [sqlite3_unlock_notify()] returns. Or, it is possible that the unlock-notify callback is invoked by a second thread after [sqlite3_unlock_notify()] is called but before the thread starts waiting to be asynchronously signaled. <p> Exactly how such a potential race-condition is handled depends on the threads and synchronization primitives interface used by the application. This example uses pthreads, the interface provided by modern UNIX-like systems, including Linux. <p> The pthreads interface provides the pthread_cond_wait() function. |
︙ | ︙ | |||
227 228 229 230 231 232 233 | <p> When the wait_for_unlock_notify() thread is ready to begin waiting for the unlock-notify callback to arrive, it: <ol> <li> Obtains the mutex. <li> Checks if the "fired" flag has been set. If so, the unlock-notify callback has already been invoked. Release the mutex and continue. | | | 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 | <p> When the wait_for_unlock_notify() thread is ready to begin waiting for the unlock-notify callback to arrive, it: <ol> <li> Obtains the mutex. <li> Checks if the "fired" flag has been set. If so, the unlock-notify callback has already been invoked. Release the mutex and continue. <li> aAtomically releases the mutex and begins waiting for the asynchronous signal. When the signal arrives, continue. </ol> <p> This way, it doesn't matter if the unlock-notify callback has already been invoked, or is being invoked, when the wait_for_unlock_notify() thread begins blocking. |
︙ | ︙ | |||
251 252 253 254 255 256 257 | <p> Even though the [sqlite3_unlock_notify()] function only allows the caller to specify a single user-context pointer, an unlock-notify callback is passed an array of such context pointers. This is because if when a blocking connection concludes its transaction, if there is more than one unlock-notify registered to call the same C function, the | | | | | 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 | <p> Even though the [sqlite3_unlock_notify()] function only allows the caller to specify a single user-context pointer, an unlock-notify callback is passed an array of such context pointers. This is because if when a blocking connection concludes its transaction, if there is more than one unlock-notify registered to call the same C function, the context-pointers are marshaled into an array and a single callback issued. If each thread were assigned a priority, then instead of just signaling the threads in arbitrary order as this implementation does, higher priority threads could be signaled before lower priority threads. <p> If a "DROP TABLE" or "DROP INDEX" SQL command is executed, and the associated database connection currently has one or more actively executing SELECT statements, then SQLITE_LOCKED is returned. If [sqlite3_unlock_notify()] is called in this case, then the specified callback will be invoked immediately. Unless the other running SELECT |
︙ | ︙ |
Changes to pages/whentouse.in.
︙ | ︙ | |||
228 229 230 231 232 233 234 | <p>With the default page size of 1024 bytes, an SQLite database is limited in size to 2 tebibytes (2<sup><small>41</small></sup> bytes). And even if it could handle larger databases, SQLite stores the entire database in a single disk file and many filesystems limit the maximum size of files to something less than this. So if you are contemplating databases of this magnitude, you would do well to consider using a client/server database engine that spreads its content across multiple | | | 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | <p>With the default page size of 1024 bytes, an SQLite database is limited in size to 2 tebibytes (2<sup><small>41</small></sup> bytes). And even if it could handle larger databases, SQLite stores the entire database in a single disk file and many filesystems limit the maximum size of files to something less than this. So if you are contemplating databases of this magnitude, you would do well to consider using a client/server database engine that spreads its content across multiple disk files, and perhaps across multiple volumes. </p> </li> <li><p><b>High Concurrency</b></p> <p> SQLite uses reader/writer locks on the entire database file. That means |
︙ | ︙ |