Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Comment: | Complete reorganization of the documentation sources. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
275febef8faf17827a432ef6e1ed1d01 |
User & Date: | drh 2007-11-12 15:32:09.000 |
2007-11-12
| ||
20:38 | Generate C interface reference document both as the single big file and also as lots of individual small files. (check-in: ae0c38c662 user: drh tags: trunk) | |
15:32 | Complete reorganization of the documentation sources. (check-in: 275febef8f user: drh tags: trunk) | |
03:45 | Initial check-in of documentation sources. (check-in: 6dc1e6a1f3 user: drh tags: trunk) | |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | #FIG 3.2 Portrait Center Inches Letter 100.00 Single -2 1200 2 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 8550 3675 9075 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 7200 3675 7725 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 5775 3675 6300 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 3975 3675 4500 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 2625 3675 3150 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 1275 3675 1800 2 1 0 3 0 7 100 0 -1 0.000 0 0 -1 1 0 2 1 1 3.00 75.00 135.00 3675 9900 3675 10425 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 10425 4875 10425 4875 11250 2550 11250 2550 10425 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 9075 4875 9075 4875 9900 2550 9900 2550 9075 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 7725 4875 7725 4875 8550 2550 8550 2550 7725 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 6300 4875 6300 4875 7200 2550 7200 2550 6300 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 4500 4875 4500 4875 5775 2550 5775 2550 4500 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 3150 4875 3150 4875 3975 2550 3975 2550 3150 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 1800 4875 1800 4875 2625 2550 2625 2550 1800 2 2 0 1 0 11 100 0 20 0.000 0 0 7 0 0 5 2550 450 4875 450 4875 1275 2550 1275 2550 450 4 1 0 100 0 0 20 0.0000 4 195 1020 3675 750 Interface\001 4 1 0 100 0 0 14 0.0000 4 195 2040 3675 1125 main.c table.c tclsqlite.c\001 4 1 0 100 0 0 20 0.0000 4 195 1920 3675 6675 Virtual Machine\001 4 1 0 100 0 0 14 0.0000 4 150 570 3675 7050 vdbe.c\001 4 1 0 100 0 0 20 0.0000 4 195 1830 3675 4875 Code Generator\001 4 1 0 100 0 0 14 0.0000 4 195 1860 3675 5175 build.c delete.c expr.c\001 4 1 0 100 0 0 14 0.0000 4 195 2115 3675 5400 insert.c select.c update.c\001 4 1 0 100 0 0 14 0.0000 4 150 705 3675 5625 where.c\001 4 1 0 100 0 0 20 0.0000 4 195 735 3675 3450 Parser\001 4 1 0 100 0 0 20 0.0000 4 195 1140 3675 2100 Tokenizer\001 4 1 0 100 0 0 14 0.0000 4 150 870 3675 2475 tokenize.c\001 4 1 0 100 0 0 20 0.0000 4 255 1350 3675 9375 Page Cache\001 4 1 0 100 0 0 14 0.0000 4 150 630 3675 3825 parse.y\001 4 1 0 100 0 0 14 0.0000 4 150 600 3675 8400 btree.c\001 4 1 0 100 0 0 14 0.0000 4 150 645 3675 9750 pager.c\001 4 1 0 100 0 0 20 0.0000 4 195 1620 3675 8025 B-tree Driver\001 4 1 0 100 0 0 14 0.0000 4 105 345 3675 11100 os.c\001 4 1 0 100 0 0 20 0.0000 4 195 1470 3675 10725 OS Interface\001 |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | #FIG 3.2 Landscape Center Inches Letter 100.00 Single -2 1200 2 0 32 #000000 0 33 #868686 0 34 #dfefd7 0 35 #d7efef 0 36 #efdbef 0 37 #efdbd7 0 38 #e7efcf 0 39 #9e9e9e 6 3225 3900 4650 6000 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 4350 3900 4650 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 5100 3900 5475 4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001 4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001 4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001 -6 6 5400 4725 6825 5250 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 4725 6750 4725 6750 5175 5400 5175 5400 4725 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 4800 6825 4800 6825 5250 5475 5250 5475 4800 4 1 0 50 0 2 12 0.0000 4 135 630 6000 5025 Utilities\001 -6 6 5400 5550 6825 6075 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 5550 6750 5550 6750 6000 5400 6000 5400 5550 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 5625 6825 5625 6825 6075 5475 6075 5475 5625 4 1 0 50 0 2 12 0.0000 4 135 855 6000 5850 Test Code\001 -6 6 5400 2775 6825 3750 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 2850 6825 2850 6825 3750 5475 3750 5475 2850 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 2775 6750 2775 6750 3675 5400 3675 5400 2775 4 1 0 50 0 2 12 0.0000 4 135 420 6075 3150 Code\001 4 1 0 50 0 2 12 0.0000 4 135 855 6075 3375 Generator\001 -6 6 5400 1950 6825 2475 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 1950 6750 1950 6750 2400 5400 2400 5400 1950 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 2025 6825 2025 6825 2475 5475 2475 5475 2025 4 1 0 50 0 2 12 0.0000 4 135 570 6075 2250 Parser\001 -6 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 1500 3900 1800 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 2250 3900 2550 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 3000 3900 3900 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 4575 1950 5400 1350 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 5400 2925 4650 2325 2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5 2850 750 4875 750 4875 3375 2850 3375 2850 750 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 6075 1500 6075 1950 2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5 2850 3675 4875 3675 4875 6225 2850 6225 2850 3675 2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5 5175 750 7200 750 7200 4050 5175 4050 5175 750 2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5 5175 4425 7200 4425 7200 6225 5175 6225 5175 4425 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 6075 2475 6075 2775 4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001 4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001 4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001 4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001 4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001 4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001 4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001 4 1 0 50 0 1 12 1.5708 4 135 885 7125 5400 Accessories\001 4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001 |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | #FIG 3.2 Landscape Center Inches Letter 100.00 Single -2 1200 2 0 32 #000000 0 33 #868686 0 34 #dfefd7 0 35 #d7efef 0 36 #efdbef 0 37 #efdbd7 0 38 #e7efcf 0 39 #9e9e9e 6 3225 3900 4650 6000 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 5475 4575 5475 4575 5925 3225 5925 3225 5475 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 5550 4650 5550 4650 6000 3300 6000 3300 5550 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 4650 4575 4650 4575 5100 3225 5100 3225 4650 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 4725 4650 4725 4650 5175 3300 5175 3300 4725 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 3900 4575 3900 4575 4350 3225 4350 3225 3900 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 3975 4650 3975 4650 4425 3300 4425 3300 3975 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 4350 3900 4650 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 5100 3900 5475 4 1 0 50 0 2 12 0.0000 4 135 1050 3900 5775 OS Interface\001 4 1 0 50 0 2 12 0.0000 4 135 615 3900 4200 B-Tree\001 4 1 0 50 0 2 12 0.0000 4 180 495 3900 4950 Pager\001 -6 6 5175 4275 7200 6150 6 5400 4519 6825 5090 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 4519 6750 4519 6750 5009 5400 5009 5400 4519 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 4601 6825 4601 6825 5090 5475 5090 5475 4601 4 1 0 50 0 2 12 0.0000 4 135 630 6000 4845 Utilities\001 -6 6 5400 5416 6825 5987 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 5416 6750 5416 6750 5906 5400 5906 5400 5416 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 5498 6825 5498 6825 5987 5475 5987 5475 5498 4 1 0 50 0 2 12 0.0000 4 135 855 6000 5742 Test Code\001 -6 2 2 0 1 0 38 55 0 20 0.000 0 0 -1 0 0 5 5175 4275 7200 4275 7200 6150 5175 6150 5175 4275 4 1 0 50 0 1 12 1.5708 4 135 885 7125 5253 Accessories\001 -6 6 5400 2700 6825 3675 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 2775 6825 2775 6825 3675 5475 3675 5475 2775 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 2700 6750 2700 6750 3600 5400 3600 5400 2700 4 1 0 50 0 2 12 0.0000 4 135 420 6075 3075 Code\001 4 1 0 50 0 2 12 0.0000 4 135 855 6075 3300 Generator\001 -6 6 5400 1875 6825 2400 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 1875 6750 1875 6750 2325 5400 2325 5400 1875 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 1950 6825 1950 6825 2400 5475 2400 5475 1950 4 1 0 50 0 2 12 0.0000 4 135 570 6075 2175 Parser\001 -6 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 5400 1050 6750 1050 6750 1500 5400 1500 5400 1050 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 5475 1125 6825 1125 6825 1575 5475 1575 5475 1125 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 1050 4575 1050 4575 1500 3225 1500 3225 1050 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 1125 4650 1125 4650 1575 3300 1575 3300 1125 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 1800 4575 1800 4575 2250 3225 2250 3225 1800 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 1875 4650 1875 4650 2325 3300 2325 3300 1875 2 2 0 1 0 7 51 0 20 0.000 0 0 -1 0 0 5 3225 2550 4575 2550 4575 3000 3225 3000 3225 2550 2 2 0 0 0 33 52 0 20 0.000 0 0 -1 0 0 5 3300 2625 4650 2625 4650 3075 3300 3075 3300 2625 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 1500 3900 1800 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 2250 3900 2550 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 3900 3000 3900 3900 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 4575 1950 5400 1350 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 5400 2925 4650 2175 2 2 0 1 0 34 55 0 20 0.000 0 0 -1 0 0 5 2850 750 4875 750 4875 3375 2850 3375 2850 750 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 6075 1500 6075 1800 2 3 0 1 0 35 55 0 20 0.000 0 0 -1 0 0 5 2850 3675 4875 3675 4875 6150 2850 6150 2850 3675 2 2 0 1 0 37 55 0 20 0.000 0 0 -1 0 0 5 5175 750 7200 750 7200 3975 5175 3975 5175 750 2 1 0 1 0 38 50 0 -1 0.000 0 0 -1 1 0 2 1 1 1.00 60.00 120.00 6075 2400 6075 2700 4 1 0 50 0 2 12 0.0000 4 135 855 6075 1350 Tokenizer\001 4 1 0 50 0 1 12 1.5708 4 180 1020 7125 2250 SQL Compiler\001 4 1 0 50 0 1 12 1.5708 4 135 345 3075 2025 Core\001 4 1 0 50 0 2 12 0.0000 4 135 1290 3900 2850 Virtual Machine\001 4 1 0 50 0 2 12 0.0000 4 165 1185 3900 1995 SQL Command\001 4 1 0 50 0 2 12 0.0000 4 135 855 3900 2183 Processor\001 4 1 0 50 0 2 14 0.0000 4 150 870 3900 1350 Interface\001 4 1 0 50 0 1 12 1.5708 4 135 645 3075 4875 Backend\001 |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
︙ | ︙ | |||
18 19 20 21 22 23 24 | sqlite3.h: $(SRC)/src/sqlite.h.in sed -e s/--VERS--/`cat ${SRC}/VERSION`/ \ -e s/--VERSION-NUMBER--/`cat ${SRC}/VERSION | \ sed 's/[^0-9]/ /g' | \ $(NAWK) '{printf "%d%03d%03d",$$1,$$2,$$3}'`/ \ $(SRC)/src/sqlite.h.in >sqlite3.h | < < < < < < | | | | | < | | | | < | < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < | < < < < < | 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 | sqlite3.h: $(SRC)/src/sqlite.h.in sed -e s/--VERS--/`cat ${SRC}/VERSION`/ \ -e s/--VERSION-NUMBER--/`cat ${SRC}/VERSION | \ sed 's/[^0-9]/ /g' | \ $(NAWK) '{printf "%d%03d%03d",$$1,$$2,$$3}'`/ \ $(SRC)/src/sqlite.h.in >sqlite3.h wrap.tcl: $(DOC)/wrap.tcl cp $(DOC)/wrap.tcl . lang.html: $(DOC)/lang.tcl tclsh $(DOC)/lang.tcl doc >lang.html opcode.html: $(DOC)/opcode.tcl $(SRC)/src/vdbe.c tclsh $(DOC)/opcode.tcl $(SRC)/src/vdbe.c >opcode.html capi3ref.html: $(DOC)/mkapidoc.tcl sqlite3.h tclsh $(DOC)/mkapidoc.tcl <sqlite3.h >capi3ref.html docdir: mkdir -p doc doc: docdir always rm -rf doc/images cp -r $(DOC)/images doc cp $(DOC)/rawpages/* doc tclsh $(DOC)/wrap.tcl $(DOC) $(SRC) doc $(DOC)/pages/*.in always: clean: rm -f doc sqlite3.h |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 | <title>SQLite Changes From Version 3.4.2 To 3.5.0</title> <tcl> proc CODE {text} { puts "<blockquote><pre>" puts $text puts "</pre></blockquote>" } proc SYNTAX {text} { puts "<blockquote><pre>" set t2 [string map {& & < < > >} $text] regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3 puts "<b>$t3</b>" puts "</pre></blockquote>" } proc IMAGE {name {caption {}}} { puts "<center><img src=\"$name\">" if {$caption!=""} { puts "<br>$caption" } puts "</center>" } proc PARAGRAPH {text} { # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2 #regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3 regsub -all {\[([^]\n]+)\]} $text {[resolve_link \1]} t3 puts "<p>[subst -novar -noback $t3]</p>\n" } proc resolve_link {args} { set a2 [split $args |] set id [string trim [lindex $a2 0]] if {[lindex $a2 1]==""} { set display [string trim [lindex $a2 0]] } else { set display [string trim [lrange $a2 1 end]] } regsub -all {[^a-zA-Z0-9_]} $id {} id return "<a href=\"capi3ref.html#$id\">$display</a>" } set level(0) 0 set level(1) 0 proc HEADING {n name {tag {}}} { if {$tag!=""} { puts "<a name=\"$tag\"></a>" } global level incr level($n) for {set i [expr {$n+1}]} {$i<10} {incr i} { set level($i) 0 } if {$n==0} { set num {} } elseif {$n==1} { set num $level(1).0 } else { set num $level(1) for {set i 2} {$i<=$n} {incr i} { append num .$level($i) } } incr n 1 puts "<h$n>$num $name</h$n>" } HEADING 0 {Moving From SQLite 3.4.2 to 3.5.0} PARAGRAPH { SQLite version 3.5.0 introduces a new OS interface layer that is incompatible with all prior versions of SQLite. In addition, a few existing interfaces have been generalized to work across all database connections within a process rather than just all connections within a thread. The purpose of this article is to describe the changes to 3.5.0 in detail so that users of prior versions of SQLite can judge what, if any, effort will be required to upgrade to newer versions. } HEADING 1 {Overview Of Changes} PARAGRAPH { A quick enumeration of the changes in SQLite version 3.5.0 is provide here. Subsequent sections will describe these changes in more detail. } PARAGRAPH { <ol> <li>The OS interface layer has been completely reworked: <ol type="a"> <li>The undocumented <b>sqlite3_os_switch()</b> interface has been removed.</li> <li>The <b>SQLITE_ENABLE_REDEF_IO</b> compile-time flag no longer functions. I/O procedures are now always redefinable.</li> <li>Three new objects are defined for specifying I/O procedures: [sqlite3_vfs], [sqlite3_file], and [sqlite3_io_methods].</li> <li>Three new interfaces are used to create alternative OS interfaces: [sqlite3_vfs_register()], [sqlite3_vfs_unregister()], and [sqlite3_vfs_find()].</li> <li>A new interface has been added to provided additional control over the creation of new database connections: [sqlite3_open_v2()]. The legacy interfaces of [sqlite3_open()] and [sqlite3_open16()] continue to be fully supported.</li> </ol></li> <li>The optional shared cache and memory management features that were introduced in version 3.3.0 can now be used across multiple threads within the same process. Formerly, these extensions only applied to database connections operating within a single thread. <ol type="a"> <li>The [sqlite3_enable_shared_cache()] interface now applies to all threads within a process, not to just the one thread in which it was run.</li> <li>The [sqlite3_soft_heap_limit()] interface now applies to all threads within a process, not to just the one thread in which it was run.</li> <li>The [sqlite3_release_memory()] interface will now attempt to reduce the memory usages across all database connections in all threads, not just connections in the thread where the interface is called.</li> <li>The [sqlite3_thread_cleanup()] interface has become a no-op.</li> </ol></li> <li>Restrictions on the use of the same database connection by multiple threads have been dropped. It is now safe for multiple threads to use the same database connection at the same time.</li> <li>There is now a compile-time option that allows an application to define alternative malloc()/free() implementations without having to modify any core SQLite code.</li> <li>There is now a compile-time option that allows an application to define alternative mutex implementations without having to modify any core SQLite code.</li> </ol> } PARAGRAPH { Of these changes, only 1a and 2a through 2c are incompatibilities in any formal sense. But users who have previously made custom modifications to the SQLite source (for example to add a custom OS layer for embedded hardware) might find that these changes have a larger impact. On the other hand, an important goal of these changes is to make it much easier to customize SQLite for use on different operating systems. } HEADING 1 {The OS Interface Layer} PARAGRAPH { If your system defines a custom OS interface for SQLite or if you were using the undocumented <b>sqlite3_os_switch()</b> interface, then you will need to make modifications in order to upgrade to SQLite version 3.5.0. This may seem painful at first glance. But as you look more closely, you will probably discover that your changes are made smaller and easier to understand and manage by the new SQLite interface. It is likely that your changes will now also work seamlessly with the SQLite amalgamation. You will no longer need to make any changes to the code SQLite source code. All of your changes can be effected by application code and you can link against a standard, unmodified version of the SQLite amalgamation. Furthermore, the OS interface layer, which was formerly undocumented, is now an officially support interface for SQLite. So you have some assurance that this will be a one-time change and that your new backend will continue to work in future versions of SQLite. } HEADING 2 {The Virtual File System Object} PARAGRAPH { The new OS interface for SQLite is built around an object named [sqlite3_vfs]. The "vfs" standard for "Virtual File System". The sqlite3_vfs object is basically a structure containing pointers to functions that implement the primitive disk I/O operations that SQLite needs to perform in order to read and write databases. In this article, we will often refer a sqlite3_vfs objects as a "VFS". } PARAGRAPH { SQLite is able to use multiple VFSes at the same time. Each individual database connection is associated with just one VFS. But if you have multiple database connections, each connection can be associated with a different VFS. } PARAGRAPH { There is always a default VFS. The legacy interfaces [sqlite3_open()] and [sqlite3_open16()] always use the default VFS. The new interface for creating database connections, [sqlite3_open_v2()], allows you to specify which VFS you want to use by name. } HEADING 3 {Registering New VFS Objects} PARAGRAPH { Standard builds of SQLite for unix or windows come with a single VFS named "unix" or "win32", as appropriate. This one VFS is also the default. So if you are using the legacy open functions, everything will continue to operate as it has before. The change is that an application now has the flexibility of adding new VFS modules to implement a customized OS layer. The [sqlite3_vfs_register()] API can be used to tell SQLite about one or more application-defined VFS modules: } CODE { int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt); } PARAGRAPH { Applications can call sqlite3_vfs_register at any time, though of course a VFS needs to be registered before it can be used. The first argument is a pointer to a customized VFS object that the application has prepared. The second argument is true to make the new VFS the default VFS so that it will be used by the legacy [sqlite3_open()] and [sqlite3_open16()] APIs. If the new VFS is not the default, then you will probably have to use the new [sqlite3_open_v2()] API to use it. Note, however, that if a new VFS is the only VFS known to SQLite (if SQLite was compiled without its usual default VFS or if the pre-compiled default VFS was removed using [sqlite3_vfs_unregister()]) then the new VFS automatic becomes the default VFS regardless of the makeDflt argument to [sqlite3_vfs_register()]. } PARAGRAPH { Standard builds include the default "unix" or "win32" VFSes. But if you use the -DOS_OTHER=1 compile-time option, then SQLite is built without a default VFS. In that case, the application must register at least one VFS prior to calling [sqlite3_open()]. This is the approach that embedded applications should use. Rather than modifying the SQLite source to to insert an alternative OS layer as was done in prior releases of SQLite, instead compile an unmodified SQLite source file (preferably the amalgamation) with the -DOS_OTHER=1 option, then invoke [sqlite3_vfs_register()] to define the interface to the underlying filesystem prior to creating any database connections. } HEADING 3 {Additional Control Over VFS Objects} PARAGRAPH { The [sqlite3_vfs_unregister()] API is used to remove an existing VFS from the system. } CODE { int sqlite3_vfs_unregister(sqlite3_vfs*); } PARAGRAPH { The [sqlite3_vfs_find()] API is used to locate a particular VFS by name. Its prototype is as follows: } CODE { sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName); } PARAGRAPH { The argument is the symbolic name for the desired VFS. If the argument is a NULL pointer, then the default VFS is returned. The function returns a pointer to the [sqlite3_vfs] object that implements the VFS. Or it returns a NULL pointer if no object could be found that matched the search criteria. } HEADING 3 {Modifications Of Existing VFSes} PARAGRAPH { Once a VFS has been registered, it should never be modified. If a change in behavior is required, a new VFS should be registered. The application could, perhaps, use [sqlite3_vfs_find()] to locate the old VFS, make a copy of the old VFS into a new [sqlite3_vfs] object, make the desired modifications to the new VFS, unregister the old VFS, the register the new VFS in its place. Existing database connections would continue to use the old VFS even after it is unregistered, but new database connections would use the new VFS. } HEADING 3 {The VFS Object} PARAGRAPH { A VFS object is an instance of the following structure: } CODE { typedef struct sqlite3_vfs sqlite3_vfs; struct sqlite3_vfs { int iVersion; /* Structure version number */ int szOsFile; /* Size of subclassed sqlite3_file */ int mxPathname; /* Maximum file pathname length */ sqlite3_vfs *pNext; /* Next registered VFS */ const char *zName; /* Name of this virtual file system */ void *pAppData; /* Pointer to application-specific data */ int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*, int flags, int *pOutFlags); int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir); int (*xAccess)(sqlite3_vfs*, const char *zName, int flags); int (*xGetTempName)(sqlite3_vfs*, char *zOut); int (*xFullPathname)(sqlite3_vfs*, const char *zName, char *zOut); void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename); void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg); void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol); void (*xDlClose)(sqlite3_vfs*, void*); int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut); int (*xSleep)(sqlite3_vfs*, int microseconds); int (*xCurrentTime)(sqlite3_vfs*, double*); /* New fields may be appended in figure versions. The iVersion ** value will increment whenever this happens. */ }; } PARAGRAPH { To create a new VFS, an application fills in an instance of this structure with appropriate values and then calls [sqlite3_vfs_register()]. } PARAGRAPH { The iVersion field of [sqlite3_vfs] should be 1 for SQLite version 3.5.0. This number may increase in future versions of SQLite if we have to modify the VFS object in some way. We hope that this never happens, but the provision is made in case it does. } PARAGRAPH { The szOsFile field is the size in bytes of the structure that defines an open file: the [sqlite3_file] object. This object will be described more fully below. The point here is that each VFS implementation can define its own [sqlite3_file] object containing whatever information the VFS implementation needs to store about an open file. SQLite needs to know how big this object is, however, in order to preallocate enough space to hold it. } PARAGRAPH { The mxPathname field is the maximum length of a file pathname that this VFS can use. SQLite sometimes has to preallocate buffers of this size, so it should be as small as reasonably possible. Some filesystems permit huge pathnames, but in practice pathnames rarely extend beyond 100 bytes or so. You do not have to put the longest pathname that the underlying filesystem can handle here. You only have to put the longest pathname that you want SQLite to be able to handle. A few hundred is a good value in most cases. } PARAGRAPH { The pNext field is used internally by SQLite. Specifically, SQLite uses this field to form a linked list of registered VFSes. } PARAGRAPH { The zName field is the symbolic name of the VFS. This is the name that the [sqlite3_vfs_find()] compares against when it is looking for a VFS. } PARAGRAPH { The pAppData pointer is unused by the SQLite core. The pointer is available to store auxiliary information that a VFS information might want to carry around. } PARAGRAPH { The remaining fields of the [sqlite3_vfs] object all store pointer to functions that implement primitive operations. We call these "methods". The first methods, xOpen, is used to open files on the underlying storage media. The result is an [sqlite3_file] object. There are additional methods, defined by the [sqlite3_file] object itself that are used to read and write and close the file. The additional methods are detailed below. The filename is in UTF-8. SQLite will guarantee that the zFilename string passed to xOpen() is a full pathname as generated by xFullPathname() and that the string will be valid and unchanged until xClose() is called. So the [sqlite3_file] can store a pointer to the filename if it needs to remember the filename for some reason. The flags argument to xOpen() is a copy of the flags argument to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16() is used, then flags is [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. If xOpen() opens a file read-only then it sets *pOutFlags to include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set. SQLite will also add one of the following flags to the xOpen() call, depending on the object being opened: <ul> <li> [SQLITE_OPEN_MAIN_DB] <li> [SQLITE_OPEN_MAIN_JOURNAL] <li> [SQLITE_OPEN_TEMP_DB] <li> [SQLITE_OPEN_TEMP_JOURNAL] <li> [SQLITE_OPEN_TRANSIENT_DB] <li> [SQLITE_OPEN_SUBJOURNAL] <li> [SQLITE_OPEN_MASTER_JOURNAL] </ul> The file I/O implementation can use the object type flags to changes the way it deals with files. For example, an application that does not care about crash recovery or rollback, might make the open of a journal file a no-op. Writes to this journal are also a no-op. Any attempt to read the journal returns [SQLITE_IOERR]. Or the implementation might recognize the a database file will be doing page-aligned sector reads and writes in a random order and set up its I/O subsystem accordingly. SQLite might also add one of the following flags to the xOpen method: <ul> <li> [SQLITE_OPEN_DELETEONCLOSE] <li> [SQLITE_OPEN_EXCLUSIVE] </ul> The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be deleted when it is closed. This will always be set for TEMP databases and journals and for subjournals. The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened for exclusive access. This flag is set for all files except for the main database file. The [sqlite3_file] structure passed as the third argument to xOpen is allocated by the caller. xOpen just fills it in. The caller allocates a minimum of szOsFile bytes for the [sqlite3_file] structure. } PARAGRAPH { The differences between an [SQLITE_OPEN_TEMP_DB] database and an [SQLITE_OPEN_TRANSIENT_DB] database is this: The [SQLITE_OPEN_TEMP_DB] is used for explicitly declared and named TEMP tables (using the CREATE TEMP TABLE syntax) or for named tables in a temporary database that is created by opening a database with a filename that is an empty string. An [SQLITE_OPEN_TRANSIENT_DB] holds an database table that SQLite creates automatically in order to evaluate a subquery or ORDER BY or GROUP BY clause. Both TEMP_DB and TRANSIENT_DB databases are private and are deleted automatically. TEMP_DB databases last for the duration of the database connection. TRANSIENT_DB databases last only for the duration of a single SQL statement. } PARAGRAPH { The xDelete method is used delete a file. The name of the file is given in the second parameter. The filename will be in UTF-8. The VFS must convert the filename into whatever character representation the underlying operating system expects. If the syncDir parameter is true, then the xDelete method should not return until the change to the directory contents for the directory containing the deleted file have been synced to disk in order to insure that the file does not "reappear" if a power failure occurs soon after. } PARAGRAPH { The xAccess method is used to check for access permissions on a file. The filename will be UTF-8 encoded. The flags argument will be [SQLITE_ACCESS_EXISTS] to check for the existence of the file, [SQLITE_ACCESS_READWRITE] to check to see if the file is both readable and writable, or [SQLITE_ACCESS_READ] to check to see if the file is at least readable. The "file" named by the second parameter might be a directory or folder name. } PARAGRAPH { The xGetTempName method computes the name of a temporary file that SQLite can use. The name should be written into the buffer given by the second parameter. SQLite will size that buffer to hold at least mxPathname bytes. The generated filename should be in UTF-8. To avoid security problems, the generated temporary filename should contain enough randomness to prevent an attacker from guessing the temporary filename in advance. } PARAGRAPH { The xFullPathname method is used to convert a relative pathname into a full pathname. The resulting full pathname is written into the buffer provided by the third parameter. SQLite will size the output buffer to at least mxPathname bytes. Both the input and output names should be in UTF-8. } PARAGRAPH { The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for accessing shared libraries at run-time. These methods may be omitted (and their pointers set to zero) if the library is compiled with SQLITE_OMIT_LOAD_EXTENSION or if the [sqlite3_enable_load_extension()] interface is never used to enable dynamic extension loading. The xDlOpen method opens a shared library or DLL and returns a pointer to a handle. NULL is returned if the open fails. If the open fails, the xDlError method can be used to obtain a text error message. The message is written into the zErrMsg buffer of the third parameter which is at least nByte bytes in length. The xDlSym returns a pointer to a symbol in the shared library. The name of the symbol is given by the second parameter. UTF-8 encoding is assumed. If the symbol is not found a NULL pointer is returned. The xDlClose routine closes the shared library. } PARAGRAPH { The xRandomness method is used exactly once to initialize the pseudo-random number generator (PRNG) inside of SQLite. Only the xRandomness method on the default VFS is used. The xRandomness methods on other VFSes are never accessed by SQLite. The xRandomness routine requests that nByte bytes of randomness be written into zOut. The routine returns the actual number of bytes of randomness obtained. The quality of the randomness so obtained will determine the quality of the randomness generated by built-in SQLite functions such as random() and randomblob(). SQLite also uses its PRNG to generate temporary file names.. On some platforms (ex: windows) SQLite assumes that temporary file names are unique without actually testing for collisions, so it is important to have good-quality randomness even if the random() and randomblob() functions are never used. } PARAGRAPH { The xSleep method is used to suspend the calling thread for at least the number of microseconds given. This method is used to implement the [sqlite3_sleep()] and [sqlite3_busy_timeout()] APIs. In the case of [sqlite3_sleep()] the xSleep method of the default VFS is always used. If the underlying system does not have a microsecond resolution sleep capability, then the sleep time should be rounded up. xSleep returns this rounded-up value. } PARAGRAPH { The xCurrentTime method finds the current time and date and writes the result as double-precision floating point value into pointer provided by the second parameter. The time and date is in coordinated universal time (UTC) and is a fractional julian day number. } HEADING 3 {The Open File Object} PARAGRAPH { The result of opening a file is an instance of an [sqlite3_file] object. The [sqlite3_file] object is an abstract base class defined as follows: } CODE { typedef struct sqlite3_file sqlite3_file; struct sqlite3_file { const struct sqlite3_io_methods *pMethods; }; } PARAGRAPH { Each VFS implementation will subclass the [sqlite3_file] by adding additional fields at the end to hold whatever information the VFS needs to know about an open file. It does not matter what information is stored as long as the total size of the structure does not exceed the szOsFile value recorded in the [sqlite3_vfs] object. } PARAGRAPH { The [sqlite3_io_methods] object is a structure that contains pointers to methods for reading, writing, and otherwise dealing with files. This object is defined as follows: } CODE { typedef struct sqlite3_io_methods sqlite3_io_methods; struct sqlite3_io_methods { int iVersion; int (*xClose)(sqlite3_file*); int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); int (*xSync)(sqlite3_file*, int flags); int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); int (*xLock)(sqlite3_file*, int); int (*xUnlock)(sqlite3_file*, int); int (*xCheckReservedLock)(sqlite3_file*); int (*xFileControl)(sqlite3_file*, int op, void *pArg); int (*xSectorSize)(sqlite3_file*); int (*xDeviceCharacteristics)(sqlite3_file*); /* Additional methods may be added in future releases */ }; } PARAGRAPH { The iVersion field of [sqlite3_io_methods] is provided as insurance against future enhancements. The iVersion value should always be 1 for SQLite version 3.5. } PARAGRAPH { The xClose method closes the file. The space for the [sqlite3_file] structure is deallocated by the caller. But if the [sqlite3_file] contains pointers to other allocated memory or resources, those allocations should be released by the xClose method. } PARAGRAPH { The xRead method reads iAmt bytes from the file beginning at a byte offset to iOfst. The data read is stored in the pointer of the second parameter. xRead returns the [SQLITE_OK] on success, [SQLITE_IOERR_SHORT_READ] if it was not able to read the full number of bytes because it reached end-of-file, or [SQLITE_IOERR_READ] for any other error. } PARAGRAPH { The xWrite method writes iAmt bytes of data from the second parameter into the file beginning at an offset of iOfst bytes. If the size of the file is less than iOfst bytes prior to the write, then xWrite should ensure that the file is extended with zeros up to iOfst bytes prior to beginning its write. xWrite continues to extends the file as necessary so that the size of the file is at least iAmt+iOfst bytes at the conclusion of the xWrite call. The xWrite method returns [SQLITE_OK] on success. If the write cannot complete because the underlying storage medium is full, then [SQLITE_FULL] is returned. [SQLITE_IOERR_WRITE] should be returned for any other error. } PARAGRAPH { The xTruncate method truncates a file to be nByte bytes in length. If the file is already nByte bytes or less in length then this method is a no-op. The xTruncate method returns [SQLITE_OK] on success and [SQLITE_IOERR_TRUNCATE] if anything goes wrong. } PARAGRAPH { The xSync method is used to force previously written data out of operating system cache and into non-volatile memory. The second parameter is usually [SQLITE_SYNC_NORMAL]. If the second parameter is [SQLITE_SYNC_FULL] then the xSync method should make sure that data has also been flushed through the disk controllers cache. The [SQLITE_SYNC_FULL] parameter is the equivalent of the F_FULLSYNC ioctl() on Mac OS X. The xSync method returns [SQLITE_OK] on success and [SQLITE_IOERR_FSYNC] if anything goes wrong. } PARAGRAPH { The xFileSize() method determines the current size of the file in bytes and writes that value into *pSize. It returns [SQLITE_OK] on success and [SQLITE_IOERR_FSTAT] if something goes wrong. } PARAGRAPH { The xLock and xUnlock methods are used to set and clear file locks. SQLite supports five levels of file locks, in order: <ul> <li> [SQLITE_LOCK_NONE] <li> [SQLITE_LOCK_SHARED] <li> [SQLITE_LOCK_RESERVED] <li> [SQLITE_LOCK_PENDING] <li> [SQLITE_LOCK_EXCLUSIVE] </ul> The underlying implementation can support some subset of these locking levels as long as it meets the other requirements of this paragraph. The locking level is specified as the second argument to both xLock and xUnlock. The xLock method increases the locking level to the specified locking level or higher. The xUnlock method decreases the locking level to no lower than the level specified. [SQLITE_LOCK_NONE] means that the file is unlocked. [SQLITE_LOCK_SHARED] gives permission to read the file. Multiple database connections can hold [SQLITE_LOCK_SHARED] at the same time. [SQLITE_LOCK_RESERVED] is like [SQLITE_LOCK_SHARED] in that its is permission to read the file. But only a single connection can hold a reserved lock at any point in time. The [SQLITE_LOCK_PENDING] is also permission to read the file. Other connections can continue to read the file as well, but no other connection is allowed to escalate a lock from none to shared. [SQLITE_LOCK_EXCLUSIVE] is permission to write on the file. Only a single connection can hold an exclusive lock and no other connection can hold any lock (other than "none") while one connection is hold an exclusive lock. The xLock returns [SQLITE_OK] on success, [SQLITE_BUSY] if it is unable to obtain the lock, or [SQLITE_IOERR_RDLOCK] if something else goes wrong. The xUnlock method returns [SQLITE_OK] on success and [SQLITE_IOERR_UNLOCK] for problems. } PARAGRAPH { The xCheckReservedLock method checks to see if another connection or another process is currently holding a reserved, pending, or exclusive lock on the file. It returns true or false. } PARAGRAPH { The xFileControl() method is a generic interface that allows custom VFS implementations to directly control an open file using the (new and experimental) [sqlite3_file_control()] interface. The second "op" argument is an integer opcode. The third argument is a generic pointer which is intended to be a pointer to a structure that may contain arguments or space in which to write return values. Potential uses for xFileControl() might be functions to enable blocking locks with timeouts, to change the locking strategy (for example to use dot-file locks), to inquire about the status of a lock, or to break stale locks. The SQLite core reserves opcodes less than 100 for its own use. A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available. Applications that define a custom xFileControl method should use opcodes greater than 100 to avoid conflicts. } PARAGRAPH { The xSectorSize returns the "sector size" of the underlying non-volatile media. A "sector" is defined as the smallest unit of storage that can be written without disturbing adjacent storage. On a disk drive the "sector size" has until recently been 512 bytes, though there is a push to increase this value to 4KiB. SQLite needs to know the sector size so that it can write a full sector at a time, and thus avoid corrupting adjacent storage space if a power lose occurs in the middle of a write. } PARAGRAPH { The xDeviceCharacteristics method returns an integer bit vector that defines any special properties that the underlying storage medium might have that SQLite can use to increase performance. The allowed return is the bit-wise OR of the following values: <ul> <li> [SQLITE_IOCAP_ATOMIC] <li> [SQLITE_IOCAP_ATOMIC512] <li> [SQLITE_IOCAP_ATOMIC1K] <li> [SQLITE_IOCAP_ATOMIC2K] <li> [SQLITE_IOCAP_ATOMIC4K] <li> [SQLITE_IOCAP_ATOMIC8K] <li> [SQLITE_IOCAP_ATOMIC16K] <li> [SQLITE_IOCAP_ATOMIC32K] <li> [SQLITE_IOCAP_ATOMIC64K] <li> [SQLITE_IOCAP_SAFE_APPEND] <li> [SQLITE_IOCAP_SEQUENTIAL] </ul> The [SQLITE_IOCAP_ATOMIC] bit means that all writes to this device are atomic in the sense that either the entire write occurs or none of it occurs. The other [SQLITE_IOCAP_ATOMIC | SQLITE_IOCAP_ATOMIC<i>nnn</i>] values indicate that writes of aligned blocks of the indicated size are atomic. [SQLITE_IOCAP_SAFE_APPEND] means that when extending a file with new data, the new data is written first and then the file size is updated. So if a power failure occurs, there is no chance that the file might have been extended with randomness. The [SQLITE_IOCAP_SEQUENTIAL] bit means that all writes occur in the order that they are issued and are not reordered by the underlying file system. } HEADING 3 {Checklist For Constructing A New VFS} PARAGRAPH { The preceding paragraphs contain a lot of information. To ease the task of constructing a new VFS for SQLite we offer the following implementation checklist: } PARAGRAPH { <ol> <li> Define an appropriate subclass of the [sqlite3_file] object. <li> Implement the methods required by the [sqlite3_io_methods] object. <li> Create a static and constant [sqlite3_io_methods] object containing pointers to the methods from the previous step. <li> Implement the xOpen method that opens a file and populates an [sqlite3_file] object, including setting pMethods to point to the [sqlite3_io_methods] object from the previous step. <li> Implement the other methods required by [sqlite3_vfs]. <li> Define a static (but not constant) [sqlite3_vfs] structure that contains pointers to the xOpen method and the other methods and which contains the appropriate values for iVersion, szOsFile, mxPathname, zName, and pAppData. <li> Implement a procedure that calls [sqlite3_vfs_register()] and passes it a pointer to the [sqlite3_vfs] structure from the previous step. This procedure is probably the only exported symbol in the source file that implements your VFS. </ol> } PARAGRAPH { Within your application, call the procedure implemented in the last step above as part of your initialization process before any database connections are opened. } HEADING 1 {The Memory Allocation Subsystem} PARAGRAPH { Beginning with version 3.5, SQLite obtains all of the heap memory it needs using the routines [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]. These routines have existed in prior versions of SQLite, but SQLite has previously bypassed these routines and used its own memory allocator. This all changes in version 3.5.0. } PARAGRAPH { The SQLite source tree actually contains multiple versions of the memory allocator. The default high-speed version found in the "mem1.c" source file is used for most builds. But if the SQLITE_MEMDEBUG flag is enabled, a separate memory allocator the "mem2.c" source file is used instead. The mem2.c allocator implements lots of hooks to do error checking and to simulate memory allocation failures for testing purposes. Both of these allocators use the malloc()/free() implementation in the standard C library. } PARAGRAPH { Applications are not required to use either of these standard memory allocators. If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION then no implementation for the [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()] functions is provided. Instead, the application that links against SQLite must provide its own implementation of these functions. The application provided memory allocator is not required to use the malloc()/free() implementation in the standard C library. An embedded application might provide an alternative memory allocator that uses memory for a fixed memory pool set aside for the exclusive use of SQLite, for example. } PARAGRAPH { Applications that implement their own memory allocator must provide implementation for the usual three allocation functions [sqlite3_malloc()], [sqlite3_realloc()], and [sqlite3_free()]. And they must also implement a fourth function: } CODE { int sqlite3_memory_alarm( void(*xCallback)(void *pArg, sqlite3_int64 used, int N), void *pArg, sqlite3_int64 iThreshold ); } PARAGRAPH { The [sqlite3_memory_alarm] routine is used to register a callback on memory allocation events. This routine registers or clears a callbacks that fires when the amount of memory allocated exceeds iThreshold. Only a single callback can be registered at a time. Each call to [sqlite3_memory_alarm()] overwrites the previous callback. The callback is disabled by setting xCallback to a NULL pointer. } PARAGRAPH { The parameters to the callback are the pArg value, the amount of memory currently in use, and the size of the allocation that provoked the callback. The callback will presumably invoke [sqlite3_free()] to free up memory space. The callback may invoke [sqlite3_malloc()] or [sqlite3_realloc()] but if it does, no additional callbacks will be invoked by the recursive calls. } PARAGRAPH { The [sqlite3_soft_heap_limit()] interface works by registering a memory alarm at the soft heap limit and invoking [sqlite3_release_memory()] in the alarm callback. Application programs should not attempt to use the [sqlite3_memory_alarm()] interface because doing so will interfere with the [sqlite3_soft_heap_limit()] module. This interface is exposed only so that applications can provide their own alternative implementation when the SQLite core is compiled with SQLITE_OMIT_MEMORY_ALLOCATION. } PARAGRAPH { The built-in memory allocators in SQLite also provide the following additional interfaces: } CODE { sqlite3_int64 sqlite3_memory_used(void); sqlite3_int64 sqlite3_memory_highwater(int resetFlag); } PARAGRAPH { These interfaces can be used by an application to monitor how much memory SQLite is using. The [sqlite3_memory_used()] routine returns the number of bytes of memory currently in use and the [sqlite3_memory_highwater()] returns the maximum instantaneous memory usage. Neither routine includes the overhead associated with the memory allocator. These routines are provided for use by the application. SQLite never invokes them itself. So if the application is providing its own memory allocation subsystem, it can omit these interfaces if desired. } HEADING 1 {The Mutex Subsystem} PARAGRAPH { SQLite has always been threadsafe in the sense that it is safe to use different SQLite database connections in different threads at the same time. The constraint was that the same database connection could not be used in two separate threads at once. SQLite version 3.5.0 relaxes this constraint. } PARAGRAPH { In order to allow multiple threads to use the same database connection at the same time, SQLite must make extensive use of mutexes. And for this reason a new mutex subsystem as been added. The mutex subsystem as the following interface: } CODE { sqlite3_mutex *sqlite3_mutex_alloc(int); void sqlite3_mutex_free(sqlite3_mutex*); void sqlite3_mutex_enter(sqlite3_mutex*); int sqlite3_mutex_try(sqlite3_mutex*); void sqlite3_mutex_leave(sqlite3_mutex*); } PARAGRAPH { Though these routines exist for the use of the SQLite core, application code is free to use these routines as well, if desired. A mutex is an [sqlite3_mutex] object. The [sqlite3_mutex_alloc()] routine allocates a new mutex object and returns a pointer to it. The argument to [sqlite3_mutex_alloc()] should be [SQLITE_MUTEX_FAST] or [SQLITE_MUTEX_RECURSIVE] for non-recursive and recursive mutexes, respectively. If the underlying system does not provide non-recursive mutexes, then a recursive mutex can be substituted in that case. The argument to [sqlite3_mutex_alloc()] can also be a constant designating one of several static mutexes: <ul> <li> [SQLITE_MUTEX_STATIC_MASTER] <li> [SQLITE_MUTEX_STATIC_MEM] <li> [SQLITE_MUTEX_STATIC_MEM2] <li> [SQLITE_MUTEX_STATIC_PRNG] <li> [SQLITE_MUTEX_STATIC_LRU] </ul> These static mutexes are reserved for use internally by SQLite and should not be used by the application. The static mutexes are all non-recursive. } PARAGRAPH { The [sqlite3_mutex_free()] routine should be used to deallocate a non-static mutex. If a static mutex is passed to this routine then the behavior is undefined. } PARAGRAPH { The [sqlite3_mutex_enter()] attempts to enter the mutex and blocks if another threads is already there. [sqlite3_mutex_try()] attempts to enter and returns [SQLITE_OK] on success or [SQLITE_BUSY] if another thread is already there. [sqlite3_mutex_leave()] exits a mutex. The mutex is held until the number of exits matches the number of entrances. If [sqlite3_mutex_leave()] is called on a mutex that the thread is not currently holding, then the behavior is undefined. If any routine is called for a deallocated mutex, then the behavior is undefined. } PARAGRAPH { The SQLite source code provides multiple implementations of these APIs, suitable for varying environments. If SQLite is compiled with the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that is fast but does no real mutual exclusion is provided. That implementation is suitable for use in single-threaded applications or applications that only use SQLite in a single thread. Other real mutex implementations are provided based on the underlying operating system. } PARAGRAPH { Embedded applications may wish to provide their own mutex implementation. If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag then the SQLite core provides no mutex subsystem and a mutex subsystem that matches the interface described above must be provided by the application that links against SQLite. } HEADING 1 {Other Interface Changes} PARAGRAPH { Version 3.5.0 of SQLite changes the behavior of a few APIs in ways that are technically incompatible. However, these APIs are seldom used and even when they are used it is difficult to imagine a scenario where the change might break something. The changes actually makes these interface much more useful and powerful. } PARAGRAPH { Prior to version 3.5.0, the [sqlite3_enable_shared_cache()] API would enable and disable the shared cache feature for all connections within a single thread - the same thread from which the sqlite3_enable_shared_cache() routine was called. Database connections that used the shared cache were restricted to running in the same thread in which they were opened. Beginning with version 3.5.0, the sqlite3_enable_shared_cache() applies to all database connections in all threads within the process. Now database connections running in separate threads can share a cache. And database connections that use shared cache can migrate from one thread to another. } PARAGRAPH { Prior to version 3.5.0 the [sqlite3_soft_heap_limit()] set an upper bound on heap memory usage for all database connections within a single thread. Each thread could have its own heap limit. Beginning in version 3.5.0, there is a single heap limit for the entire process. This seems more restrictive (one limit as opposed to many) but in practice it is what most users want. } PARAGRAPH { Prior to version 3.5.0 the [sqlite3_release_memory()] function would try to reclaim memory from all database connections in the same thread as the sqlite3_release_memory() call. Beginning with version 3.5.0, the sqlite3_release_memory() function will attempt to reclaim memory from all database connections in all threads. } HEADING 1 {Summary} PARAGRAPH { The transition from SQLite version 3.4.2 to 3.5.0 is a major change. Every source code file in the SQLite core had to be modified, some extensively. And the change introduced some minor incompatibilities in the C interface. But we feel that the benefits of the transition from 3.4.2 to 3.5.0 far outweigh the pain of porting. The new VFS layer is now well-defined and stable and should simplify future customizations. The VFS layer, and the separable memory allocator and mutex subsystems allow a standard SQLite source code amalgamation to be used in an embedded project without change, greatly simplifying configuration management. And the resulting system is much more tolerant of highly threaded designs. } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 | <h2>About SQLite</h2> <p> SQLite is a small C library that implements a <a href="selfcontained.html">self-contained</a>, <a href="serverless.html">serverless</a>, <a href="zeroconf.html">zero-configuration</a>, <a href="transactional.html">transactional</a> SQL database engine. </p> <h3>Features:</h3> <p><ul> <li><a href="transactional.html">Transactions</a> are atomic, consistent, isolated, and durable (ACID) even after system crashes and power failures. <li><a href="zeroconf.html">Zero-configuration</a> - no setup or administration needed.</li> <li>Implements most of SQL92. (<a href="omitted.html">Features not supported</a>)</li> <li>A complete database is stored in a single disk file.</li> <li>Database files can be freely shared between machines with different byte orders.</li> <li>Supports terabyte-sized databases and gigabyte-sized strings and blobs. (See <a href="limits.html">limits.html</a>.) <li>Small code footprint: <a href="http://www.sqlite.org/cvstrac/wiki?p=SizeOfSqlite"> less than 250KiB</a> fully configured or less than 150KiB with optional features omitted.</li> <li><a href="speed.html">Faster</a> than popular client/server database engines for most common operations.</li> <li>Simple, easy to use <a href="capi3.html">API</a>.</li> <li><a href="tclsqlite.html">TCL bindings</a> included. Bindings for many other languages <a href="http://www.sqlite.org/cvstrac/wiki?p=SqliteWrappers"> available separately.</a></li> <li>Well-commented source code with over 98% test coverage.</li> <li>Available as a <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation"> single ANSI-C source-code file</a> that you can easily drop into another project. <li><a href="selfcontained.html">Self-contained</a>: no external dependencies.</li> <li>Cross-platform: Linux (unix), MacOSX, OS/2, Win32 and WinCE are supported out of the box. Easy to port to other systems. <li>Sources are in the <a href="copyright.html">public domain</a>. Use for any purpose.</li> <li>Comes with a standalone command-line interface (CLI) client that can be used to administer SQLite databases.</li> </ul> </p> <h3>Suggested Uses:</h3> <p><ul> <li><p><b>Application File Format.</b> Rather than using fopen() to write XML or some proprietary format into disk files used by your application, use an SQLite database instead. You'll avoid having to write and troubleshoot a parser, your data will be more easily accessible and cross-platform, your updates will transactional.</p><li> <li><p><b>Database For Gadgets.</b> SQLite is popular choice for the database engine in cellphones, PDAs, MP3 players, set-top boxes, and other electronic gadgets. SQLite has a small code footprint, makes efficient use of memory, disk space, and disk bandwidth, is highly reliable, and requires no maintenance from a Database Adminstrator.</p></li> <li><p><b>Website Database.</b> Because it requires no configuration and stores information in order disk files, SQLite is a popular choice as the database to back small to medium-sized websites.</p></li> <li><p><b>Stand-in For An Enterprise RDBMS.</b> SQLite is often used as a surrogate for an enterprise RDBMS for demonstration purposes or for testing. SQLite is fast and requires no setup, which takes a lot of the hassle out of testing and which makes demos perky and easy to launch.</p></li> </ul> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>Architecture of SQLite</title> <h2>The Architecture Of SQLite</h2> <h3>Introduction</h3> <table align="right" border="1" cellpadding="15" cellspacing="1"> <tr><th>Block Diagram Of SQLite</th></tr> <tr><td><img src="arch2.gif"></td></tr> </table> <p>This document describes the architecture of the SQLite library. The information here is useful to those who want to understand or modify the inner workings of SQLite. </p> <p> A block diagram showing the main components of SQLite and how they interrelate is shown at the right. The text that follows will provide a quick overview of each of these components. </p> <p> This document describes SQLite version 3.0. Version 2.8 and earlier are similar but the details differ. </p> <h3>Interface</h3> <p>Much of the public interface to the SQLite library is implemented by functions found in the <b>main.c</b>, <b>legacy.c</b>, and <b>vdbeapi.c</b> source files though some routines are scattered about in other files where they can have access to data structures with file scope. The <b>sqlite3_get_table()</b> routine is implemented in <b>table.c</b>. <b>sqlite3_mprintf()</b> is found in <b>printf.c</b>. <b>sqlite3_complete()</b> is in <b>tokenize.c</b>. The Tcl interface is implemented by <b>tclsqlite.c</b>. More information on the C interface to SQLite is <a href="capi3ref.html">available separately</a>.<p> <p>To avoid name collisions with other software, all external symbols in the SQLite library begin with the prefix <b>sqlite3</b>. Those symbols that are intended for external use (in other words, those symbols which form the API for SQLite) begin with <b>sqlite3_</b>.</p> <h3>Tokenizer</h3> <p>When a string containing SQL statements is to be executed, the interface passes that string to the tokenizer. The job of the tokenizer is to break the original string up into tokens and pass those tokens one by one to the parser. The tokenizer is hand-coded in C in the file <b>tokenize.c</b>. <p>Note that in this design, the tokenizer calls the parser. People who are familiar with YACC and BISON may be used to doing things the other way around -- having the parser call the tokenizer. The author of SQLite has done it both ways and finds things generally work out nicer for the tokenizer to call the parser. YACC has it backwards.</p> <h3>Parser</h3> <p>The parser is the piece that assigns meaning to tokens based on their context. The parser for SQLite is generated using the <a href="http://www.hwaci.com/sw/lemon/">Lemon</a> LALR(1) parser generator. Lemon does the same job as YACC/BISON, but it uses a different input syntax which is less error-prone. Lemon also generates a parser which is reentrant and thread-safe. And lemon defines the concept of a non-terminal destructor so that it does not leak memory when syntax errors are encountered. The source file that drives Lemon is found in <b>parse.y</b>.</p> <p>Because lemon is a program not normally found on development machines, the complete source code to lemon (just one C file) is included in the SQLite distribution in the "tool" subdirectory. Documentation on lemon is found in the "doc" subdirectory of the distribution. </p> <h3>Code Generator</h3> <p>After the parser assembles tokens into complete SQL statements, it calls the code generator to produce virtual machine code that will do the work that the SQL statements request. There are many files in the code generator: <b>attach.c</b>, <b>auth.c</b>, <b>build.c</b>, <b>delete.c</b>, <b>expr.c</b>, <b>insert.c</b>, <b>pragma.c</b>, <b>select.c</b>, <b>trigger.c</b>, <b>update.c</b>, <b>vacuum.c</b> and <b>where.c</b>. In these files is where most of the serious magic happens. <b>expr.c</b> handles code generation for expressions. <b>where.c</b> handles code generation for WHERE clauses on SELECT, UPDATE and DELETE statements. The files <b>attach.c</b>, <b>delete.c</b>, <b>insert.c</b>, <b>select.c</b>, <b>trigger.c</b> <b>update.c</b>, and <b>vacuum.c</b> handle the code generation for SQL statements with the same names. (Each of these files calls routines in <b>expr.c</b> and <b>where.c</b> as necessary.) All other SQL statements are coded out of <b>build.c</b>. The <b>auth.c</b> file implements the functionality of <b>sqlite3_set_authorizer()</b>.</p> <h3>Virtual Machine</h3> <p>The program generated by the code generator is executed by the virtual machine. Additional information about the virtual machine is <a href="opcode.html">available separately</a>. To summarize, the virtual machine implements an abstract computing engine specifically designed to manipulate database files. The machine has a stack which is used for intermediate storage. Each instruction contains an opcode and up to three additional operands.</p> <p>The virtual machine itself is entirely contained in a single source file <b>vdbe.c</b>. The virtual machine also has its own header files: <b>vdbe.h</b> that defines an interface between the virtual machine and the rest of the SQLite library and <b>vdbeInt.h</b> which defines structure private the virtual machine. The <b>vdbeaux.c</b> file contains utilities used by the virtual machine and interface modules used by the rest of the library to construct VM programs. The <b>vdbeapi.c</b> file contains external interfaces to the virtual machine such as the <b>sqlite3_bind_...</b> family of functions. Individual values (strings, integer, floating point numbers, and BLOBs) are stored in an internal object named "Mem" which is implemented by <b>vdbemem.c</b>.</p> <p> SQLite implements SQL functions using callbacks to C-language routines. Even the built-in SQL functions are implemented this way. Most of the built-in SQL functions (ex: <b>coalesce()</b>, <b>count()</b>, <b>substr()</b>, and so forth) can be found in <b>func.c</b>. Date and time conversion functions are found in <b>date.c</b>. </p> <h3>B-Tree</h3> <p>An SQLite database is maintained on disk using a B-tree implementation found in the <b>btree.c</b> source file. A separate B-tree is used for each table and index in the database. All B-trees are stored in the same disk file. Details of the file format are recorded in a large comment at the beginning of <b>btree.c</b>.</p> <p>The interface to the B-tree subsystem is defined by the header file <b>btree.h</b>. </p> <h3>Page Cache</h3> <p>The B-tree module requests information from the disk in fixed-size chunks. The default chunk size is 1024 bytes but can vary between 512 and 65536 bytes. The page cache is responsible for reading, writing, and caching these chunks. The page cache also provides the rollback and atomic commit abstraction and takes care of locking of the database file. The B-tree driver requests particular pages from the page cache and notifies the page cache when it wants to modify pages or commit or rollback changes and the page cache handles all the messy details of making sure the requests are handled quickly, safely, and efficiently.</p> <p>The code to implement the page cache is contained in the single C source file <b>pager.c</b>. The interface to the page cache subsystem is defined by the header file <b>pager.h</b>. </p> <h3>OS Interface</h3> <p> In order to provide portability between POSIX and Win32 operating systems, SQLite uses an abstraction layer to interface with the operating system. The interface to the OS abstraction layer is defined in <b>os.h</b>. Each supported operating system has its own implementation: <b>os_unix.c</b> for Unix, <b>os_win.c</b> for windows, and so forth. Each of these operating-specific implements typically has its own header file: <b>os_unix.h</b>, <b>os_win.h</b>, etc. </p> <h3>Utilities</h3> <p> Memory allocation and caseless string comparison routines are located in <b>util.c</b>. Symbol tables used by the parser are maintained by hash tables found in <b>hash.c</b>. The <b>utf.c</b> source file contains Unicode conversion subroutines. SQLite has its own private implementation of <b>printf()</b> (with some extensions) in <b>printf.c</b> and its own random number generator in <b>random.c</b>. </p> <h3>Test Code</h3> <p> If you count regression test scripts, more than half the total code base of SQLite is devoted to testing. There are many <b>assert()</b> statements in the main code files. In additional, the source files <b>test1.c</b> through <b>test5.c</b> together with <b>md5.c</b> implement extensions used for testing purposes only. The <b>os_test.c</b> backend interface is used to simulate power failures to verify the crash-recovery mechanism in the pager. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>SQLite Security Audit Procedure</title> <p> A security audit for SQLite consists of two components. First, there is a check for common errors that often lead to security problems. Second, an attempt is made to construct a proof that SQLite has certain desirable security properties. </p> <h2>Part I: Things to check</h2> <p> Scan all source code and check for the following common errors: </p> <ol> <li><p> Verify that the destination buffer is large enough to hold its result in every call to the following routines: <ul> <li> <b>strcpy()</b> </li> <li> <b>strncpy()</b> </li> <li> <b>strcat()</b> </li> <li> <b>memcpy()</b> </li> <li> <b>memset()</b> </li> <li> <b>memmove()</b> </li> <li> <b>bcopy()</b> </li> <li> <b>sprintf()</b> </li> <li> <b>scanf()</b> </li> </ul> </p></li> <li><p> Verify that pointers returned by subroutines are not NULL before using the pointers. In particular, make sure the return values for the following routines are checked before they are used: <ul> <li> <b>malloc()</b> </li> <li> <b>realloc()</b> </li> <li> <b>sqliteMalloc()</b> </li> <li> <b>sqliteRealloc()</b> </li> <li> <b>sqliteStrDup()</b> </li> <li> <b>sqliteStrNDup()</b> </li> <li> <b>sqliteExpr()</b> </li> <li> <b>sqliteExprFunction()</b> </li> <li> <b>sqliteExprListAppend()</b> </li> <li> <b>sqliteResultSetOfSelect()</b> </li> <li> <b>sqliteIdListAppend()</b> </li> <li> <b>sqliteSrcListAppend()</b> </li> <li> <b>sqliteSelectNew()</b> </li> <li> <b>sqliteTableNameToTable()</b> </li> <li> <b>sqliteTableTokenToSrcList()</b> </li> <li> <b>sqliteWhereBegin()</b> </li> <li> <b>sqliteFindTable()</b> </li> <li> <b>sqliteFindIndex()</b> </li> <li> <b>sqliteTableNameFromToken()</b> </li> <li> <b>sqliteGetVdbe()</b> </li> <li> <b>sqlite_mprintf()</b> </li> <li> <b>sqliteExprDup()</b> </li> <li> <b>sqliteExprListDup()</b> </li> <li> <b>sqliteSrcListDup()</b> </li> <li> <b>sqliteIdListDup()</b> </li> <li> <b>sqliteSelectDup()</b> </li> <li> <b>sqliteFindFunction()</b> </li> <li> <b>sqliteTriggerSelectStep()</b> </li> <li> <b>sqliteTriggerInsertStep()</b> </li> <li> <b>sqliteTriggerUpdateStep()</b> </li> <li> <b>sqliteTriggerDeleteStep()</b> </li> </ul> </p></li> <li><p> On all functions and procedures, verify that pointer parameters are not NULL before dereferencing those parameters. </p></li> <li><p> Check to make sure that temporary files are opened safely: that the process will not overwrite an existing file when opening the temp file and that another process is unable to substitute a file for the temp file being opened. </p></li> </ol> <h2>Part II: Things to prove</h2> <p> Prove that SQLite exhibits the characteristics outlined below: </p> <ol> <li><p> The following are preconditions:</p> <p><ul> <li><b>Z</b> is an arbitrary-length NUL-terminated string.</li> <li>An existing SQLite database has been opened. The return value from the call to <b>sqlite_open()</b> is stored in the variable <b>db</b>.</li> <li>The database contains at least one table of the form: <blockquote><pre> CREATE TABLE t1(a CLOB); </pre></blockquote></li> <li>There are no user-defined functions other than the standard build-in functions.</li> </ul></p> <p>The following statement of C code is executed:</p> <blockquote><pre> sqlite_exec_printf( db, "INSERT INTO t1(a) VALUES('%q');", 0, 0, 0, Z ); </pre></blockquote> <p>Prove the following are true for all possible values of string <b>Z</b>:</p> <ol type="a"> <li><p> The call to <b>sqlite_exec_printf()</b> will return in a length of time that is a polynomial in <b>strlen(Z)</b>. It might return an error code but it will not crash. </p></li> <li><p> At most one new row will be inserted into table t1. </p></li> <li><p> No preexisting rows of t1 will be deleted or modified. </p></li> <li><p> No tables other than t1 will be altered in any way. </p></li> <li><p> No preexisting files on the host computers filesystem, other than the database file itself, will be deleted or modified. </p></li> <li><p> For some constants <b>K1</b> and <b>K2</b>, if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are available to <b>malloc()</b>, then the call to <b>sqlite_exec_printf()</b> will not return SQLITE_NOMEM. </p></li> </ol> </p></li> <li><p> The following are preconditions: <p><ul> <li><b>Z</b> is an arbitrary-length NUL-terminated string.</li> <li>An existing SQLite database has been opened. The return value from the call to <b>sqlite_open()</b> is stored in the variable <b>db</b>.</li> <li>There exists a callback function <b>cb()</b> that appends all information passed in through its parameters into a single data buffer called <b>Y</b>.</li> <li>There are no user-defined functions other than the standard build-in functions.</li> </ul></p> <p>The following statement of C code is executed:</p> <blockquote><pre> sqlite_exec(db, Z, cb, 0, 0); </pre></blockquote> <p>Prove the following are true for all possible values of string <b>Z</b>:</p> <ol type="a"> <li><p> The call to <b>sqlite_exec()</b> will return in a length of time which is a polynomial in <b>strlen(Z)</b>. It might return an error code but it will not crash. </p></li> <li><p> After <b>sqlite_exec()</b> returns, the buffer <b>Y</b> will not contain any content from any preexisting file on the host computers file system, except for the database file. </p></li> <li><p> After the call to <b>sqlite_exec()</b> returns, the database file will still be well-formed. It might not contain the same data, but it will still be a properly constructed SQLite database file. </p></li> <li><p> No preexisting files on the host computers filesystem, other than the database file itself, will be deleted or modified. </p></li> <li><p> For some constants <b>K1</b> and <b>K2</b>, if at least <b>K1*strlen(Z) + K2</b> bytes of contiguous memory are available to <b>malloc()</b>, then the call to <b>sqlite_exec()</b> will not return SQLITE_NOMEM. </p></li> </ol> </p></li> </ol> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | <title>SQLite Autoincrement</title> <h1>SQLite Autoincrement</h1> <p> In SQLite, every row of every table has an integer ROWID. The ROWID for each row is unique among all rows in the same table. In SQLite version 2.8 the ROWID is a 32-bit signed integer. Version 3.0 of SQLite expanded the ROWID to be a 64-bit signed integer. </p> <p> You can access the ROWID of an SQLite table using one the special column names ROWID, _ROWID_, or OID. Except if you declare an ordinary table column to use one of those special names, then the use of that name will refer to the declared column not to the internal ROWID. </p> <p> If a table contains a column of type INTEGER PRIMARY KEY, then that column becomes an alias for the ROWID. You can then access the ROWID using any of four different names, the original three names described above or the name given to the INTEGER PRIMARY KEY column. All these names are aliases for one another and work equally well in any context. </p> <p> When a new row is inserted into an SQLite table, the ROWID can either be specified as part of the INSERT statement or it can be assigned automatically by the database engine. To specify a ROWID manually, just include it in the list of values to be inserted. For example: </p> <blockquote><pre> CREATE TABLE test1(a INT, b TEXT); INSERT INTO test1(rowid, a, b) VALUES(123, 5, 'hello'); </pre></blockquote> <p> If no ROWID is specified on the insert, an appropriate ROWID is created automatically. The usual algorithm is to give the newly created row a ROWID that is one larger than the largest ROWID in the table prior to the insert. If the table is initially empty, then a ROWID of 1 is used. If the largest ROWID is equal to the largest possible integer (9223372036854775807 in SQLite version 3.0 and later) then the database engine starts picking candidate ROWIDs at random until it finds one that is not previously used. </p> <p> The normal ROWID selection algorithm described above will generate monotonically increasing unique ROWIDs as long as you never use the maximum ROWID value and you never delete the entry in the table with the largest ROWID. If you ever delete rows or if you ever create a row with the maximum possible ROWID, then ROWIDs from previously deleted rows might be reused when creating new rows and newly created ROWIDs might not be in strictly accending order. </p> <h2>The AUTOINCREMENT Keyword</h2> <p> If a column has the type INTEGER PRIMARY KEY AUTOINCREMENT then a slightly different ROWID selection algorithm is used. The ROWID chosen for the new row is one larger than the largest ROWID that has ever before existed in that same table. If the table has never before contained any data, then a ROWID of 1 is used. If the table has previously held a row with the largest possible ROWID, then new INSERTs are not allowed and any attempt to insert a new row will fail with an SQLITE_FULL error. </p> <p> SQLite keeps track of the largest ROWID that a table has ever held using the special SQLITE_SEQUENCE table. The SQLITE_SEQUENCE table is created and initialized automatically whenever a normal table that contains an AUTOINCREMENT column is created. The content of the SQLITE_SEQUENCE table can be modified using ordinary UPDATE, INSERT, and DELETE statements. But making modifications to this table will likely perturb the AUTOINCREMENT key generation algorithm. Make sure you know what you are doing before you undertake such changes. </p> <p> The behavior implemented by the AUTOINCREMENT keyword is subtly different from the default behavior. With AUTOINCREMENT, rows with automatically selected ROWIDs are guaranteed to have ROWIDs that have never been used before by the same table in the same database. And the automatically generated ROWIDs are guaranteed to be monotonically increasing. These are important properties in certain applications. But if your application does not need these properties, you should probably stay with the default behavior since the use of AUTOINCREMENT requires additional work to be done as each row is inserted and thus causes INSERTs to run a little slower. |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 | <title>The C language interface to SQLite Version 2</title> <h2>The C language interface to SQLite Version 2</h2> <p>The SQLite library is designed to be very easy to use from a C or C++ program. This document gives an overview of the C/C++ programming interface.</p> <h3>1.0 The Core API</h3> <p>The interface to the SQLite library consists of three core functions, one opaque data structure, and some constants used as return values. The core interface is as follows:</p> <blockquote><pre> typedef struct sqlite sqlite; #define SQLITE_OK 0 /* Successful result */ sqlite *sqlite_open(const char *dbname, int mode, char **errmsg); void sqlite_close(sqlite *db); int sqlite_exec( sqlite *db, char *sql, int (*xCallback)(void*,int,char**,char**), void *pArg, char **errmsg ); </pre></blockquote> <p> The above is all you really need to know in order to use SQLite in your C or C++ programs. There are other interface functions available (and described below) but we will begin by describing the core functions shown above. </p> <a name="sqlite_open"></a> <h4>1.1 Opening a database</h4> <p>Use the <b>sqlite_open</b> function to open an existing SQLite database or to create a new SQLite database. The first argument is the database name. The second argument is intended to signal whether the database is going to be used for reading and writing or just for reading. But in the current implementation, the second argument to <b>sqlite_open</b> is ignored. The third argument is a pointer to a string pointer. If the third argument is not NULL and an error occurs while trying to open the database, then an error message will be written to memory obtained from malloc() and *errmsg will be made to point to this error message. The calling function is responsible for freeing the memory when it has finished with it.</p> <p>The name of an SQLite database is the name of a file that will contain the database. If the file does not exist, SQLite attempts to create and initialize it. If the file is read-only (due to permission bits or because it is located on read-only media like a CD-ROM) then SQLite opens the database for reading only. The entire SQL database is stored in a single file on the disk. But additional temporary files may be created during the execution of an SQL command in order to store the database rollback journal or temporary and intermediate results of a query.</p> <p>The return value of the <b>sqlite_open</b> function is a pointer to an opaque <b>sqlite</b> structure. This pointer will be the first argument to all subsequent SQLite function calls that deal with the same database. NULL is returned if the open fails for any reason.</p> <a name="sqlite_close"></a> <h4>1.2 Closing the database</h4> <p>To close an SQLite database, call the <b>sqlite_close</b> function passing it the sqlite structure pointer that was obtained from a prior call to <b>sqlite_open</b>. If a transaction is active when the database is closed, the transaction is rolled back.</p> <a name="sqlite_exec"></a> <h4>1.3 Executing SQL statements</h4> <p>The <b>sqlite_exec</b> function is used to process SQL statements and queries. This function requires 5 parameters as follows:</p> <ol> <li><p>A pointer to the sqlite structure obtained from a prior call to <b>sqlite_open</b>.</p></li> <li><p>A null-terminated string containing the text of one or more SQL statements and/or queries to be processed.</p></li> <li><p>A pointer to a callback function which is invoked once for each row in the result of a query. This argument may be NULL, in which case no callbacks will ever be invoked.</p></li> <li><p>A pointer that is forwarded to become the first argument to the callback function.</p></li> <li><p>A pointer to an error string. Error messages are written to space obtained from malloc() and the error string is made to point to the malloced space. The calling function is responsible for freeing this space when it has finished with it. This argument may be NULL, in which case error messages are not reported back to the calling function.</p></li> </ol> <p> The callback function is used to receive the results of a query. A prototype for the callback function is as follows:</p> <blockquote><pre> int Callback(void *pArg, int argc, char **argv, char **columnNames){ return 0; } </pre></blockquote> <a name="callback_row_data"></a> <p>The first argument to the callback is just a copy of the fourth argument to <b>sqlite_exec</b> This parameter can be used to pass arbitrary information through to the callback function from client code. The second argument is the number of columns in the query result. The third argument is an array of pointers to strings where each string is a single column of the result for that record. Note that the callback function reports a NULL value in the database as a NULL pointer, which is very different from an empty string. If the i-th parameter is an empty string, we will get:</p> <blockquote><pre> argv[i][0] == 0 </pre></blockquote> <p>But if the i-th parameter is NULL we will get:</p> <blockquote><pre> argv[i] == 0 </pre></blockquote> <p>The names of the columns are contained in first <i>argc</i> entries of the fourth argument. If the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma is on (it is off by default) then the second <i>argc</i> entries in the 4th argument are the datatypes for the corresponding columns. </p> <p>If the <a href="pragma.html#pragma_empty_result_callbacks"> EMPTY_RESULT_CALLBACKS</a> pragma is set to ON and the result of a query is an empty set, then the callback is invoked once with the third parameter (argv) set to 0. In other words <blockquote><pre> argv == 0 </pre></blockquote> The second parameter (argc) and the fourth parameter (columnNames) are still valid and can be used to determine the number and names of the result columns if there had been a result. The default behavior is not to invoke the callback at all if the result set is empty.</p> <a name="callback_returns_nonzero"></a> <p>The callback function should normally return 0. If the callback function returns non-zero, the query is immediately aborted and <b>sqlite_exec</b> will return SQLITE_ABORT.</p> <h4>1.4 Error Codes</h4> <p> The <b>sqlite_exec</b> function normally returns SQLITE_OK. But if something goes wrong it can return a different value to indicate the type of error. Here is a complete list of the return codes: </p> <blockquote><pre> #define SQLITE_OK 0 /* Successful result */ #define SQLITE_ERROR 1 /* SQL error or missing database */ #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ #define SQLITE_PERM 3 /* Access permission denied */ #define SQLITE_ABORT 4 /* Callback routine requested an abort */ #define SQLITE_BUSY 5 /* The database file is locked */ #define SQLITE_LOCKED 6 /* A table in the database is locked */ #define SQLITE_NOMEM 7 /* A malloc() failed */ #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ #define SQLITE_MISMATCH 20 /* Data type mismatch */ #define SQLITE_MISUSE 21 /* Library used incorrectly */ #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ #define SQLITE_AUTH 23 /* Authorization denied */ #define SQLITE_ROW 100 /* sqlite_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite_step() has finished executing */ </pre></blockquote> <p> The meanings of these various return values are as follows: </p> <blockquote> <dl> <dt>SQLITE_OK</dt> <dd><p>This value is returned if everything worked and there were no errors. </p></dd> <dt>SQLITE_INTERNAL</dt> <dd><p>This value indicates that an internal consistency check within the SQLite library failed. This can only happen if there is a bug in the SQLite library. If you ever get an SQLITE_INTERNAL reply from an <b>sqlite_exec</b> call, please report the problem on the SQLite mailing list. </p></dd> <dt>SQLITE_ERROR</dt> <dd><p>This return value indicates that there was an error in the SQL that was passed into the <b>sqlite_exec</b>. </p></dd> <dt>SQLITE_PERM</dt> <dd><p>This return value says that the access permissions on the database file are such that the file cannot be opened. </p></dd> <dt>SQLITE_ABORT</dt> <dd><p>This value is returned if the callback function returns non-zero. </p></dd> <dt>SQLITE_BUSY</dt> <dd><p>This return code indicates that another program or thread has the database locked. SQLite allows two or more threads to read the database at the same time, but only one thread can have the database open for writing at the same time. Locking in SQLite is on the entire database.</p> </p></dd> <dt>SQLITE_LOCKED</dt> <dd><p>This return code is similar to SQLITE_BUSY in that it indicates that the database is locked. But the source of the lock is a recursive call to <b>sqlite_exec</b>. This return can only occur if you attempt to invoke sqlite_exec from within a callback routine of a query from a prior invocation of sqlite_exec. Recursive calls to sqlite_exec are allowed as long as they do not attempt to write the same table. </p></dd> <dt>SQLITE_NOMEM</dt> <dd><p>This value is returned if a call to <b>malloc</b> fails. </p></dd> <dt>SQLITE_READONLY</dt> <dd><p>This return code indicates that an attempt was made to write to a database file that is opened for reading only. </p></dd> <dt>SQLITE_INTERRUPT</dt> <dd><p>This value is returned if a call to <b>sqlite_interrupt</b> interrupts a database operation in progress. </p></dd> <dt>SQLITE_IOERR</dt> <dd><p>This value is returned if the operating system informs SQLite that it is unable to perform some disk I/O operation. This could mean that there is no more space left on the disk. </p></dd> <dt>SQLITE_CORRUPT</dt> <dd><p>This value is returned if SQLite detects that the database it is working on has become corrupted. Corruption might occur due to a rogue process writing to the database file or it might happen due to an perviously undetected logic error in of SQLite. This value is also returned if a disk I/O error occurs in such a way that SQLite is forced to leave the database file in a corrupted state. The latter should only happen due to a hardware or operating system malfunction. </p></dd> <dt>SQLITE_FULL</dt> <dd><p>This value is returned if an insertion failed because there is no space left on the disk, or the database is too big to hold any more information. The latter case should only occur for databases that are larger than 2GB in size. </p></dd> <dt>SQLITE_CANTOPEN</dt> <dd><p>This value is returned if the database file could not be opened for some reason. </p></dd> <dt>SQLITE_PROTOCOL</dt> <dd><p>This value is returned if some other process is messing with file locks and has violated the file locking protocol that SQLite uses on its rollback journal files. </p></dd> <dt>SQLITE_SCHEMA</dt> <dd><p>When the database first opened, SQLite reads the database schema into memory and uses that schema to parse new SQL statements. If another process changes the schema, the command currently being processed will abort because the virtual machine code generated assumed the old schema. This is the return code for such cases. Retrying the command usually will clear the problem. </p></dd> <dt>SQLITE_TOOBIG</dt> <dd><p>SQLite will not store more than about 1 megabyte of data in a single row of a single table. If you attempt to store more than 1 megabyte in a single row, this is the return code you get. </p></dd> <dt>SQLITE_CONSTRAINT</dt> <dd><p>This constant is returned if the SQL statement would have violated a database constraint. </p></dd> <dt>SQLITE_MISMATCH</dt> <dd><p>This error occurs when there is an attempt to insert non-integer data into a column labeled INTEGER PRIMARY KEY. For most columns, SQLite ignores the data type and allows any kind of data to be stored. But an INTEGER PRIMARY KEY column is only allowed to store integer data. </p></dd> <dt>SQLITE_MISUSE</dt> <dd><p>This error might occur if one or more of the SQLite API routines is used incorrectly. Examples of incorrect usage include calling <b>sqlite_exec</b> after the database has been closed using <b>sqlite_close</b> or calling <b>sqlite_exec</b> with the same database pointer simultaneously from two separate threads. </p></dd> <dt>SQLITE_NOLFS</dt> <dd><p>This error means that you have attempts to create or access a file database file that is larger that 2GB on a legacy Unix machine that lacks large file support. </p></dd> <dt>SQLITE_AUTH</dt> <dd><p>This error indicates that the authorizer callback has disallowed the SQL you are attempting to execute. </p></dd> <dt>SQLITE_ROW</dt> <dd><p>This is one of the return codes from the <b>sqlite_step</b> routine which is part of the non-callback API. It indicates that another row of result data is available. </p></dd> <dt>SQLITE_DONE</dt> <dd><p>This is one of the return codes from the <b>sqlite_step</b> routine which is part of the non-callback API. It indicates that the SQL statement has been completely executed and the <b>sqlite_finalize</b> routine is ready to be called. </p></dd> </dl> </blockquote> <h3>2.0 Accessing Data Without Using A Callback Function</h3> <p> The <b>sqlite_exec</b> routine described above used to be the only way to retrieve data from an SQLite database. But many programmers found it inconvenient to use a callback function to obtain results. So beginning with SQLite version 2.7.7, a second access interface is available that does not use callbacks. </p> <p> The new interface uses three separate functions to replace the single <b>sqlite_exec</b> function. </p> <blockquote><pre> typedef struct sqlite_vm sqlite_vm; int sqlite_compile( sqlite *db, /* The open database */ const char *zSql, /* SQL statement to be compiled */ const char **pzTail, /* OUT: uncompiled tail of zSql */ sqlite_vm **ppVm, /* OUT: the virtual machine to execute zSql */ char **pzErrmsg /* OUT: Error message. */ ); int sqlite_step( sqlite_vm *pVm, /* The virtual machine to execute */ int *pN, /* OUT: Number of columns in result */ const char ***pazValue, /* OUT: Column data */ const char ***pazColName /* OUT: Column names and datatypes */ ); int sqlite_finalize( sqlite_vm *pVm, /* The virtual machine to be finalized */ char **pzErrMsg /* OUT: Error message */ ); </pre></blockquote> <p> The strategy is to compile a single SQL statement using <b>sqlite_compile</b> then invoke <b>sqlite_step</b> multiple times, once for each row of output, and finally call <b>sqlite_finalize</b> to clean up after the SQL has finished execution. </p> <h4>2.1 Compiling An SQL Statement Into A Virtual Machine</h4> <p> The <b>sqlite_compile</b> "compiles" a single SQL statement (specified by the second parameter) and generates a virtual machine that is able to execute that statement. As with must interface routines, the first parameter must be a pointer to an sqlite structure that was obtained from a prior call to <b>sqlite_open</b>. <p> A pointer to the virtual machine is stored in a pointer which is passed in as the 4th parameter. Space to hold the virtual machine is dynamically allocated. To avoid a memory leak, the calling function must invoke <b>sqlite_finalize</b> on the virtual machine after it has finished with it. The 4th parameter may be set to NULL if an error is encountered during compilation. </p> <p> If any errors are encountered during compilation, an error message is written into memory obtained from <b>malloc</b> and the 5th parameter is made to point to that memory. If the 5th parameter is NULL, then no error message is generated. If the 5th parameter is not NULL, then the calling function should dispose of the memory containing the error message by calling <b>sqlite_freemem</b>. </p> <p> If the 2nd parameter actually contains two or more statements of SQL, only the first statement is compiled. (This is different from the behavior of <b>sqlite_exec</b> which executes all SQL statements in its input string.) The 3rd parameter to <b>sqlite_compile</b> is made to point to the first character beyond the end of the first statement of SQL in the input. If the 2nd parameter contains only a single SQL statement, then the 3rd parameter will be made to point to the '\000' terminator at the end of the 2nd parameter. </p> <p> On success, <b>sqlite_compile</b> returns SQLITE_OK. Otherwise and error code is returned. </p> <h4>2.2 Step-By-Step Execution Of An SQL Statement</h4> <p> After a virtual machine has been generated using <b>sqlite_compile</b> it is executed by one or more calls to <b>sqlite_step</b>. Each invocation of <b>sqlite_step</b>, except the last one, returns a single row of the result. The number of columns in the result is stored in the integer that the 2nd parameter points to. The pointer specified by the 3rd parameter is made to point to an array of pointers to column values. The pointer in the 4th parameter is made to point to an array of pointers to column names and datatypes. The 2nd through 4th parameters to <b>sqlite_step</b> convey the same information as the 2nd through 4th parameters of the <b>callback</b> routine when using the <b>sqlite_exec</b> interface. Except, with <b>sqlite_step</b> the column datatype information is always included in the in the 4th parameter regardless of whether or not the <a href="pragma.html#pragma_show_datatypes">SHOW_DATATYPES</a> pragma is on or off. </p> <p> Each invocation of <b>sqlite_step</b> returns an integer code that indicates what happened during that step. This code may be SQLITE_BUSY, SQLITE_ROW, SQLITE_DONE, SQLITE_ERROR, or SQLITE_MISUSE. </p> <p> If the virtual machine is unable to open the database file because it is locked by another thread or process, <b>sqlite_step</b> will return SQLITE_BUSY. The calling function should do some other activity, or sleep, for a short amount of time to give the lock a chance to clear, then invoke <b>sqlite_step</b> again. This can be repeated as many times as desired. </p> <p> Whenever another row of result data is available, <b>sqlite_step</b> will return SQLITE_ROW. The row data is stored in an array of pointers to strings and the 2nd parameter is made to point to this array. </p> <p> When all processing is complete, <b>sqlite_step</b> will return either SQLITE_DONE or SQLITE_ERROR. SQLITE_DONE indicates that the statement completed successfully and SQLITE_ERROR indicates that there was a run-time error. (The details of the error are obtained from <b>sqlite_finalize</b>.) It is a misuse of the library to attempt to call <b>sqlite_step</b> again after it has returned SQLITE_DONE or SQLITE_ERROR. </p> <p> When <b>sqlite_step</b> returns SQLITE_DONE or SQLITE_ERROR, the *pN and *pazColName values are set to the number of columns in the result set and to the names of the columns, just as they are for an SQLITE_ROW return. This allows the calling code to find the number of result columns and the column names and datatypes even if the result set is empty. The *pazValue parameter is always set to NULL when the return codes is SQLITE_DONE or SQLITE_ERROR. If the SQL being executed is a statement that does not return a result (such as an INSERT or an UPDATE) then *pN will be set to zero and *pazColName will be set to NULL. </p> <p> If you abuse the library by trying to call <b>sqlite_step</b> inappropriately it will attempt return SQLITE_MISUSE. This can happen if you call sqlite_step() on the same virtual machine at the same time from two or more threads or if you call sqlite_step() again after it returned SQLITE_DONE or SQLITE_ERROR or if you pass in an invalid virtual machine pointer to sqlite_step(). You should not depend on the SQLITE_MISUSE return code to indicate an error. It is possible that a misuse of the interface will go undetected and result in a program crash. The SQLITE_MISUSE is intended as a debugging aid only - to help you detect incorrect usage prior to a mishap. The misuse detection logic is not guaranteed to work in every case. </p> <h4>2.3 Deleting A Virtual Machine</h4> <p> Every virtual machine that <b>sqlite_compile</b> creates should eventually be handed to <b>sqlite_finalize</b>. The sqlite_finalize() procedure deallocates the memory and other resources that the virtual machine uses. Failure to call sqlite_finalize() will result in resource leaks in your program. </p> <p> The <b>sqlite_finalize</b> routine also returns the result code that indicates success or failure of the SQL operation that the virtual machine carried out. The value returned by sqlite_finalize() will be the same as would have been returned had the same SQL been executed by <b>sqlite_exec</b>. The error message returned will also be the same. </p> <p> It is acceptable to call <b>sqlite_finalize</b> on a virtual machine before <b>sqlite_step</b> has returned SQLITE_DONE. Doing so has the effect of interrupting the operation in progress. Partially completed changes will be rolled back and the database will be restored to its original state (unless an alternative recovery algorithm is selected using an ON CONFLICT clause in the SQL being executed.) The effect is the same as if a callback function of <b>sqlite_exec</b> had returned non-zero. </p> <p> It is also acceptable to call <b>sqlite_finalize</b> on a virtual machine that has never been passed to <b>sqlite_step</b> even once. </p> <h3>3.0 The Extended API</h3> <p>Only the three core routines described in section 1.0 are required to use SQLite. But there are many other functions that provide useful interfaces. These extended routines are as follows: </p> <blockquote><pre> int sqlite_last_insert_rowid(sqlite*); int sqlite_changes(sqlite*); int sqlite_get_table( sqlite*, char *sql, char ***result, int *nrow, int *ncolumn, char **errmsg ); void sqlite_free_table(char**); void sqlite_interrupt(sqlite*); int sqlite_complete(const char *sql); void sqlite_busy_handler(sqlite*, int (*)(void*,const char*,int), void*); void sqlite_busy_timeout(sqlite*, int ms); const char sqlite_version[]; const char sqlite_encoding[]; int sqlite_exec_printf( sqlite*, char *sql, int (*)(void*,int,char**,char**), void*, char **errmsg, ... ); int sqlite_exec_vprintf( sqlite*, char *sql, int (*)(void*,int,char**,char**), void*, char **errmsg, va_list ); int sqlite_get_table_printf( sqlite*, char *sql, char ***result, int *nrow, int *ncolumn, char **errmsg, ... ); int sqlite_get_table_vprintf( sqlite*, char *sql, char ***result, int *nrow, int *ncolumn, char **errmsg, va_list ); char *sqlite_mprintf(const char *zFormat, ...); char *sqlite_vmprintf(const char *zFormat, va_list); void sqlite_freemem(char*); void sqlite_progress_handler(sqlite*, int, int (*)(void*), void*); </pre></blockquote> <p>All of the above definitions are included in the "sqlite.h" header file that comes in the source tree.</p> <h4>3.1 The ROWID of the most recent insert</h4> <p>Every row of an SQLite table has a unique integer key. If the table has a column labeled INTEGER PRIMARY KEY, then that column serves as the key. If there is no INTEGER PRIMARY KEY column then the key is a unique integer. The key for a row can be accessed in a SELECT statement or used in a WHERE or ORDER BY clause using any of the names "ROWID", "OID", or "_ROWID_".</p> <p>When you do an insert into a table that does not have an INTEGER PRIMARY KEY column, or if the table does have an INTEGER PRIMARY KEY but the value for that column is not specified in the VALUES clause of the insert, then the key is automatically generated. You can find the value of the key for the most recent INSERT statement using the <b>sqlite_last_insert_rowid</b> API function.</p> <h4>3.2 The number of rows that changed</h4> <p>The <b>sqlite_changes</b> API function returns the number of rows that have been inserted, deleted, or modified since the database was last quiescent. A "quiescent" database is one in which there are no outstanding calls to <b>sqlite_exec</b> and no VMs created by <b>sqlite_compile</b> that have not been finalized by <b>sqlite_finalize</b>. In common usage, <b>sqlite_changes</b> returns the number of rows inserted, deleted, or modified by the most recent <b>sqlite_exec</b> call or since the most recent <b>sqlite_compile</b>. But if you have nested calls to <b>sqlite_exec</b> (that is, if the callback routine of one <b>sqlite_exec</b> invokes another <b>sqlite_exec</b>) or if you invoke <b>sqlite_compile</b> to create a new VM while there is still another VM in existance, then the meaning of the number returned by <b>sqlite_changes</b> is more complex. The number reported includes any changes that were later undone by a ROLLBACK or ABORT. But rows that are deleted because of a DROP TABLE are <em>not</em> counted.</p> <p>SQLite implements the command "<b>DELETE FROM table</b>" (without a WHERE clause) by dropping the table then recreating it. This is much faster than deleting the elements of the table individually. But it also means that the value returned from <b>sqlite_changes</b> will be zero regardless of the number of elements that were originally in the table. If an accurate count of the number of elements deleted is necessary, use "<b>DELETE FROM table WHERE 1</b>" instead.</p> <h4>3.3 Querying into memory obtained from malloc()</h4> <p>The <b>sqlite_get_table</b> function is a wrapper around <b>sqlite_exec</b> that collects all the information from successive callbacks and writes it into memory obtained from malloc(). This is a convenience function that allows the application to get the entire result of a database query with a single function call.</p> <p>The main result from <b>sqlite_get_table</b> is an array of pointers to strings. There is one element in this array for each column of each row in the result. NULL results are represented by a NULL pointer. In addition to the regular data, there is an added row at the beginning of the array that contains the name of each column of the result.</p> <p>As an example, consider the following query:</p> <blockquote> SELECT employee_name, login, host FROM users WHERE login LIKE 'd%'; </blockquote> <p>This query will return the name, login and host computer name for every employee whose login begins with the letter "d". If this query is submitted to <b>sqlite_get_table</b> the result might look like this:</p> <blockquote> nrow = 2<br> ncolumn = 3<br> result[0] = "employee_name"<br> result[1] = "login"<br> result[2] = "host"<br> result[3] = "dummy"<br> result[4] = "No such user"<br> result[5] = 0<br> result[6] = "D. Richard Hipp"<br> result[7] = "drh"<br> result[8] = "zadok" </blockquote> <p>Notice that the "host" value for the "dummy" record is NULL so the result[] array contains a NULL pointer at that slot.</p> <p>If the result set of a query is empty, then by default <b>sqlite_get_table</b> will set nrow to 0 and leave its result parameter is set to NULL. But if the EMPTY_RESULT_CALLBACKS pragma is ON then the result parameter is initialized to the names of the columns only. For example, consider this query which has an empty result set:</p> <blockquote> SELECT employee_name, login, host FROM users WHERE employee_name IS NULL; </blockquote> <p> The default behavior gives this results: </p> <blockquote> nrow = 0<br> ncolumn = 0<br> result = 0<br> </blockquote> <p> But if the EMPTY_RESULT_CALLBACKS pragma is ON, then the following is returned: </p> <blockquote> nrow = 0<br> ncolumn = 3<br> result[0] = "employee_name"<br> result[1] = "login"<br> result[2] = "host"<br> </blockquote> <p>Memory to hold the information returned by <b>sqlite_get_table</b> is obtained from malloc(). But the calling function should not try to free this information directly. Instead, pass the complete table to <b>sqlite_free_table</b> when the table is no longer needed. It is safe to call <b>sqlite_free_table</b> with a NULL pointer such as would be returned if the result set is empty.</p> <p>The <b>sqlite_get_table</b> routine returns the same integer result code as <b>sqlite_exec</b>.</p> <h4>3.4 Interrupting an SQLite operation</h4> <p>The <b>sqlite_interrupt</b> function can be called from a different thread or from a signal handler to cause the current database operation to exit at its first opportunity. When this happens, the <b>sqlite_exec</b> routine (or the equivalent) that started the database operation will return SQLITE_INTERRUPT.</p> <h4>3.5 Testing for a complete SQL statement</h4> <p>The next interface routine to SQLite is a convenience function used to test whether or not a string forms a complete SQL statement. If the <b>sqlite_complete</b> function returns true when its input is a string, then the argument forms a complete SQL statement. There are no guarantees that the syntax of that statement is correct, but we at least know the statement is complete. If <b>sqlite_complete</b> returns false, then more text is required to complete the SQL statement.</p> <p>For the purpose of the <b>sqlite_complete</b> function, an SQL statement is complete if it ends in a semicolon.</p> <p>The <b>sqlite</b> command-line utility uses the <b>sqlite_complete</b> function to know when it needs to call <b>sqlite_exec</b>. After each line of input is received, <b>sqlite</b> calls <b>sqlite_complete</b> on all input in its buffer. If <b>sqlite_complete</b> returns true, then <b>sqlite_exec</b> is called and the input buffer is reset. If <b>sqlite_complete</b> returns false, then the prompt is changed to the continuation prompt and another line of text is read and added to the input buffer.</p> <h4>3.6 Library version string</h4> <p>The SQLite library exports the string constant named <b>sqlite_version</b> which contains the version number of the library. The header file contains a macro SQLITE_VERSION with the same information. If desired, a program can compare the SQLITE_VERSION macro against the <b>sqlite_version</b> string constant to verify that the version number of the header file and the library match.</p> <h4>3.7 Library character encoding</h4> <p>By default, SQLite assumes that all data uses a fixed-size 8-bit character (iso8859). But if you give the --enable-utf8 option to the configure script, then the library assumes UTF-8 variable sized characters. This makes a difference for the LIKE and GLOB operators and the LENGTH() and SUBSTR() functions. The static string <b>sqlite_encoding</b> will be set to either "UTF-8" or "iso8859" to indicate how the library was compiled. In addition, the <b>sqlite.h</b> header file will define one of the macros <b>SQLITE_UTF8</b> or <b>SQLITE_ISO8859</b>, as appropriate.</p> <p>Note that the character encoding mechanism used by SQLite cannot be changed at run-time. This is a compile-time option only. The <b>sqlite_encoding</b> character string just tells you how the library was compiled.</p> <h4>3.8 Changing the library's response to locked files</h4> <p>The <b>sqlite_busy_handler</b> procedure can be used to register a busy callback with an open SQLite database. The busy callback will be invoked whenever SQLite tries to access a database that is locked. The callback will typically do some other useful work, or perhaps sleep, in order to give the lock a chance to clear. If the callback returns non-zero, then SQLite tries again to access the database and the cycle repeats. If the callback returns zero, then SQLite aborts the current operation and returns SQLITE_BUSY.</p> <p>The arguments to <b>sqlite_busy_handler</b> are the opaque structure returned from <b>sqlite_open</b>, a pointer to the busy callback function, and a generic pointer that will be passed as the first argument to the busy callback. When SQLite invokes the busy callback, it sends it three arguments: the generic pointer that was passed in as the third argument to <b>sqlite_busy_handler</b>, the name of the database table or index that the library is trying to access, and the number of times that the library has attempted to access the database table or index.</p> <p>For the common case where we want the busy callback to sleep, the SQLite library provides a convenience routine <b>sqlite_busy_timeout</b>. The first argument to <b>sqlite_busy_timeout</b> is a pointer to an open SQLite database and the second argument is a number of milliseconds. After <b>sqlite_busy_timeout</b> has been executed, the SQLite library will wait for the lock to clear for at least the number of milliseconds specified before it returns SQLITE_BUSY. Specifying zero milliseconds for the timeout restores the default behavior.</p> <h4>3.9 Using the <tt>_printf()</tt> wrapper functions</h4> <p>The four utility functions</p> <p> <ul> <li><b>sqlite_exec_printf()</b></li> <li><b>sqlite_exec_vprintf()</b></li> <li><b>sqlite_get_table_printf()</b></li> <li><b>sqlite_get_table_vprintf()</b></li> </ul> </p> <p>implement the same query functionality as <b>sqlite_exec</b> and <b>sqlite_get_table</b>. But instead of taking a complete SQL statement as their second argument, the four <b>_printf</b> routines take a printf-style format string. The SQL statement to be executed is generated from this format string and from whatever additional arguments are attached to the end of the function call.</p> <p>There are two advantages to using the SQLite printf functions instead of <b>sprintf</b>. First of all, with the SQLite printf routines, there is never a danger of overflowing a static buffer as there is with <b>sprintf</b>. The SQLite printf routines automatically allocate (and later frees) as much memory as is necessary to hold the SQL statements generated.</p> <p>The second advantage the SQLite printf routines have over <b>sprintf</b> are two new formatting options specifically designed to support string literals in SQL. Within the format string, the %q formatting option works very much like %s in that it reads a null-terminated string from the argument list and inserts it into the result. But %q translates the inserted string by making two copies of every single-quote (') character in the substituted string. This has the effect of escaping the end-of-string meaning of single-quote within a string literal. The %Q formatting option works similar; it translates the single-quotes like %q and additionally encloses the resulting string in single-quotes. If the argument for the %Q formatting options is a NULL pointer, the resulting string is NULL without single quotes. </p> <p>Consider an example. Suppose you are trying to insert a string value into a database table where the string value was obtained from user input. Suppose the string to be inserted is stored in a variable named zString. The code to do the insertion might look like this:</p> <blockquote><pre> sqlite_exec_printf(db, "INSERT INTO table1 VALUES('%s')", 0, 0, 0, zString); </pre></blockquote> <p>If the zString variable holds text like "Hello", then this statement will work just fine. But suppose the user enters a string like "Hi y'all!". The SQL statement generated reads as follows: <blockquote><pre> INSERT INTO table1 VALUES('Hi y'all') </pre></blockquote> <p>This is not valid SQL because of the apostrophy in the word "y'all". But if the %q formatting option is used instead of %s, like this:</p> <blockquote><pre> sqlite_exec_printf(db, "INSERT INTO table1 VALUES('%q')", 0, 0, 0, zString); </pre></blockquote> <p>Then the generated SQL will look like the following:</p> <blockquote><pre> INSERT INTO table1 VALUES('Hi y''all') </pre></blockquote> <p>Here the apostrophy has been escaped and the SQL statement is well-formed. When generating SQL on-the-fly from data that might contain a single-quote character ('), it is always a good idea to use the SQLite printf routines and the %q formatting option instead of <b>sprintf</b>. </p> <p>If the %Q formatting option is used instead of %q, like this:</p> <blockquote><pre> sqlite_exec_printf(db, "INSERT INTO table1 VALUES(%Q)", 0, 0, 0, zString); </pre></blockquote> <p>Then the generated SQL will look like the following:</p> <blockquote><pre> INSERT INTO table1 VALUES('Hi y''all') </pre></blockquote> <p>If the value of the zString variable is NULL, the generated SQL will look like the following:</p> <blockquote><pre> INSERT INTO table1 VALUES(NULL) </pre></blockquote> <p>All of the _printf() routines above are built around the following two functions:</p> <blockquote><pre> char *sqlite_mprintf(const char *zFormat, ...); char *sqlite_vmprintf(const char *zFormat, va_list); </pre></blockquote> <p>The <b>sqlite_mprintf()</b> routine works like the the standard library <b>sprintf()</b> except that it writes its results into memory obtained from malloc() and returns a pointer to the malloced buffer. <b>sqlite_mprintf()</b> also understands the %q and %Q extensions described above. The <b>sqlite_vmprintf()</b> is a varargs version of the same routine. The string pointer that these routines return should be freed by passing it to <b>sqlite_freemem()</b>. </p> <h4>3.10 Performing background jobs during large queries</h3> <p>The <b>sqlite_progress_handler()</b> routine can be used to register a callback routine with an SQLite database to be invoked periodically during long running calls to <b>sqlite_exec()</b>, <b>sqlite_step()</b> and the various wrapper functions. </p> <p>The callback is invoked every N virtual machine operations, where N is supplied as the second argument to <b>sqlite_progress_handler()</b>. The third and fourth arguments to <b>sqlite_progress_handler()</b> are a pointer to the routine to be invoked and a void pointer to be passed as the first argument to it. </p> <p>The time taken to execute each virtual machine operation can vary based on many factors. A typical value for a 1 GHz PC is between half and three million per second but may be much higher or lower, depending on the query. As such it is difficult to schedule background operations based on virtual machine operations. Instead, it is recommended that a callback be scheduled relatively frequently (say every 1000 instructions) and external timer routines used to determine whether or not background jobs need to be run. </p> <a name="cfunc"></a> <h3>4.0 Adding New SQL Functions</h3> <p>Beginning with version 2.4.0, SQLite allows the SQL language to be extended with new functions implemented as C code. The following interface is used: </p> <blockquote><pre> typedef struct sqlite_func sqlite_func; int sqlite_create_function( sqlite *db, const char *zName, int nArg, void (*xFunc)(sqlite_func*,int,const char**), void *pUserData ); int sqlite_create_aggregate( sqlite *db, const char *zName, int nArg, void (*xStep)(sqlite_func*,int,const char**), void (*xFinalize)(sqlite_func*), void *pUserData ); char *sqlite_set_result_string(sqlite_func*,const char*,int); void sqlite_set_result_int(sqlite_func*,int); void sqlite_set_result_double(sqlite_func*,double); void sqlite_set_result_error(sqlite_func*,const char*,int); void *sqlite_user_data(sqlite_func*); void *sqlite_aggregate_context(sqlite_func*, int nBytes); int sqlite_aggregate_count(sqlite_func*); </pre></blockquote> <p> The <b>sqlite_create_function()</b> interface is used to create regular functions and <b>sqlite_create_aggregate()</b> is used to create new aggregate functions. In both cases, the <b>db</b> parameter is an open SQLite database on which the functions should be registered, <b>zName</b> is the name of the new function, <b>nArg</b> is the number of arguments, and <b>pUserData</b> is a pointer which is passed through unchanged to the C implementation of the function. Both routines return 0 on success and non-zero if there are any errors. </p> <p> The length of a function name may not exceed 255 characters. Any attempt to create a function whose name exceeds 255 characters in length will result in an error. </p> <p> For regular functions, the <b>xFunc</b> callback is invoked once for each function call. The implementation of xFunc should call one of the <b>sqlite_set_result_...</b> interfaces to return its result. The <b>sqlite_user_data()</b> routine can be used to retrieve the <b>pUserData</b> pointer that was passed in when the function was registered. </p> <p> For aggregate functions, the <b>xStep</b> callback is invoked once for each row in the result and then <b>xFinalize</b> is invoked at the end to compute a final answer. The xStep routine can use the <b>sqlite_aggregate_context()</b> interface to allocate memory that will be unique to that particular instance of the SQL function. This memory will be automatically deleted after xFinalize is called. The <b>sqlite_aggregate_count()</b> routine can be used to find out how many rows of data were passed to the aggregate. The xFinalize callback should invoke one of the <b>sqlite_set_result_...</b> interfaces to set the final result of the aggregate. </p> <p> SQLite now implements all of its built-in functions using this interface. For additional information and examples on how to create new SQL functions, review the SQLite source code in the file <b>func.c</b>. </p> <h3>5.0 Multi-Threading And SQLite</h3> <p> If SQLite is compiled with the THREADSAFE preprocessor macro set to 1, then it is safe to use SQLite from two or more threads of the same process at the same time. But each thread should have its own <b>sqlite*</b> pointer returned from <b>sqlite_open</b>. It is never safe for two or more threads to access the same <b>sqlite*</b> pointer at the same time. </p> <p> In precompiled SQLite libraries available on the website, the Unix versions are compiled with THREADSAFE turned off but the windows versions are compiled with THREADSAFE turned on. If you need something different that this you will have to recompile. </p> <p> Under Unix, an <b>sqlite*</b> pointer should not be carried across a <b>fork()</b> system call into the child process. The child process should open its own copy of the database after the <b>fork()</b>. </p> <h3>6.0 Usage Examples</h3> <p>For examples of how the SQLite C/C++ interface can be used, refer to the source code for the <b>sqlite</b> program in the file <b>src/shell.c</b> of the source tree. Additional information about sqlite is available at <a href="sqlite.html">sqlite.html</a>. See also the sources to the Tcl interface for SQLite in the source file <b>src/tclsqlite.c</b>.</p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 | <title>C/C++ Interface For SQLite Version 3</title> <tcl> proc AddHyperlinks {txt} { regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \ {\1<a href="capi3ref.html#\2">\2</a>\3} t2 puts $t2 } AddHyperlinks { <h2>C/C++ Interface For SQLite Version 3</h2> <h3>1.0 Overview</h3> <p> SQLite version 3.0 is a new version of SQLite, derived from the SQLite 2.8.13 code base, but with an incompatible file format and API. SQLite version 3.0 was created to answer demand for the following features: </p> <ul> <li>Support for UTF-16.</li> <li>User-definable text collating sequences.</li> <li>The ability to store BLOBs in indexed columns.</li> </ul> <p> It was necessary to move to version 3.0 to implement these features because each requires incompatible changes to the database file format. Other incompatible changes, such as a cleanup of the API, were introduced at the same time under the theory that it is best to get your incompatible changes out of the way all at once. </p> <p> The API for version 3.0 is similar to the version 2.X API, but with some important changes. Most noticeably, the "<tt>sqlite_</tt>" prefix that occurs on the beginning of all API functions and data structures are changed to "<tt>sqlite3_</tt>". This avoids confusion between the two APIs and allows linking against both SQLite 2.X and SQLite 3.0 at the same time. </p> <p> There is no agreement on what the C datatype for a UTF-16 string should be. Therefore, SQLite uses a generic type of void* to refer to UTF-16 strings. Client software can cast the void* to whatever datatype is appropriate for their system. </p> <h3>2.0 C/C++ Interface</h3> <p> The API for SQLite 3.0 includes 83 separate functions in addition to several data structures and #defines. (A complete <a href="capi3ref.html">API reference</a> is provided as a separate document.) Fortunately, the interface is not nearly as complex as its size implies. Simple programs can still make do with only 3 functions: <a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>, <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>, and <a href="capi3ref.html#sqlite3_close">sqlite3_close()</a>. More control over the execution of the database engine is provided using <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> to compile an SQLite statement into byte code and <a href="capi3ref.html#sqlite3_prepare">sqlite3_step()</a> to execute that bytecode. A family of routines with names beginning with <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_</a> is used to extract information about the result set of a query. Many interface functions come in pairs, with both a UTF-8 and UTF-16 version. And there is a collection of routines used to implement user-defined SQL functions and user-defined text collating sequences. </p> <h4>2.1 Opening and closing a database</h4> <blockquote><pre> typedef struct sqlite3 sqlite3; int sqlite3_open(const char*, sqlite3**); int sqlite3_open16(const void*, sqlite3**); int sqlite3_close(sqlite3*); const char *sqlite3_errmsg(sqlite3*); const void *sqlite3_errmsg16(sqlite3*); int sqlite3_errcode(sqlite3*); </pre></blockquote> <p> The sqlite3_open() routine returns an integer error code rather than a pointer to the sqlite3 structure as the version 2 interface did. The difference between sqlite3_open() and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native byte order) for the name of the database file. If a new database file needs to be created, then sqlite3_open16() sets the internal text representation to UTF-16 whereas sqlite3_open() sets the text representation to UTF-8. </p> <p> The opening and/or creating of the database file is deferred until the file is actually needed. This allows options and parameters, such as the native text representation and default page size, to be set using PRAGMA statements. </p> <p> The sqlite3_errcode() routine returns a result code for the most recent major API call. sqlite3_errmsg() returns an English-language text error message for the most recent error. The error message is represented in UTF-8 and will be ephemeral - it could disappear on the next call to any SQLite API function. sqlite3_errmsg16() works like sqlite3_errmsg() except that it returns the error message represented as UTF-16 in host native byte order. </p> <p> The error codes for SQLite version 3 are unchanged from version 2. They are as follows: </p> <blockquote><pre> #define SQLITE_OK 0 /* Successful result */ #define SQLITE_ERROR 1 /* SQL error or missing database */ #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */ #define SQLITE_PERM 3 /* Access permission denied */ #define SQLITE_ABORT 4 /* Callback routine requested an abort */ #define SQLITE_BUSY 5 /* The database file is locked */ #define SQLITE_LOCKED 6 /* A table in the database is locked */ #define SQLITE_NOMEM 7 /* A malloc() failed */ #define SQLITE_READONLY 8 /* Attempt to write a readonly database */ #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */ #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */ #define SQLITE_CORRUPT 11 /* The database disk image is malformed */ #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */ #define SQLITE_FULL 13 /* Insertion failed because database is full */ #define SQLITE_CANTOPEN 14 /* Unable to open the database file */ #define SQLITE_PROTOCOL 15 /* Database lock protocol error */ #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */ #define SQLITE_SCHEMA 17 /* The database schema changed */ #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */ #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */ #define SQLITE_MISMATCH 20 /* Data type mismatch */ #define SQLITE_MISUSE 21 /* Library used incorrectly */ #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */ #define SQLITE_AUTH 23 /* Authorization denied */ #define SQLITE_ROW 100 /* sqlite_step() has another row ready */ #define SQLITE_DONE 101 /* sqlite_step() has finished executing */ </pre></blockquote> <h4>2.2 Executing SQL statements</h4> <blockquote><pre> typedef int (*sqlite_callback)(void*,int,char**, char**); int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**); </pre></blockquote> <p> The sqlite3_exec function works much as it did in SQLite version 2. Zero or more SQL statements specified in the second parameter are compiled and executed. Query results are returned to a callback routine. See the <a href="capi3ref.html#sqlite3_exec">API reference</a> for additional information. </p> <p> In SQLite version 3, the sqlite3_exec routine is just a wrapper around calls to the prepared statement interface. </p> <blockquote><pre> typedef struct sqlite3_stmt sqlite3_stmt; int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**); int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**); int sqlite3_finalize(sqlite3_stmt*); int sqlite3_reset(sqlite3_stmt*); </pre></blockquote> <p> The sqlite3_prepare interface compiles a single SQL statement into byte code for later execution. This interface is now the preferred way of accessing the database. </p> <p> The SQL statement is a UTF-8 string for sqlite3_prepare(). The sqlite3_prepare16() works the same way except that it expects a UTF-16 string as SQL input. Only the first SQL statement in the input string is compiled. The fourth parameter is filled in with a pointer to the next (uncompiled) SQLite statement in the input string, if any. The sqlite3_finalize() routine deallocates a prepared SQL statement. All prepared statements must be finalized before the database can be closed. The sqlite3_reset() routine resets a prepared SQL statement so that it can be executed again. </p> <p> The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa" where "nnn" is an integer and "aaa" is an identifier. Such tokens represent unspecified literal values (or "wildcards") to be filled in later by the <a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind</a> interface. Each wildcard has an associated number which is its sequence in the statement or the "nnn" in the case of a "?nnn" form. It is allowed for the same wildcard to occur more than once in the same SQL statement, in which case all instance of that wildcard will be filled in with the same value. Unbound wildcards have a value of NULL. </p> <blockquote><pre> int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_double(sqlite3_stmt*, int, double); int sqlite3_bind_int(sqlite3_stmt*, int, int); int sqlite3_bind_int64(sqlite3_stmt*, int, long long int); int sqlite3_bind_null(sqlite3_stmt*, int); int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*)); int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); </pre></blockquote> <p> There is an assortment of sqlite3_bind routines used to assign values to wildcards in a prepared SQL statement. Unbound wildcards are interpreted as NULLs. Bindings are not reset by sqlite3_reset(). But wildcards can be rebound to new values after an sqlite3_reset(). </p> <p> After an SQL statement has been prepared (and optionally bound), it is executed using: </p> <blockquote><pre> int sqlite3_step(sqlite3_stmt*); </pre></blockquote> <p> The sqlite3_step() routine return SQLITE_ROW if it is returning a single row of the result set, or SQLITE_DONE if execution has completed, either normally or due to an error. It might also return SQLITE_BUSY if it is unable to open the database file. If the return value is SQLITE_ROW, then the following routines can be used to extract information about that row of the result set: </p> <blockquote><pre> const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); int sqlite3_column_bytes(sqlite3_stmt*, int iCol); int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); int sqlite3_column_count(sqlite3_stmt*); const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol); const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol); double sqlite3_column_double(sqlite3_stmt*, int iCol); int sqlite3_column_int(sqlite3_stmt*, int iCol); long long int sqlite3_column_int64(sqlite3_stmt*, int iCol); const char *sqlite3_column_name(sqlite3_stmt*, int iCol); const void *sqlite3_column_name16(sqlite3_stmt*, int iCol); const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); int sqlite3_column_type(sqlite3_stmt*, int iCol); </pre></blockquote> <p> The <a href="capi3ref.html#sqlite3_column_count">sqlite3_column_count()</a> function returns the number of columns in the results set. sqlite3_column_count() can be called at any time after sqlite3_prepare(). <a href="capi3ref.html#sqlite3_data_count">sqlite3_data_count()</a> works similarly to sqlite3_column_count() except that it only works following sqlite3_step(). If the previous call to sqlite3_step() returned SQLITE_DONE or an error code, then sqlite3_data_count() will return 0 whereas sqlite3_column_count() will continue to return the number of columns in the result set. </p> <p>Returned data is examined using the other sqlite3_column_***() functions, all of which take a column number as their second parameter. Columns are zero-indexed from left to right. Note that this is different to parameters, which are indexed starting at one. </p> <p> The sqlite3_column_type() function returns the datatype for the value in the Nth column. The return value is one of these: </p> <blockquote><pre> #define SQLITE_INTEGER 1 #define SQLITE_FLOAT 2 #define SQLITE_TEXT 3 #define SQLITE_BLOB 4 #define SQLITE_NULL 5 </pre></blockquote> <p> The sqlite3_column_decltype() routine returns text which is the declared type of the column in the CREATE TABLE statement. For an expression, the return type is an empty string. sqlite3_column_name() returns the name of the Nth column. sqlite3_column_bytes() returns the number of bytes in a column that has type BLOB or the number of bytes in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns the same value for BLOBs but for TEXT strings returns the number of bytes in a UTF-16 encoding. sqlite3_column_blob() return BLOB data. sqlite3_column_text() return TEXT data as UTF-8. sqlite3_column_text16() return TEXT data as UTF-16. sqlite3_column_int() return INTEGER data in the host machines native integer format. sqlite3_column_int64() returns 64-bit INTEGER data. Finally, sqlite3_column_double() return floating point data. </p> <p> It is not necessary to retrieve data in the format specify by sqlite3_column_type(). If a different format is requested, the data is converted automatically. </p> <p> Data format conversions can invalidate the pointer returned by prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16(). Pointers might be invalided in the following cases: </p> <ul> <li><p> The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() is called. A zero-terminator might need to be added to the string. </p></li> <li><p> The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() is called. The content must be converted to UTF-16. </p></li> <li><p> The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() is called. The content must be converted to UTF-8. </p></li> </ul> <p> Note that conversions between UTF-16be and UTF-16le are always done in place and do not invalidate a prior pointer, though of course the content of the buffer that the prior pointer points to will have been modified. Other kinds of conversion are done in place when it is possible, but sometime it is not possible and in those cases prior pointers are invalidated. </p> <p> The safest and easiest to remember policy is this: assume that any result from <ul> <li>sqlite3_column_blob(),</li> <li>sqlite3_column_text(), or</li> <li>sqlite3_column_text16()</li> </ul> is invalided by subsequent calls to <ul> <li>sqlite3_column_bytes(),</li> <li>sqlite3_column_bytes16(),</li> <li>sqlite3_column_text(), or</li> <li>sqlite3_column_text16().</li> </ul> This means that you should always call sqlite3_column_bytes() or sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(), sqlite3_column_text(), or sqlite3_column_text16(). </p> <h4>2.3 User-defined functions</h4> <p> User defined functions can be created using the following routine: </p> <blockquote><pre> typedef struct sqlite3_value sqlite3_value; int sqlite3_create_function( sqlite3 *, const char *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); int sqlite3_create_function16( sqlite3*, const void *zFunctionName, int nArg, int eTextRep, void*, void (*xFunc)(sqlite3_context*,int,sqlite3_value**), void (*xStep)(sqlite3_context*,int,sqlite3_value**), void (*xFinal)(sqlite3_context*) ); #define SQLITE_UTF8 1 #define SQLITE_UTF16 2 #define SQLITE_UTF16BE 3 #define SQLITE_UTF16LE 4 #define SQLITE_ANY 5 </pre></blockquote> <p> The nArg parameter specifies the number of arguments to the function. A value of 0 indicates that any number of arguments is allowed. The eTextRep parameter specifies what representation text values are expected to be in for arguments to this function. The value of this parameter should be one of the parameters defined above. SQLite version 3 allows multiple implementations of the same function using different text representations. The database engine chooses the function that minimization the number of text conversions required. </p> <p> Normal functions specify only xFunc and leave xStep and xFinal set to NULL. Aggregate functions specify xStep and xFinal and leave xFunc set to NULL. There is no separate sqlite3_create_aggregate() API. </p> <p> The function name is specified in UTF-8. A separate sqlite3_create_function16() API works the same as sqlite_create_function() except that the function name is specified in UTF-16 host byte order. </p> <p> Notice that the parameters to functions are now pointers to sqlite3_value structures instead of pointers to strings as in SQLite version 2.X. The following routines are used to extract useful information from these "values": </p> <blockquote><pre> const void *sqlite3_value_blob(sqlite3_value*); int sqlite3_value_bytes(sqlite3_value*); int sqlite3_value_bytes16(sqlite3_value*); double sqlite3_value_double(sqlite3_value*); int sqlite3_value_int(sqlite3_value*); long long int sqlite3_value_int64(sqlite3_value*); const unsigned char *sqlite3_value_text(sqlite3_value*); const void *sqlite3_value_text16(sqlite3_value*); int sqlite3_value_type(sqlite3_value*); </pre></blockquote> <p> Function implementations use the following APIs to acquire context and to report results: </p> <blockquote><pre> void *sqlite3_aggregate_context(sqlite3_context*, int nbyte); void *sqlite3_user_data(sqlite3_context*); void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_double(sqlite3_context*, double); void sqlite3_result_error(sqlite3_context*, const char*, int); void sqlite3_result_error16(sqlite3_context*, const void*, int); void sqlite3_result_int(sqlite3_context*, int); void sqlite3_result_int64(sqlite3_context*, long long int); void sqlite3_result_null(sqlite3_context*); void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*)); void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*)); void sqlite3_result_value(sqlite3_context*, sqlite3_value*); void *sqlite3_get_auxdata(sqlite3_context*, int); void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*)); </pre></blockquote> <h4>2.4 User-defined collating sequences</h4> <p> The following routines are used to implement user-defined collating sequences: </p> <blockquote><pre> sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*)); sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*, int(*xCompare)(void*,int,const void*,int,const void*)); sqlite3_collation_needed(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*)); sqlite3_collation_needed16(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*)); </pre></blockquote> <p> The sqlite3_create_collation() function specifies a collating sequence name and a comparison function to implement that collating sequence. The comparison function is only used for comparing text values. The eTextRep parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or SQLITE_ANY to specify which text representation the comparison function works with. Separate comparison functions can exist for the same collating sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations. The sqlite3_create_collation16() works like sqlite3_create_collation() except that the collation name is specified in UTF-16 host byte order instead of in UTF-8. </p> <p> The sqlite3_collation_needed() routine registers a callback which the database engine will invoke if it encounters an unknown collating sequence. The callback can lookup an appropriate comparison function and invoke sqlite_3_create_collation() as needed. The fourth parameter to the callback is the name of the collating sequence in UTF-8. For sqlite3_collation_need16() the callback sends the collating sequence name in UTF-16 host byte order. </p> } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>C/C++ Interface For SQLite Version 3</title> <h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2> <tcl> set in [open sqlite3.h] set title {} set type {} set body {} set code {} set phase 0 set content {} while {![eof $in]} { set line [gets $in] if {$phase==0} { # Looking for the CAPI3REF: keyword if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} { set title $tx set phase 1 } } elseif {$phase==1} { if {[string range $line 0 1]=="**"} { set lx [string trim [string range $line 3 end]] if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} { set type $cx } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} { foreach k $kx { set keyword($k) 1 } } else { append body $lx\n } } elseif {[string range $line 0 1]=="*/"} { set phase 2 } } elseif {$phase==2} { if {$line==""} { set kwlist [lsort [array names keyword]] unset -nocomplain keyword set key $type:$kwlist lappend content [list $key $title $type $kwlist $body $code] set title {} set keywords {} set type {} set body {} set code {} set phase 0 } else { if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} { set type constant set keyword($kx) 1 } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} { set type datatype set keyword($kx) 1 } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} { set type function set keyword($kx) 1 } append code $line\n } } } # Output HTML that displays the given list in N columns # proc output_list {N lx} { puts {<table width="100%" cellpadding="5"><tr>} set len [llength $lx] set n [expr {($len + $N - 1)/$N}] for {set i 0} {$i<$N} {incr i} { set start [expr {$i*$n}] set end [expr {($i+1)*$n}] puts {<td valign="top"><ul>} for {set j $start} {$j<$end} {incr j} { set entry [lindex $lx $j] if {$entry!=""} { foreach {link label} $entry break puts "<li><a href=\"#$link\">$label</a></li>" } } puts {</ul></td>} } puts {</tr></table>} } # Do a table of contents for objects # set objlist {} foreach c $content { foreach {key title type keywords body code} $c break if {$type!="datatype"} continue set keywords [lsort $keywords] set k [lindex $keywords 0] foreach kw $keywords { lappend objlist [list $k $kw] } } puts {<h2>Datatypes:</h2>} output_list 3 $objlist puts {<hr>} # Do a table of contents for constants # set clist {} foreach c $content { foreach {key title type keywords body code} $c break if {$type!="constant"} continue set keywords [lsort $keywords] set k [lindex $keywords 0] foreach kw $keywords { lappend clist [list $k $kw] } } puts {<h2>Constants:</h2>} set clist [lsort -index 1 $clist] output_list 3 $clist puts {<hr>} # Do a table of contents for functions # set funclist {} foreach c $content { foreach {key title type keywords body code} $c break if {$type!="function"} continue set keywords [lsort $keywords] set k [lindex $keywords 0] foreach kw $keywords { lappend funclist [list $k $kw] } } puts {<h2>Functions:</h2>} set funclist [lsort -index 1 $funclist] output_list 3 $funclist puts {<hr>} # Resolve links # proc resolve_links {args} { set tag [lindex $args 0] regsub -all {[^a-zA-Z0-9_]} $tag {} tag set x "<a href=\"#$tag\">" if {[llength $args]>2} { append x [lrange $args 2 end]</a> } else { append x [lindex $args 0]</a> } return $x } # Output all the records # foreach c [lsort $content] { foreach {key title type keywords body code} $c break foreach k $keywords { puts "<a name=\"$k\"></a></a>" } puts "<h2>$title</h2>" puts "<blockquote><pre>" puts "$code" puts "</pre></blockquote>" regsub -all "\n\n+" $body {</p>\1<p>} body regsub -all {\[} <p>$body</p> {[resolve_links } body set body [subst -novar -noback $body] puts "$body" puts "<hr>" } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 | <title>SQLite changes</title> <p> This page provides a high-level summary of changes to SQLite. For more detail, refer the the checkin logs generated by CVS at <a href="http://www.sqlite.org/cvstrac/timeline"> http://www.sqlite.org/cvstrac/timeline</a>. </p> <tcl> proc chng {date desc} { if {[regexp {\(([0-9.]+)\)} $date all vers]} { set label [string map {. _} $vers] puts "<A NAME=\"version_$label\">" } puts "<DT><B>$date</B></DT>" regsub -all {[Tt]icket #(\d+)} $desc \ {<a href="http://www.sqlite.org/cvstrac/tktview?tn=\1">\0</a>} desc puts "<DD><P><UL>$desc</UL></P>" puts "</DD>" } chng {2007 Nov 05 (3.5.2)} { <li>Dropped support for the SQLITE_OMIT_MEMORY_ALLOCATION compile-time option. <li>Always open files using FILE_FLAG_RANDOM_ACCESS under windows. <li>The 3rd parameter of the built-in SUBSTR() function is now optional. <li>Bug fix: do not invoke the authorizer when reparsing the schema after a schema change. <li>Added the experimental malloc-free memory allocator in mem3.c. <li>Virtual machine stores 64-bit integer and floating point constants in binary instead of text for a performance boost. <li>Fix a race condition in test_async.c. <li>Added the ".timer" command to the CLI } chng {2007 Oct 04 (3.5.1)} { <li><i><b>Nota Bene:</b> We are not using terms "alpha" or "beta" on this release because the code is stable and because if we use those terms, nobody will upgrade. However, we still reserve the right to make incompatible changes to the new VFS interface in future releases.</i></li> <li>Fix a bug in the handling of SQLITE_FULL errors that could lead to database corruption. Ticket #2686. <li>The test_async.c drive now does full file locking and works correctly when used simultaneously by multiple processes on the same database. <li>The CLI ignores whitespace (including comments) at the end of lines <li>Make sure the query optimizer checks dependences on all terms of a compound SELECT statement. Ticket #2640. <li>Add demonstration code showing how to build a VFS for a raw mass storage without a filesystem. <li>Added an output buffer size parameter to the xGetTempname() method of the VFS layer. <li>Sticky SQLITE_FULL or SQLITE_IOERR errors in the pager are reset when a new transaction is started. } chng {2007 Sep 04 (3.5.0) alpha} { <li>Redesign the OS interface layer. See <a href="34to35.html">34to35.html</a> for details. <font color="red">*** Potentially incompatible change ***</font> <li>The <a href="capi3ref.html#sqlite3_release_memory"> sqlite3_release_memory()</a>, <a href="capi3ref.html#sqlite3_soft_heap_limit"> sqlite3_soft_heap_limit()</a>, and <a href="capi3ref.html#sqlite3_enable_shared_cache"> sqlite3_enable_shared_cache()</a> interfaces now work cross all threads in the process, not just the single thread in which they are invoked. <font color="red">*** Potentially incompatible change ***</font> <li>Added the <a href="capi3ref.html#sqlite3_open_v2">sqlite3_open_v2()</a> interface. <li>Reimplemented the memory allocation subsystem and made it replacable at compile-time. <li>Created a new mutex subsystem and made it replacable at compile-time. <li>The same database connection may now be used simultaneously by separate threads. } chng {2007 August 13 (3.4.2)} { <li>Fix a database corruption bug that might occur if a ROLLBACK command is executed in <a href="pragma.html#pragma_auto_vacuum">auto-vacuum mode</a> and a very small <a href="capi3ref.html#sqlite3_soft_heap_limit"> soft_heap_limit</a> is set. <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565">Ticket #2565</a>. <li>Add the ability to run a full regression test with a small <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a>. <li>Fix other minor problems with using small soft heap limits. <li>Work-around for <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=32575">GCC bug 32575</a>. <li>Improved error detection of misused aggregate functions. <li>Improvements to the amalgamation generator script so that all symbols are prefixed with either SQLITE_PRIVATE or SQLITE_API. } chng {2007 July 20 (3.4.1)} { <li>Fix a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption"> database corruption</a> if two processes are connected to the database at the same time and one VACUUMs then the other then modifies the database.</li> <li>The expression "+column" is now considered the same as "column" when computing the collating sequence to use on the expression.</li> <li>In the <a href="tclsqlite.html">TCL language interface</a>, "@variable" instead of "$variable" always binds as a blob.</li> <li>Added <a href="pragma.html#pragma_freelist_count">PRAGMA freelist_count</a> for determining the current size of the freelist.</li> <li>The <a href="pragma.html#pragma_auto_vacuum"> PRAGMA auto_vacuum=incremental</a> setting is now persistent.</li> <li>Add FD_CLOEXEC to all open files under unix.</li> <li>Fix a bug in the <a href="optoverview.html#minmax"> min()/max() optimization</a> when applied to descending indices.</li> <li>Make sure the TCL language interface works correctly with 64-bit integers on 64-bit machines.</li> <li>Allow the value -9223372036854775808 as an integer literal in SQL statements.</li> <li>Add the capability of "hidden" columns in virtual tables.</li> <li>Use the macro SQLITE_PRIVATE (defaulting to "static") on all internal functions in the amalgamation.</li> <li>Add pluggable tokenizers and <a href="http://www.icu-project.org/">ICU</a> tokenization support to FTS2</li> <li>Other minor bug fixes and documentation enhancements</li> } chng {2007 June 18 (3.4.0)} { <li>Fix a bug that can lead to database corruption if an SQLITE_BUSY error occurs in the middle of an explicit transaction and that transaction is later committed. <a href="http://www.sqlite.org/cvstrac/tktview?tn=2409">Ticket #2409.</a> See the <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> CorruptionFollowingBusyError</a> wiki page for details.</i> <li>Fix a bug that can lead to database corruption if autovacuum mode is on and a malloc() failure follows a CREATE TABLE or CREATE INDEX statement which itself follows a cache overflow inside a transaction. See <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a>. </li> <li>Added explicit <a href="limits.html">upper bounds</a> on the sizes and quantities of things SQLite can process. This change might cause compatibility problems for applications that use SQLite in the extreme, which is why the current release is 3.4.0 instead of 3.3.18.</li> <li>Added support for <a href="capi3ref.html#sqlite3_blob_open"> Incremental BLOB I/O</a>.</li> <li>Added the <a href="capi3ref.html#sqlite3_bind_zeroblob">zeroblob API</a> and the <a href="lang_expr.html#zeroblob">zeroblob()</a> SQL function.</li> <li>Added support for <a href="pragma.html#pragma_incremental_vacuum"> Incremental Vacuum</a>.</li> <li>Added the SQLITE_MIXED_ENDIAN_64BIT_FLOAT compile-time option to suppport ARM7 processors with goofy endianness.</li> <li>Removed all instances of sprintf() and strcpy() from the core library.</li> <li>Added support for <a href="http://www.icu-project.org/"> International Components for Unicode (ICU)</a> to the full-text search extensions. </ul><p> <ul type="circle"> <li>In the windows OS driver, reacquire a SHARED lock if an attempt to acquire an EXCLUSIVE lock fails. Ticket #2354</li> <li>Fix the REPLACE() function so that it returns NULL if the second argument is an empty string. Ticket #2324.</li> <li>Document the hazards of type coversions in <a href="capi3ref.html#sqlite3_column_blob">sqlite3_column_blob()</a> and related APIs. Fix unnecessary type conversions. Ticket #2321.</li> <li>Internationalization of the TRIM() function. Ticket #2323</li> <li>Use memmove() instead of memcpy() when moving between memory regions that might overlap. Ticket #2334</li> <li>Fix an optimizer bug involving subqueries in a compound SELECT that has both an ORDER BY and a LIMIT clause. Ticket #2339.</li> <li>Make sure the <a href="capi3ref.html#sqlite3_snprintf">sqlite3_snprintf() </a> interface does not zero-terminate the buffer if the buffer size is less than 1. Ticket #2341</li> <li>Fix the built-in printf logic so that it prints "NaN" not "Inf" for floating-point NaNs. Ticket #2345</li> <li>When converting BLOB to TEXT, use the text encoding of the main database. Ticket #2349</li> <li>Keep the full precision of integers (if possible) when casting to NUMERIC. Ticket #2364</li> <li>Fix a bug in the handling of UTF16 codepoint 0xE000</li> <li>Consider explicit collate clauses when matching WHERE constraints to indices in the query optimizer. Ticket #2391</li> <li>Fix the query optimizer to correctly handle constant expressions in the ON clause of a LEFT JOIN. Ticket #2403</li> <li>Fix the query optimizer to handle rowid comparisions to NULL correctly. Ticket #2404</li> <li>Fix many potental segfaults that could be caused by malicious SQL statements.</li> } chng {2007 April 25 (3.3.17)} { <li>When the "write_version" value of the database header is larger than what the library understands, make the database read-only instead of unreadable.</li> <li>Other minor bug fixes</li> } chng {2007 April 18 (3.3.16)} { <li>Fix a bug that caused VACUUM to fail if NULLs appeared in a UNIQUE column.</li> <li>Reinstate performance improvements that were added in 3.3.14 but regressed in 3.3.15.</li> <li>Fix problems with the handling of ORDER BY expressions on compound SELECT statements in subqueries.</li> <li>Fix a potential segfault when destroying locks on WinCE in a multi-threaded environment.</li> <li>Documentation updates.</li> } chng {2007 April 9 (3.3.15)} { <li>Fix a bug introduced in 3.3.14 that caused a rollback of CREATE TEMP TABLE to leave the database connection wedged.</li> <li>Fix a bug that caused an extra NULL row to be returned when a descending query was interrupted by a change to the database.</li> <li>The FOR EACH STATEMENT clause on a trigger now causes a syntax error. It used to be silently ignored.</li> <li>Fix an obscure and relatively harmless problem that might have caused a resource leak following an I/O error.</li> <li>Many improvements to the test suite. Test coverage now exceeded 98%</li> } chng {2007 April 2 (3.3.14)} { <li>Fix a <a href="http://www.sqlite.org/cvstrac/tktview?tn=2273">bug</a> in 3.3.13 that could cause a segfault when the IN operator is used one one term of a two-column index and the right-hand side of the IN operator contains a NULL.</li> <li>Added a new OS interface method for determining the sector size of underlying media: sqlite3OsSectorSize().</li> <li>A new algorithm for statements of the form INSERT INTO <i>table1</i> SELECT * FROM <i>table2</i> is faster and reduces fragmentation. VACUUM uses statements of this form and thus runs faster and defragments better.</li> <li>Performance enhancements through reductions in disk I/O: <ul> <li>Do not read the last page of an overflow chain when deleting the row - just add that page to the freelist.</li> <li>Do not store pages being deleted in the rollback journal.</li> <li>Do not read in the (meaningless) content of pages extracted from the freelist.</li> <li>Do not flush the page cache (and thus avoiding a cache refill) unless another process changes the underlying database file.</li> <li>Truncate rather than delete the rollback journal when committing a transaction in exclusive access mode, or when committing the TEMP database.</li> </ul></li> <li>Added support for exclusive access mode using <a href="pragma.html#pragma_locking_mode"> "PRAGMA locking_mode=EXCLUSIVE"</a></li> <li>Use heap space instead of stack space for large buffers in the pager - useful on embedded platforms with stack-space limitations.</li> <li>Add a makefile target "sqlite3.c" that builds an amalgamation containing the core SQLite library C code in a single file.</li> <li>Get the library working correctly when compiled with GCC option "-fstrict-aliasing".</li> <li>Removed the vestigal SQLITE_PROTOCOL error.</li> <li>Improvements to test coverage, other minor bugs fixed, memory leaks plugged, code refactored and/or recommented in places for easier reading.</li> } chng {2007 February 13 (3.3.13)} { <li>Add a "fragmentation" measurement in the output of sqlite3_analyzer.</li> <li>Add the COLLATE operator used to explicitly set the collating sequence used by an expression. This feature is considered experimental pending additional testing.</li> <li>Allow up to 64 tables in a join - the old limit was 32.</li> <li>Added two new experimental functions: <a href="lang_expr.html#randomblobFunc">randomBlob()</a> and <a href="lang_expr.html#hexFunc">hex()</a>. Their intended use is to facilitate generating <a href="http://en.wikipedia.org/wiki/UUID">UUIDs</a>. </li> <li>Fix a problem where <a href="pragma.html#pragma_count_changes">PRAGMA count_changes</a> was causing incorrect results for updates on tables with triggers</li> <li>Fix a bug in the ORDER BY clause optimizer for joins where the left-most table in the join is constrained by a UNIQUE index.</li> <li>Fixed a bug in the "copy" method of the TCL interface.</li> <li>Bug fixes in fts1 and fts2 modules.</li> } chng {2007 January 27 (3.3.12)} { <li>Fix another bug in the IS NULL optimization that was added in version 3.3.9.</li> <li>Fix a assertion fault that occurred on deeply nested views.</li> <li>Limit the amount of output that <a href="pragma.html#pragma_integrity_check">PRAGMA integrity_check</a> generates.</li> <li>Minor syntactic changes to support a wider variety of compilers.</li> } chng {2007 January 22 (3.3.11)} { <li>Fix another bug in the implementation of the new <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API. We'll get it right eventually...</li> <li>Fix a bug in the IS NULL optimization that was added in version 3.3.9 - the bug was causing incorrect results on certain LEFT JOINs that included in the WHERE clause an IS NULL constraint for the right table of the LEFT JOIN.</li> <li>Make AreFileApisANSI() a no-op macro in winCE since winCE does not support this function.</li> } chng {2007 January 9 (3.3.10)} { <li>Fix bugs in the implementation of the new <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API that can lead to segfaults.</li> <li>Fix 1-second round-off errors in the <a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions"> strftime()</a> function</li> <li>Enhance the windows OS layer to provide detailed error codes</li> <li>Work around a win2k problem so that SQLite can use single-character database file names</li> <li>The <a href="pragma.html#pragma_user_version">user_version</a> and <a href="pragma.html#pragma_schema_version">schema_version</a> pragmas correctly set their column names in the result set</li> <li>Documentation updates</li> } chng {2007 January 4 (3.3.9)} { <li>Fix bugs in pager.c that could lead to database corruption if two processes both try to recover a hot journal at the same instant</li> <li>Added the <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API.</li> <li>Fixed the ".dump" command in the command-line shell to show indices, triggers and views again.</li> <li>Change the table_info pragma so that it returns NULL for the default value if there is no default value</li> <li>Support for non-ASCII characters in win95 filenames</li> <li>Query optimizer enhancements: <ul> <li>Optimizer does a better job of using indices to satisfy ORDER BY clauses that sort on the integer primary key</li> <li>Use an index to satisfy an IS NULL operator in the WHERE clause</li> <li>Fix a bug that was causing the optimizer to miss an OR optimization opportunity</li> <li>The optimizer has more freedom to reorder tables in the FROM clause even in there are LEFT joins.</li> </ul> <li>Extension loading supported added to winCE</li> <li>Allow constraint names on the DEFAULT clause in a table definition</li> <li>Added the ".bail" command to the command-line shell</li> <li>Make CSV (comma separate value) output from the command-line shell more closely aligned to accepted practice</li> <li>Experimental FTS2 module added</li> <li>Use sqlite3_mprintf() instead of strdup() to avoid libc dependencies</li> <li>VACUUM uses a temporary file in the official TEMP folder, not in the same directory as the original database</li> <li>The prefix on temporary filenames on windows is changed from "sqlite" to "etilqs".</li> } chng {2006 October 9 (3.3.8)} { <li>Support for full text search using the <a href="http://www.sqlite.org/cvstrac/wiki?p=FullTextIndex">FTS1 module</a> (beta)</li> <li>Added OS-X locking patches (beta - disabled by default)</li> <li>Introduce extended error codes and add error codes for various kinds of I/O errors.</li> <li>Added support for IF EXISTS on CREATE/DROP TRIGGER/VIEW</li> <li>Fix the regression test suite so that it works with Tcl8.5</li> <li>Enhance sqlite3_set_authorizer() to provide notification of calls to SQL functions.</li> <li>Added experimental API: sqlite3_auto_extension()</li> <li>Various minor bug fixes</li> } chng {2006 August 12 (3.3.7)} { <li>Added support for <a href="http://www.sqlite.org/cvstrac/wiki?p=VirtualTables">virtual tables</a> (beta)</li> <li>Added support for <a href="http://www.sqlite.org/cvstrac/wiki?p=LoadableExtensions"> dynamically loaded extensions</a> (beta)</li> <li>The <a href="capi3ref.html#sqlite3_interrupt">sqlite3_interrupt()</a> routine can be called for a different thread</li> <li>Added the <a href="lang_expr.html#match">MATCH</a> operator.</li> <li>The default file format is now 1. } chng {2006 June 6 (3.3.6)} { <li>Plays better with virus scanners on windows</li> <li>Faster :memory: databases</li> <li>Fix an obscure segfault in UTF-8 to UTF-16 conversions</li> <li>Added driver for OS/2</li> <li>Correct column meta-information returned for aggregate queries</li> <li>Enhanced output from EXPLAIN QUERY PLAN</li> <li>LIMIT 0 now works on subqueries</li> <li>Bug fixes and performance enhancements in the query optimizer</li> <li>Correctly handle NULL filenames in ATTACH and DETACH</li> <li>Inproved syntax error messages in the parser</li> <li>Fix type coercion rules for the IN operator</li> } chng {2006 April 5 (3.3.5)} { <li>CHECK constraints use conflict resolution algorithms correctly.</li> <li>The SUM() function throws an error on integer overflow.</li> <li>Choose the column names in a compound query from the left-most SELECT instead of the right-most.</li> <li>The sqlite3_create_collation() function honors the SQLITE_UTF16_ALIGNED flag.</li> <li>SQLITE_SECURE_DELETE compile-time option causes deletes to overwrite old data with zeros.</li> <li>Detect integer overflow in abs().</li> <li>The random() function provides 64 bits of randomness instead of only 32 bits.</li> <li>Parser detects and reports automaton stack overflow.</li> <li>Change the round() function to return REAL instead of TEXT.</li> <li>Allow WHERE clause terms on the left table of a LEFT OUTER JOIN to contain aggregate subqueries.</li> <li>Skip over leading spaces in text to numeric conversions.</li> <li>Various minor bug and documentation typo fixes and performance enhancements.</li> } chng {2006 February 11 (3.3.4)} { <li>Fix a blunder in the Unix mutex implementation that can lead to deadlock on multithreaded systems.</li> <li>Fix an alignment problem on 64-bit machines</li> <li>Added the fullfsync pragma.</li> <li>Fix an optimizer bug that could have caused some unusual LEFT OUTER JOINs to give incorrect results.</li> <li>The SUM function detects integer overflow and converts to accumulating an approximate result using floating point numbers</li> <li>Host parameter names can begin with '@' for compatibility with SQL Server. </li> <li>Other miscellaneous bug fixes</li> } chng {2006 January 31 (3.3.3)} { <li>Removed support for an ON CONFLICT clause on CREATE INDEX - it never worked correctly so this should not present any backward compatibility problems.</li> <li>Authorizer callback now notified of ALTER TABLE ADD COLUMN commands</li> <li>After any changes to the TEMP database schema, all prepared statements are invalidated and must be recreated using a new call to sqlite3_prepare()</li> <li>Other minor bug fixes in preparation for the first stable release of version 3.3</li> } chng {2006 January 24 (3.3.2 beta)} { <li>Bug fixes and speed improvements. Improved test coverage.</li> <li>Changes to the OS-layer interface: mutexes must now be recursive.</li> <li>Discontinue the use of thread-specific data for out-of-memory exception handling</li> } chng {2006 January 16 (3.3.1 alpha)} { <li>Countless bug fixes</li> <li>Speed improvements</li> <li>Database connections can now be used by multiple threads, not just the thread in which they were created.</li> } chng {2006 January 10 (3.3.0 alpha)} { <li>CHECK constraints</li> <li>IF EXISTS and IF NOT EXISTS clauses on CREATE/DROP TABLE/INDEX.</li> <li>DESC indices</li> <li>More efficient encoding of boolean values resulting in smaller database files</li> <li>More aggressive SQLITE_OMIT_FLOATING_POINT</li> <li>Separate INTEGER and REAL affinity</li> <li>Added a virtual function layer for the OS interface</li> <li>"exists" method added to the TCL interface</li> <li>Improved response to out-of-memory errors</li> <li>Database cache can be optionally shared between connections in the same thread</li> <li>Optional READ UNCOMMITTED isolation (instead of the default isolation level of SERIALIZABLE) and table level locking when database connections share a common cache.</li> } chng {2005 December 19 (3.2.8)} { <li>Fix an obscure bug that can cause database corruption under the following unusual circumstances: A large INSERT or UPDATE statement which is part of an even larger transaction fails due to a uniqueness contraint but the containing transaction commits.</li> } chng {2005 December 19 (2.8.17)} { <li>Fix an obscure bug that can cause database corruption under the following unusual circumstances: A large INSERT or UPDATE statement which is part of an even larger transaction fails due to a uniqueness contraint but the containing transaction commits.</li> } chng {2005 September 24 (3.2.7)} { <li>GROUP BY now considers NULLs to be equal again, as it should </li> <li>Now compiles on Solaris and OpenBSD and other Unix variants that lack the fdatasync() function</li> <li>Now compiles on MSVC++6 again</li> <li>Fix uninitialized variables causing malfunctions for various obscure queries</li> <li>Correctly compute a LEFT OUTER JOINs that is constrained on the left table only</li> } chng {2005 September 17 (3.2.6)} { <li>Fix a bug that can cause database corruption if a VACUUM (or autovacuum) fails and is rolled back on a database that is larger than 1GiB</li> <li>LIKE optiization now works for columns with COLLATE NOCASE</li> <li>ORDER BY and GROUP BY now use bounded memory</li> <li>Added support for COUNT(DISTINCT expr)</li> <li>Change the way SUM() handles NULL values in order to comply with the SQL standard</li> <li>Use fdatasync() instead of fsync() where possible in order to speed up commits slightly</li> <li>Use of the CROSS keyword in a join turns off the table reordering optimization</li> <li>Added the experimental and undocumented EXPLAIN QUERY PLAN capability</li> <li>Use the unicode API in windows</li> } chng {2005 August 27 (3.2.5)} { <li>Fix a bug effecting DELETE and UPDATE statements that changed more than 40960 rows.</li> <li>Change the makefile so that it no longer requires GNUmake extensions</li> <li>Fix the --enable-threadsafe option on the configure script</li> <li>Fix a code generator bug that occurs when the left-hand side of an IN operator is constant and the right-hand side is a SELECT statement</li> <li>The PRAGMA synchronous=off statement now disables syncing of the master journal file in addition to the normal rollback journals</li> } chng {2005 August 24 (3.2.4)} { <li>Fix a bug introduced in the previous release that can cause a segfault while generating code for complex WHERE clauses.</li> <li>Allow floating point literals to begin or end with a decimal point.</li> } chng {2005 August 21 (3.2.3)} { <li>Added support for the CAST operator</li> <li>Tcl interface allows BLOB values to be transferred to user-defined functions</li> <li>Added the "transaction" method to the Tcl interface</li> <li>Allow the DEFAULT value of a column to call functions that have constant operands</li> <li>Added the ANALYZE command for gathering statistics on indices and using those statistics when picking an index in the optimizer</li> <li>Remove the limit (formerly 100) on the number of terms in the WHERE clause</li> <li>The right-hand side of the IN operator can now be a list of expressions instead of just a list of constants</li> <li>Rework the optimizer so that it is able to make better use of indices</li> <li>The order of tables in a join is adjusted automatically to make better use of indices</li> <li>The IN operator is now a candidate for optimization even if the left-hand side is not the left-most term of the index. Multiple IN operators can be used with the same index.</li> <li>WHERE clause expressions using BETWEEN and OR are now candidates for optimization</li> <li>Added the "case_sensitive_like" pragma and the SQLITE_CASE_SENSITIVE_LIKE compile-time option to set its default value to "on".</li> <li>Use indices to help with GLOB expressions and LIKE expressions too when the case_sensitive_like pragma is enabled</li> <li>Added support for grave-accent quoting for compatibility with MySQL</li> <li>Improved test coverage</li> <li>Dozens of minor bug fixes</li> } chng {2005 June 13 (3.2.2)} { <li>Added the sqlite3_db_handle() API</li> <li>Added the sqlite3_get_autocommit() API</li> <li>Added a REGEXP operator to the parser. There is no function to back up this operator in the standard build but users can add their own using sqlite3_create_function()</li> <li>Speed improvements and library footprint reductions.</li> <li>Fix byte alignment problems on 64-bit architectures.</li> <li>Many, many minor bug fixes and documentation updates.</li> } chng {2005 March 29 (3.2.1)} { <li>Fix a memory allocation error in the new ADD COLUMN comment.</li> <li>Documentation updates</li> } chng {2005 March 21 (3.2.0)} { <li>Added support for ALTER TABLE ADD COLUMN.</li> <li>Added support for the "T" separator in ISO-8601 date/time strings.</li> <li>Improved support for Cygwin.</li> <li>Numerous bug fixes and documentation updates.</li> } chng {2005 March 16 (3.1.6)} { <li>Fix a bug that could cause database corruption when inserting record into tables with around 125 columns.</li> <li>sqlite3_step() is now much more likely to invoke the busy handler and less likely to return SQLITE_BUSY.</li> <li>Fix memory leaks that used to occur after a malloc() failure.</li> } chng {2005 March 11 (3.1.5)} { <li>The ioctl on OS-X to control syncing to disk is F_FULLFSYNC, not F_FULLSYNC. The previous release had it wrong.</li> } chng {2005 March 10 (3.1.4)} { <li>Fix a bug in autovacuum that could cause database corruption if a CREATE UNIQUE INDEX fails because of a constraint violation. This problem only occurs if the new autovacuum feature introduced in version 3.1 is turned on.</li> <li>The F_FULLSYNC ioctl (currently only supported on OS-X) is disabled if the synchronous pragma is set to something other than "full".</li> <li>Add additional forward compatibility to the future version 3.2 database file format.</li> <li>Fix a bug in WHERE clauses of the form (rowid<'2')</li> <li>New SQLITE_OMIT_... compile-time options added</li> <li>Updates to the man page</li> <li>Remove the use of strcasecmp() from the shell</li> <li>Windows DLL exports symbols Tclsqlite_Init and Sqlite_Init</li> } chng {2005 February 19 (3.1.3)} { <li>Fix a problem with VACUUM on databases from which tables containing AUTOINCREMENT have been dropped.</li> <li>Add forward compatibility to the future version 3.2 database file format.</li> <li>Documentation updates</li> } chng {2005 February 15 (3.1.2)} { <li>Fix a bug that can lead to database corruption if there are two open connections to the same database and one connection does a VACUUM and the second makes some change to the database.</li> <li>Allow "?" parameters in the LIMIT clause.</li> <li>Fix VACUUM so that it works with AUTOINCREMENT.</li> <li>Fix a race condition in AUTOVACUUM that can lead to corrupt databases</li> <li>Add a numeric version number to the sqlite3.h include file.</li> <li>Other minor bug fixes and performance enhancements.</li> } chng {2005 February 15 (2.8.16)} { <li>Fix a bug that can lead to database corruption if there are two open connections to the same database and one connection does a VACUUM and the second makes some change to the database.</li> <li>Correctly handle quoted names in CREATE INDEX statements.</li> <li>Fix a naming conflict between sqlite.h and sqlite3.h.</li> <li>Avoid excess heap usage when copying expressions.</li> <li>Other minor bug fixes.</li> } chng {2005 February 1 (3.1.1 BETA)} { <li>Automatic caching of prepared statements in the TCL interface</li> <li>ATTACH and DETACH as well as some other operations cause existing prepared statements to expire.</li> <li>Numerious minor bug fixes</li> } chng {2005 January 21 (3.1.0 ALPHA)} { <li>Autovacuum support added</li> <li>CURRENT_TIME, CURRENT_DATE, and CURRENT_TIMESTAMP added</li> <li>Support for the EXISTS clause added.</li> <li>Support for correlated subqueries added.</li> <li>Added the ESCAPE clause on the LIKE operator.</li> <li>Support for ALTER TABLE ... RENAME TABLE ... added</li> <li>AUTOINCREMENT keyword supported on INTEGER PRIMARY KEY</li> <li>Many SQLITE_OMIT_ macros inserts to omit features at compile-time and reduce the library footprint.</li> <li>The REINDEX command was added.</li> <li>The engine no longer consults the main table if it can get all the information it needs from an index.</li> <li>Many nuisance bugs fixed.</li> } chng {2004 October 11 (3.0.8)} { <li>Add support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions.</li> <li>Allow new user-defined functions to be created when there are already one or more precompiled SQL statements.<li> <li>Fix portability problems for Mingw/MSYS.</li> <li>Fix a byte alignment problem on 64-bit Sparc machines.</li> <li>Fix the ".import" command of the shell so that it ignores \r characters at the end of lines.</li> <li>The "csv" mode option in the shell puts strings inside double-quotes.</li> <li>Fix typos in documentation.</li> <li>Convert array constants in the code to have type "const".</li> <li>Numerous code optimizations, specially optimizations designed to make the code footprint smaller.</li> } chng {2004 September 18 (3.0.7)} { <li>The BTree module allocates large buffers using malloc() instead of off of the stack, in order to play better on machines with limited stack space.</li> <li>Fixed naming conflicts so that versions 2.8 and 3.0 can be linked and used together in the same ANSI-C source file.</li> <li>New interface: sqlite3_bind_parameter_index()</li> <li>Add support for wildcard parameters of the form: "?nnn"</li> <li>Fix problems found on 64-bit systems.</li> <li>Removed encode.c file (containing unused routines) from the version 3.0 source tree.</li> <li>The sqlite3_trace() callbacks occur before each statement is executed, not when the statement is compiled.</li> <li>Makefile updates and miscellaneous bug fixes.</li> } chng {2004 September 02 (3.0.6 beta)} { <li>Better detection and handling of corrupt database files.</li> <li>The sqlite3_step() interface returns SQLITE_BUSY if it is unable to commit a change because of a lock</li> <li>Combine the implementations of LIKE and GLOB into a single pattern-matching subroutine.</li> <li>Miscellaneous code size optimizations and bug fixes</li> } chng {2004 August 29 (3.0.5 beta)} { <li>Support for ":AAA" style bind parameter names.</li> <li>Added the new sqlite3_bind_parameter_name() interface.</li> <li>Support for TCL variable names embedded in SQL statements in the TCL bindings.</li> <li>The TCL bindings transfer data without necessarily doing a conversion to a string.</li> <li>The database for TEMP tables is not created until it is needed.</li> <li>Add the ability to specify an alternative temporary file directory using the "sqlite_temp_directory" global variable.</li> <li>A compile-time option (SQLITE_BUSY_RESERVED_LOCK) causes the busy handler to be called when there is contention for a RESERVED lock.</li> <li>Various bug fixes and optimizations</li> } chng {2004 August 8 (3.0.4 beta)} { <li>CREATE TABLE and DROP TABLE now work correctly as prepared statements.</li> <li>Fix a bug in VACUUM and UNIQUE indices.</li> <li>Add the ".import" command to the command-line shell.</li> <li>Fix a bug that could cause index corruption when an attempt to delete rows of a table is blocked by a pending query.</li> <li>Library size optimizations.</li> <li>Other minor bug fixes.</li> } chng {2004 July 22 (2.8.15)} { <li>This is a maintenance release only. Various minor bugs have been fixed and some portability enhancements are added.</li> } chng {2004 July 22 (3.0.3 beta)} { <li>The second beta release for SQLite 3.0.</li> <li>Add support for "PRAGMA page_size" to adjust the page size of the database.</li> <li>Various bug fixes and documentation updates.</li> } chng {2004 June 30 (3.0.2 beta)} { <li>The first beta release for SQLite 3.0.</li> } chng {2004 June 22 (3.0.1 alpha)} { <li><font color="red"><b> *** Alpha Release - Research And Testing Use Only ***</b></font> <li>Lots of bug fixes.</li> } chng {2004 June 18 (3.0.0 alpha)} { <li><font color="red"><b> *** Alpha Release - Research And Testing Use Only ***</b></font> <li>Support for internationalization including UTF-8, UTF-16, and user defined collating sequences.</li> <li>New file format that is 25% to 35% smaller for typical use.</li> <li>Improved concurrency.</li> <li>Atomic commits for ATTACHed databases.</li> <li>Remove cruft from the APIs.</li> <li>BLOB support.</li> <li>64-bit rowids.</li> <li><a href="version3.html">More information</a>. } chng {2004 June 9 (2.8.14)} { <li>Fix the min() and max() optimizer so that it works when the FROM clause consists of a subquery.</li> <li>Ignore extra whitespace at the end of of "." commands in the shell.</li> <li>Bundle sqlite_encode_binary() and sqlite_decode_binary() with the library.</li> <li>The TEMP_STORE and DEFAULT_TEMP_STORE pragmas now work.</li> <li>Code changes to compile cleanly using OpenWatcom.</li> <li>Fix VDBE stack overflow problems with INSTEAD OF triggers and NULLs in IN operators.</li> <li>Add the global variable sqlite_temp_directory which if set defines the directory in which temporary files are stored.</li> <li>sqlite_interrupt() plays well with VACUUM.</li> <li>Other minor bug fixes.</li> } chng {2004 March 8 (2.8.13)} { <li>Refactor parts of the code in order to make the code footprint smaller. The code is now also a little bit faster.</li> <li>sqlite_exec() is now implemented as a wrapper around sqlite_compile() and sqlite_step().</li> <li>The built-in min() and max() functions now honor the difference between NUMERIC and TEXT datatypes. Formerly, min() and max() always assumed their arguments were of type NUMERIC.</li> <li>New HH:MM:SS modifier to the built-in date/time functions.</li> <li>Experimental sqlite_last_statement_changes() API added. Fixed the the last_insert_rowid() function so that it works correctly with triggers.</li> <li>Add functions prototypes for the database encryption API.</li> <li>Fix several nuisance bugs.</li> } chng {2004 February 8 (2.8.12)} { <li>Fix a bug that will might corrupt the rollback journal if a power failure or external program halt occurs in the middle of a COMMIT. The corrupt journal can lead to database corruption when it is rolled back.</li> <li>Reduce the size and increase the speed of various modules, especially the virtual machine.</li> <li>Allow "<expr> IN <table>" as a shorthand for "<expr> IN (SELECT * FROM <table>".</li> <li>Optimizations to the sqlite_mprintf() routine.</li> <li>Make sure the MIN() and MAX() optimizations work within subqueries.</li> } chng {2004 January 14 (2.8.11)} { <li>Fix a bug in how the IN operator handles NULLs in subqueries. The bug was introduced by the previous release.</li> } chng {2004 January 13 (2.8.10)} { <li>Fix a potential database corruption problem on Unix caused by the fact that all posix advisory locks are cleared whenever you close() a file. The work around it to embargo all close() calls while locks are outstanding.</li> <li>Performance enhancements on some corner cases of COUNT(*).</li> <li>Make sure the in-memory backend response sanely if malloc() fails.</li> <li>Allow sqlite_exec() to be called from within user-defined SQL functions.</li> <li>Improved accuracy of floating-point conversions using "long double".</li> <li>Bug fixes in the experimental date/time functions.</li> } chng {2004 January 5 (2.8.9)} { <li>Fix a 32-bit integer overflow problem that could result in corrupt indices in a database if large negative numbers (less than -2147483648) were inserted into a indexed numeric column.</li> <li>Fix a locking problem on multi-threaded Linux implementations.</li> <li>Always use "." instead of "," as the decimal point even if the locale requests ",".</li> <li>Added UTC to localtime conversions to the experimental date/time functions.</li> <li>Bug fixes to date/time functions.</li> } chng {2003 December 17 (2.8.8)} { <li>Fix a critical bug introduced into 2.8.0 which could cause database corruption.</li> <li>Fix a problem with 3-way joins that do not use indices</li> <li>The VACUUM command now works with the non-callback API</li> <li>Improvements to the "PRAGMA integrity_check" command</li> } chng {2003 December 4 (2.8.7)} { <li>Added experimental sqlite_bind() and sqlite_reset() APIs.</li> <li>If the name of the database is an empty string, open a new database in a temporary file that is automatically deleted when the database is closed.</li> <li>Performance enhancements in the lemon-generated parser</li> <li>Experimental date/time functions revised.</li> <li>Disallow temporary indices on permanent tables.</li> <li>Documentation updates and typo fixes</li> <li>Added experimental sqlite_progress_handler() callback API</li> <li>Removed support for the Oracle8 outer join syntax.</li> <li>Allow GLOB and LIKE operators to work as functions.</li> <li>Other minor documentation and makefile changes and bug fixes.</li> } chng {2003 August 21 (2.8.6)} { <li>Moved the CVS repository to www.sqlite.org</li> <li>Update the NULL-handling documentation.</li> <li>Experimental date/time functions added.</li> <li>Bug fix: correctly evaluate a view of a view without segfaulting.</li> <li>Bug fix: prevent database corruption if you dropped a trigger that had the same name as a table.</li> <li>Bug fix: allow a VACUUM (without segfaulting) on an empty database after setting the EMPTY_RESULT_CALLBACKS pragma.</li> <li>Bug fix: if an integer value will not fit in a 32-bit int, store it in a double instead.</li> <li>Bug fix: Make sure the journal file directory entry is committed to disk before writing the database file.</li> } chng {2003 July 22 (2.8.5)} { <li>Make LIMIT work on a compound SELECT statement.</li> <li>LIMIT 0 now shows no rows. Use LIMIT -1 to see all rows.</li> <li>Correctly handle comparisons between an INTEGER PRIMARY KEY and a floating point number.</li> <li>Fix several important bugs in the new ATTACH and DETACH commands.</li> <li>Updated the <a href="nulls.html">NULL-handling document</a>.</li> <li>Allow NULL arguments in sqlite_compile() and sqlite_step().</li> <li>Many minor bug fixes</li> } chng {2003 June 29 (2.8.4)} { <li>Enhanced the "PRAGMA integrity_check" command to verify indices.</li> <li>Added authorization hooks for the new ATTACH and DETACH commands.</li> <li>Many documentation updates</li> <li>Many minor bug fixes</li> } chng {2003 June 4 (2.8.3)} { <li>Fix a problem that will corrupt the indices on a table if you do an INSERT OR REPLACE or an UPDATE OR REPLACE on a table that contains an INTEGER PRIMARY KEY plus one or more indices.</li> <li>Fix a bug in windows locking code so that locks work correctly when simultaneously accessed by Win95 and WinNT systems.</li> <li>Add the ability for INSERT and UPDATE statements to refer to the "rowid" (or "_rowid_" or "oid") columns.</li> <li>Other important bug fixes</li> } chng {2003 May 17 (2.8.2)} { <li>Fix a problem that will corrupt the database file if you drop a table from the main database that has a TEMP index.</li> } chng {2003 May 16 (2.8.1)} { <li>Reactivated the VACUUM command that reclaims unused disk space in a database file.</li> <li>Added the ATTACH and DETACH commands to allow interacting with multiple database files at the same time.</li> <li>Added support for TEMP triggers and indices.</li> <li>Added support for in-memory databases.</li> <li>Removed the experimental sqlite_open_aux_file(). Its function is subsumed in the new ATTACH command.</li> <li>The precedence order for ON CONFLICT clauses was changed so that ON CONFLICT clauses on BEGIN statements have a higher precedence than ON CONFLICT clauses on constraints. <li>Many, many bug fixes and compatibility enhancements.</li> } chng {2003 Feb 16 (2.8.0)} { <li>Modified the journal file format to make it more resistant to corruption that can occur after an OS crash or power failure.</li> <li>Added a new C/C++ API that does not use callback for returning data.</li> } chng {2003 Jan 25 (2.7.6)} { <li>Performance improvements. The library is now much faster.</li> <li>Added the <b>sqlite_set_authorizer()</b> API. Formal documentation has not been written - see the source code comments for instructions on how to use this function.</li> <li>Fix a bug in the GLOB operator that was preventing it from working with upper-case letters.</li> <li>Various minor bug fixes.</li> } chng {2002 Dec 27 (2.7.5)} { <li>Fix an uninitialized variable in pager.c which could (with a probability of about 1 in 4 billion) result in a corrupted database.</li> } chng {2002 Dec 17 (2.7.4)} { <li>Database files can now grow to be up to 2^41 bytes. The old limit was 2^31 bytes.</li> <li>The optimizer will now scan tables in the reverse if doing so will satisfy an ORDER BY ... DESC clause.</li> <li>The full pathname of the database file is now remembered even if a relative path is passed into sqlite_open(). This allows the library to continue operating correctly after a chdir().</li> <li>Speed improvements in the VDBE.</li> <li>Lots of little bug fixes.</li> } chng {2002 Oct 30 (2.7.3)} { <li>Various compiler compatibility fixes.</li> <li>Fix a bug in the "expr IN ()" operator.</li> <li>Accept column names in parentheses.</li> <li>Fix a problem with string memory management in the VDBE</li> <li>Fix a bug in the "table_info" pragma"</li> <li>Export the sqlite_function_type() API function in the Windows DLL</li> <li>Fix locking behavior under windows</li> <li>Fix a bug in LEFT OUTER JOIN</li> } chng {2002 Sep 25 (2.7.2)} { <li>Prevent journal file overflows on huge transactions.</li> <li>Fix a memory leak that occurred when sqlite_open() failed.</li> <li>Honor the ORDER BY and LIMIT clause of a SELECT even if the result set is used for an INSERT.</li> <li>Do not put write locks on the file used to hold TEMP tables.</li> <li>Added documentation on SELECT DISTINCT and on how SQLite handles NULLs.</li> <li>Fix a problem that was causing poor performance when many thousands of SQL statements were executed by a single sqlite_exec() call.</li> } chng {2002 Aug 31 (2.7.1)} { <li>Fix a bug in the ORDER BY logic that was introduced in version 2.7.0</li> <li>C-style comments are now accepted by the tokenizer.</li> <li>INSERT runs a little faster when the source is a SELECT statement.</li> } chng {2002 Aug 25 (2.7.0)} { <li>Make a distinction between numeric and text values when sorting. Text values sort according to memcmp(). Numeric values sort in numeric order.</li> <li>Allow multiple simultaneous readers under windows by simulating the reader/writers locks that are missing from Win95/98/ME.</li> <li>An error is now returned when trying to start a transaction if another transaction is already active.</li> } chng {2002 Aug 12 (2.6.3)} { <li>Add the ability to read both little-endian and big-endian databases. So database created under SunOS or MacOSX can be read and written under Linux or Windows and vice versa.</li> <li>Convert to the new website: http://www.sqlite.org/</li> <li>Allow transactions to span Linux Threads</li> <li>Bug fix in the processing of the ORDER BY clause for GROUP BY queries</li> } chng {2002 Jly 30 (2.6.2)} { <li>Text files read by the COPY command can now have line terminators of LF, CRLF, or CR.</li> <li>SQLITE_BUSY is handled correctly if encountered during database initialization.</li> <li>Fix to UPDATE triggers on TEMP tables.</li> <li>Documentation updates.</li> } chng {2002 Jly 19 (2.6.1)} { <li>Include a static string in the library that responds to the RCS "ident" command and which contains the library version number.</li> <li>Fix an assertion failure that occurred when deleting all rows of a table with the "count_changes" pragma turned on.</li> <li>Better error reporting when problems occur during the automatic 2.5.6 to 2.6.0 database format upgrade.</li> } chng {2002 Jly 17 (2.6.0)} { <li>Change the format of indices to correct a design flaw the originated with version 2.1.0. <font color="red">*** This is an incompatible file format change ***</font> When version 2.6.0 or later of the library attempts to open a database file created by version 2.5.6 or earlier, it will automatically and irreversibly convert the file format. <b>Make backup copies of older database files before opening them with version 2.6.0 of the library.</b> </li> } chng {2002 Jly 7 (2.5.6)} { <li>Fix more problems with rollback. Enhance the test suite to exercise the rollback logic extensively in order to prevent any future problems. </li> } chng {2002 Jly 6 (2.5.5)} { <li>Fix a bug which could cause database corruption during a rollback. This bugs was introduced in version 2.4.0 by the freelist optimization of checking [410].</li> <li>Fix a bug in aggregate functions for VIEWs.</li> <li>Other minor changes and enhancements.</li> } chng {2002 Jly 1 (2.5.4)} { <li>Make the "AS" keyword optional again.</li> <li>The datatype of columns now appear in the 4th argument to the callback.</li> <li>Added the <b>sqlite_open_aux_file()</b> API, though it is still mostly undocumented and untested.</li> <li>Added additional test cases and fixed a few bugs that those test cases found.</li> } chng {2002 Jun 24 (2.5.3)} { <li>Bug fix: Database corruption can occur due to the optimization that was introduced in version 2.4.0 (check-in [410]). The problem should now be fixed. The use of versions 2.4.0 through 2.5.2 is not recommended.</li> } chng {2002 Jun 24 (2.5.2)} { <li>Added the new <b>SQLITE_TEMP_MASTER</b> table which records the schema for temporary tables in the same way that <b>SQLITE_MASTER</b> does for persistent tables.</li> <li>Added an optimization to UNION ALL</li> <li>Fixed a bug in the processing of LEFT OUTER JOIN</li> <li>The LIMIT clause now works on subselects</li> <li>ORDER BY works on subselects</li> <li>There is a new TypeOf() function used to determine if an expression is numeric or text.</li> <li>Autoincrement now works for INSERT from a SELECT.</li> } chng {2002 Jun 19 (2.5.1)} { <li>The query optimizer now attempts to implement the ORDER BY clause using an index. Sorting is still used if not suitable index is available.</li> } chng {2002 Jun 17 (2.5.0)} { <li>Added support for row triggers.</li> <li>Added SQL-92 compliant handling of NULLs.</li> <li>Add support for the full SQL-92 join syntax and LEFT OUTER JOINs.</li> <li>Double-quoted strings interpreted as column names not text literals.</li> <li>Parse (but do not implement) foreign keys.</li> <li>Performance improvements in the parser, pager, and WHERE clause code generator.</li> <li>Make the LIMIT clause work on subqueries. (ORDER BY still does not work, though.)</li> <li>Added the "%Q" expansion to sqlite_*_printf().</li> <li>Bug fixes too numerous to mention (see the change log).</li> } chng {2002 May 09 (2.4.12)} { <li>Added logic to detect when the library API routines are called out of sequence.</li> } chng {2002 May 08 (2.4.11)} { <li>Bug fix: Column names in the result set were not being generated correctly for some (rather complex) VIEWs. This could cause a segfault under certain circumstances.</li> } chng {2002 May 02 (2.4.10)} { <li>Bug fix: Generate correct column headers when a compound SELECT is used as a subquery.</li> <li>Added the sqlite_encode_binary() and sqlite_decode_binary() functions to the source tree. But they are not yet linked into the library.</li> <li>Documentation updates.</li> <li>Export the sqlite_changes() function from windows DLLs.</li> <li>Bug fix: Do not attempt the subquery flattening optimization on queries that lack a FROM clause. To do so causes a segfault.</li> } chng {2002 Apr 21 (2.4.9)} { <li>Fix a bug that was causing the precompiled binary of SQLITE.EXE to report "out of memory" under Windows 98.</li> } chng {2002 Apr 20 (2.4.8)} { <li>Make sure VIEWs are created after their corresponding TABLEs in the output of the <b>.dump</b> command in the shell.</li> <li>Speed improvements: Do not do synchronous updates on TEMP tables.</li> <li>Many improvements and enhancements to the shell.</li> <li>Make the GLOB and LIKE operators functions that can be overridden by a programmer. This allows, for example, the LIKE operator to be changed to be case sensitive.</li> } chng {2002 Apr 06 (2.4.7)} { <li>Add the ability to put TABLE.* in the column list of a SELECT statement.</li> <li>Permit SELECT statements without a FROM clause.</li> <li>Added the <b>last_insert_rowid()</b> SQL function.</li> <li>Do not count rows where the IGNORE conflict resolution occurs in the row count.</li> <li>Make sure functions expressions in the VALUES clause of an INSERT are correct.</li> <li>Added the <b>sqlite_changes()</b> API function to return the number of row that changed in the most recent operation.</li> } chng {2002 Apr 02 (2.4.6)} { <li>Bug fix: Correctly handle terms in the WHERE clause of a join that do not contain a comparison operator.</li> } chng {2002 Apr 01 (2.4.5)} { <li>Bug fix: Correctly handle functions that appear in the WHERE clause of a join.</li> <li>When the PRAGMA vdbe_trace=ON is set, correctly print the P3 operand value when it is a pointer to a structure rather than a pointer to a string.</li> <li>When inserting an explicit NULL into an INTEGER PRIMARY KEY, convert the NULL value into a unique key automatically.</li> } chng {2002 Mar 24 (2.4.4)} { <li>Allow "VIEW" to be a column name</li> <li>Added support for CASE expressions (patch from Dan Kennedy)</li> <li>Added RPMS to the delivery (patches from Doug Henry)</li> <li>Fix typos in the documentation</li> <li>Cut over configuration management to a new CVS repository with its own CVSTrac bug tracking system.</li> } chng {2002 Mar 22 (2.4.3)} { <li>Fix a bug in SELECT that occurs when a compound SELECT is used as a subquery in the FROM of a SELECT.</li> <li>The <b>sqlite_get_table()</b> function now returns an error if you give it two or more SELECTs that return different numbers of columns.</li> } chng {2002 Mar 14 (2.4.2)} { <li>Bug fix: Fix an assertion failure that occurred when ROWID was a column in a SELECT statement on a view.</li> <li>Bug fix: Fix an uninitialized variable in the VDBE that would could an assert failure.</li> <li>Make the os.h header file more robust in detecting when the compile is for windows and when it is for unix.</li> } chng {2002 Mar 13 (2.4.1)} { <li>Using an unnamed subquery in a FROM clause would cause a segfault.</li> <li>The parser now insists on seeing a semicolon or the end of input before executing a statement. This avoids an accidental disaster if the WHERE keyword is misspelled in an UPDATE or DELETE statement.</li> } chng {2002 Mar 10 (2.4.0)} { <li>Change the name of the sanity_check PRAGMA to <b>integrity_check</b> and make it available in all compiles.</li> <li>SELECT min() or max() of an indexed column with no WHERE or GROUP BY clause is handled as a special case which avoids a complete table scan.</li> <li>Automatically generated ROWIDs are now sequential.</li> <li>Do not allow dot-commands of the command-line shell to occur in the middle of a real SQL command.</li> <li>Modifications to the "lemon" parser generator so that the parser tables are 4 times smaller.</li> <li>Added support for user-defined functions implemented in C.</li> <li>Added support for new functions: <b>coalesce()</b>, <b>lower()</b>, <b>upper()</b>, and <b>random()</b> <li>Added support for VIEWs.</li> <li>Added the subquery flattening optimizer.</li> <li>Modified the B-Tree and Pager modules so that disk pages that do not contain real data (free pages) are not journaled and are not written from memory back to the disk when they change. This does not impact database integrity, since the pages contain no real data, but it does make large INSERT operations about 2.5 times faster and large DELETEs about 5 times faster.</li> <li>Made the CACHE_SIZE pragma persistent</li> <li>Added the SYNCHRONOUS pragma</li> <li>Fixed a bug that was causing updates to fail inside of transactions when the database contained a temporary table.</li> } chng {2002 Feb 18 (2.3.3)} { <li>Allow identifiers to be quoted in square brackets, for compatibility with MS-Access.</li> <li>Added support for sub-queries in the FROM clause of a SELECT.</li> <li>More efficient implementation of sqliteFileExists() under Windows. (by Joel Luscy)</li> <li>The VALUES clause of an INSERT can now contain expressions, including scalar SELECT clauses.</li> <li>Added support for CREATE TABLE AS SELECT</li> <li>Bug fix: Creating and dropping a table all within a single transaction was not working.</li> } chng {2002 Feb 14 (2.3.2)} { <li>Bug fix: There was an incorrect assert() in pager.c. The real code was all correct (as far as is known) so everything should work OK if you compile with -DNDEBUG=1. When asserts are not disabled, there could be a fault.</li> } chng {2002 Feb 13 (2.3.1)} { <li>Bug fix: An assertion was failing if "PRAGMA full_column_names=ON;" was set and you did a query that used a rowid, like this: "SELECT rowid, * FROM ...".</li> } chng {2002 Jan 30 (2.3.0)} { <li>Fix a serious bug in the INSERT command which was causing data to go into the wrong columns if the data source was a SELECT and the INSERT clauses specified its columns in some order other than the default.</li> <li>Added the ability to resolve constraint conflicts is ways other than an abort and rollback. See the documentation on the "ON CONFLICT" clause for details.</li> <li>Temporary files are now automatically deleted by the operating system when closed. There are no more dangling temporary files on a program crash. (If the OS crashes, fsck will delete the file after reboot under Unix. I do not know what happens under Windows.)</li> <li>NOT NULL constraints are honored.</li> <li>The COPY command puts NULLs in columns whose data is '\N'.</li> <li>In the COPY command, backslash can now be used to escape a newline.</li> <li>Added the SANITY_CHECK pragma.</li> } chng {2002 Jan 28 (2.2.5)} { <li>Important bug fix: the IN operator was not working if either the left-hand or right-hand side was derived from an INTEGER PRIMARY KEY.</li> <li>Do not escape the backslash '\' character in the output of the <b>sqlite</b> command-line access program.</li> } chng {2002 Jan 22 (2.2.4)} { <li>The label to the right of an AS in the column list of a SELECT can now be used as part of an expression in the WHERE, ORDER BY, GROUP BY, and/or HAVING clauses.</li> <li>Fix a bug in the <b>-separator</b> command-line option to the <b>sqlite</b> command.</li> <li>Fix a problem with the sort order when comparing upper-case strings against characters greater than 'Z' but less than 'a'.</li> <li>Report an error if an ORDER BY or GROUP BY expression is constant.</li> } chng {2002 Jan 16 (2.2.3)} { <li>Fix warning messages in VC++ 7.0. (Patches from nicolas352001)</li> <li>Make the library thread-safe. (The code is there and appears to work but has not been stressed.)</li> <li>Added the new <b>sqlite_last_insert_rowid()</b> API function.</li> } chng {2002 Jan 13 (2.2.2)} { <li>Bug fix: An assertion was failing when a temporary table with an index had the same name as a permanent table created by a separate process.</li> <li>Bug fix: Updates to tables containing an INTEGER PRIMARY KEY and an index could fail.</li> } chng {2002 Jan 9 (2.2.1)} { <li>Bug fix: An attempt to delete a single row of a table with a WHERE clause of "ROWID=x" when no such rowid exists was causing an error.</li> <li>Bug fix: Passing in a NULL as the 3rd parameter to <b>sqlite_open()</b> would sometimes cause a coredump.</li> <li>Bug fix: DROP TABLE followed by a CREATE TABLE with the same name all within a single transaction was causing a coredump.</li> <li>Makefile updates from A. Rottmann</li> } chng {2001 Dec 22 (2.2.0)} { <li>Columns of type INTEGER PRIMARY KEY are actually used as the primary key in underlying B-Tree representation of the table.</li> <li>Several obscure, unrelated bugs were found and fixed while implemented the integer primary key change of the previous bullet.</li> <li>Added the ability to specify "*" as part of a larger column list in the result section of a SELECT statement. For example: <nobr>"<b>SELECT rowid, * FROM table1;</b>"</nobr>.</li> <li>Updates to comments and documentation.</li> } chng {2001 Dec 14 (2.1.7)} { <li>Fix a bug in <b>CREATE TEMPORARY TABLE</b> which was causing the table to be initially allocated in the main database file instead of in the separate temporary file. This bug could cause the library to suffer an assertion failure and it could cause "page leaks" in the main database file. <li>Fix a bug in the b-tree subsystem that could sometimes cause the first row of a table to be repeated during a database scan.</li> } chng {2001 Dec 14 (2.1.6)} { <li>Fix the locking mechanism yet again to prevent <b>sqlite_exec()</b> from returning SQLITE_PROTOCOL unnecessarily. This time the bug was a race condition in the locking code. This change effects both POSIX and Windows users.</li> } chng {2001 Dec 6 (2.1.5)} { <li>Fix for another problem (unrelated to the one fixed in 2.1.4) that sometimes causes <b>sqlite_exec()</b> to return SQLITE_PROTOCOL unnecessarily. This time the bug was in the POSIX locking code and should not effect windows users.</li> } chng {2001 Dec 4 (2.1.4)} { <li>Sometimes <b>sqlite_exec()</b> would return SQLITE_PROTOCOL when it should have returned SQLITE_BUSY.</li> <li>The fix to the previous bug uncovered a deadlock which was also fixed.</li> <li>Add the ability to put a single .command in the second argument of the sqlite shell</li> <li>Updates to the FAQ</li> } chng {2001 Nov 23 (2.1.3)} { <li>Fix the behavior of comparison operators (ex: "<b><</b>", "<b>==</b>", etc.) so that they are consistent with the order of entries in an index.</li> <li>Correct handling of integers in SQL expressions that are larger than what can be represented by the machine integer.</li> } chng {2001 Nov 22 (2.1.2)} { <li>Changes to support 64-bit architectures.</li> <li>Fix a bug in the locking protocol.</li> <li>Fix a bug that could (rarely) cause the database to become unreadable after a DROP TABLE due to corruption to the SQLITE_MASTER table.</li> <li>Change the code so that version 2.1.1 databases that were rendered unreadable by the above bug can be read by this version of the library even though the SQLITE_MASTER table is (slightly) corrupted.</li> } chng {2001 Nov 13 (2.1.1)} { <li>Bug fix: Sometimes arbitrary strings were passed to the callback function when the actual value of a column was NULL.</li> } chng {2001 Nov 12 (2.1.0)} { <li>Change the format of data records so that records up to 16MB in size can be stored.</li> <li>Change the format of indices to allow for better query optimization.</li> <li>Implement the "LIMIT ... OFFSET ..." clause on SELECT statements.</li> } chng {2001 Nov 3 (2.0.8)} { <li>Made selected parameters in API functions <b>const</b>. This should be fully backwards compatible.</li> <li>Documentation updates</li> <li>Simplify the design of the VDBE by restricting the number of sorters and lists to 1. In practice, no more than one sorter and one list was ever used anyhow. </li> } chng {2001 Oct 21 (2.0.7)} { <li>Any UTF-8 character or ISO8859 character can be used as part of an identifier.</li> <li>Patches from Christian Werner to improve ODBC compatibility and to fix a bug in the round() function.</li> <li>Plug some memory leaks that use to occur if malloc() failed. We have been and continue to be memory leak free as long as malloc() works.</li> <li>Changes to some test scripts so that they work on Windows in addition to Unix.</li> } chng {2001 Oct 19 (2.0.6)} { <li>Added the EMPTY_RESULT_CALLBACKS pragma</li> <li>Support for UTF-8 and ISO8859 characters in column and table names.</li> <li>Bug fix: Compute correct table names with the FULL_COLUMN_NAMES pragma is turned on.</li> } chng {2001 Oct 14 (2.0.5)} { <li>Added the COUNT_CHANGES pragma.</li> <li>Changes to the FULL_COLUMN_NAMES pragma to help out the ODBC driver.</li> <li>Bug fix: "SELECT count(*)" was returning NULL for empty tables. Now it returns 0.</li> } chng {2001 Oct 13 (2.0.4)} { <li>Bug fix: an obscure and relatively harmless bug was causing one of the tests to fail when gcc optimizations are turned on. This release fixes the problem.</li> } chng {2001 Oct 13 (2.0.3)} { <li>Bug fix: the <b>sqlite_busy_timeout()</b> function was delaying 1000 times too long before failing.</li> <li>Bug fix: an assertion was failing if the disk holding the database file became full or stopped accepting writes for some other reason. New tests were added to detect similar problems in the future.</li> <li>Added new operators: <b>&</b> (bitwise-and) <b>|</b> (bitwise-or), <b>~</b> (ones-complement), <b><<</b> (shift left), <b>>></b> (shift right).</li> <li>Added new functions: <b>round()</b> and <b>abs()</b>.</li> } chng {2001 Oct 9 (2.0.2)} { <li>Fix two bugs in the locking protocol. (One was masking the other.)</li> <li>Removed some unused "#include <unistd.h>" that were causing problems for VC++.</li> <li>Fixed <b>sqlite.h</b> so that it is usable from C++</li> <li>Added the FULL_COLUMN_NAMES pragma. When set to "ON", the names of columns are reported back as TABLE.COLUMN instead of just COLUMN.</li> <li>Added the TABLE_INFO() and INDEX_INFO() pragmas to help support the ODBC interface.</li> <li>Added support for TEMPORARY tables and indices.</li> } chng {2001 Oct 2 (2.0.1)} { <li>Remove some C++ style comments from btree.c so that it will compile using compilers other than gcc.</li> <li>The ".dump" output from the shell does not work if there are embedded newlines anywhere in the data. This is an old bug that was carried forward from version 1.0. To fix it, the ".dump" output no longer uses the COPY command. It instead generates INSERT statements.</li> <li>Extend the expression syntax to support "expr NOT NULL" (with a space between the "NOT" and the "NULL") in addition to "expr NOTNULL" (with no space).</li> } chng {2001 Sep 28 (2.0.0)} { <li>Automatically build binaries for Linux and Windows and put them on the website.</li> } chng {2001 Sep 28 (2.0-alpha-4)} { <li>Incorporate makefile patches form A. Rottmann to use LIBTOOL</li> } chng {2001 Sep 27 (2.0-alpha-3)} { <li>SQLite now honors the UNIQUE keyword in CREATE UNIQUE INDEX. Primary keys are required to be unique.</li> <li>File format changed back to what it was for alpha-1</li> <li>Fixes to the rollback and locking behavior</li> } chng {2001 Sep 20 (2.0-alpha-2)} { <li>Initial release of version 2.0. The idea of renaming the library to "SQLus" was abandoned in favor of keeping the "SQLite" name and bumping the major version number.</li> <li>The pager and btree subsystems added back. They are now the only available backend.</li> <li>The Dbbe abstraction and the GDBM and memory drivers were removed.</li> <li>Copyright on all code was disclaimed. The library is now in the public domain.</li> } chng {2001 Jul 23 (1.0.32)} { <li>Pager and btree subsystems removed. These will be used in a follow-on SQL server library named "SQLus".</li> <li>Add the ability to use quoted strings as table and column names in expressions.</li> } chng {2001 Apr 14 (1.0.31)} { <li>Pager subsystem added but not yet used.</li> <li>More robust handling of out-of-memory errors.</li> <li>New tests added to the test suite.</li> } chng {2001 Apr 6 (1.0.30)} { <li>Remove the <b>sqlite_encoding</b> TCL variable that was introduced in the previous version.</li> <li>Add options <b>-encoding</b> and <b>-tcl-uses-utf</b> to the <b>sqlite</b> TCL command.</li> <li>Add tests to make sure that tclsqlite was compiled using Tcl header files and libraries that match.</li> } chng {2001 Apr 5 (1.0.29)} { <li>The library now assumes data is stored as UTF-8 if the --enable-utf8 option is given to configure. The default behavior is to assume iso8859-x, as it has always done. This only makes a difference for LIKE and GLOB operators and the LENGTH and SUBSTR functions.</li> <li>If the library is not configured for UTF-8 and the Tcl library is one of the newer ones that uses UTF-8 internally, then a conversion from UTF-8 to iso8859 and back again is done inside the TCL interface.</li> } chng {2001 Apr 4 (1.0.28)} { <li>Added limited support for transactions. At this point, transactions will do table locking on the GDBM backend. There is no support (yet) for rollback or atomic commit.</li> <li>Added special column names ROWID, OID, and _ROWID_ that refer to the unique random integer key associated with every row of every table.</li> <li>Additional tests added to the regression suite to cover the new ROWID feature and the TCL interface bugs mentioned below.</li> <li>Changes to the "lemon" parser generator to help it work better when compiled using MSVC.</li> <li>Bug fixes in the TCL interface identified by Oleg Oleinick.</li> } chng {2001 Mar 20 (1.0.27)} { <li>When doing DELETE and UPDATE, the library used to write the record numbers of records to be deleted or updated into a temporary file. This is changed so that the record numbers are held in memory.</li> <li>The DELETE command without a WHILE clause just removes the database files from the disk, rather than going through and deleting record by record.</li> } chng {2001 Mar 20 (1.0.26)} { <li>A serious bug fixed on Windows. Windows users should upgrade. No impact to Unix.</li> } chng {2001 Mar 15 (1.0.25)} { <li>Modify the test scripts to identify tests that depend on system load and processor speed and to warn the user that a failure of one of those (rare) tests does not necessarily mean the library is malfunctioning. No changes to code. </li> } chng {2001 Mar 14 (1.0.24)} { <li>Fix a bug which was causing the UPDATE command to fail on systems where "malloc(0)" returns NULL. The problem does not appear Windows, Linux, or HPUX but does cause the library to fail on QNX. </li> } chng {2001 Feb 19 (1.0.23)} { <li>An unrelated (and minor) bug from Mark Muranwski fixed. The algorithm for figuring out where to put temporary files for a "memory:" database was not working quite right. </li> } chng {2001 Feb 19 (1.0.22)} { <li>The previous fix was not quite right. This one seems to work better. </li> } chng {2001 Feb 19 (1.0.21)} { <li>The UPDATE statement was not working when the WHERE clause contained some terms that could be satisfied using indices and other terms that could not. Fixed.</li> } chng {2001 Feb 11 (1.0.20)} { <li>Merge development changes into the main trunk. Future work toward using a BTree file structure will use a separate CVS source tree. This CVS tree will continue to support the GDBM version of SQLite only.</li> } chng {2001 Feb 6 (1.0.19)} { <li>Fix a strange (but valid) C declaration that was causing problems for QNX. No logical changes.</li> } chng {2001 Jan 4 (1.0.18)} { <li>Print the offending SQL statement when an error occurs.</li> <li>Do not require commas between constraints in CREATE TABLE statements.</li> <li>Added the "-echo" option to the shell.</li> <li>Changes to comments.</li> } chng {2000 Dec 10 (1.0.17)} { <li>Rewrote <b>sqlite_complete()</b> to make it faster.</li> <li>Minor tweaks to other code to make it run a little faster.</li> <li>Added new tests for <b>sqlite_complete()</b> and for memory leaks.</li> } chng {2000 Dec 4 (1.0.16)} { <li>Documentation updates. Mostly fixing of typos and spelling errors.</li> } chng {2000 Oct 23 (1.0.15)} { <li>Documentation updates</li> <li>Some sanity checking code was removed from the inner loop of vdbe.c to help the library to run a little faster. The code is only removed if you compile with -DNDEBUG.</li> } chng {2000 Oct 19 (1.0.14)} { <li>Added a "memory:" backend driver that stores its database in an in-memory hash table.</li> } chng {2000 Oct 18 (1.0.13)} { <li>Break out the GDBM driver into a separate file in anticipation to added new drivers.</li> <li>Allow the name of a database to be prefixed by the driver type. For now, the only driver type is "gdbm:".</li> } chng {2000 Oct 16 (1.0.12)} { <li>Fixed an off-by-one error that was causing a coredump in the '%q' format directive of the new <b>sqlite_..._printf()</b> routines.</li> <li>Added the <b>sqlite_interrupt()</b> interface.</li> <li>In the shell, <b>sqlite_interrupt()</b> is invoked when the user presses Control-C</li> <li>Fixed some instances where <b>sqlite_exec()</b> was returning the wrong error code.</li> } chng {2000 Oct 11 (1.0.10)} { <li>Added notes on how to compile for Windows95/98.</li> <li>Removed a few variables that were not being used. Etc.</li> } chng {2000 Oct 8 (1.0.9)} { <li>Added the <b>sqlite_..._printf()</b> interface routines.</li> <li>Modified the <b>sqlite</b> shell program to use the new interface routines.</li> <li>Modified the <b>sqlite</b> shell program to print the schema for the built-in SQLITE_MASTER table, if explicitly requested.</li> } chng {2000 Sep 30 (1.0.8)} { <li>Begin writing documentation on the TCL interface.</li> } chng {2000 Sep 29 (Not Released)} { <li>Added the <b>sqlite_get_table()</b> API</li> <li>Updated the documentation for due to the above change.</li> <li>Modified the <b>sqlite</b> shell to make use of the new sqlite_get_table() API in order to print a list of tables in multiple columns, similar to the way "ls" prints filenames.</li> <li>Modified the <b>sqlite</b> shell to print a semicolon at the end of each CREATE statement in the output of the ".schema" command.</li> } chng {2000 Sep 21 (Not Released)} { <li>Change the tclsqlite "eval" method to return a list of results if no callback script is specified.</li> <li>Change tclsqlite.c to use the Tcl_Obj interface</li> <li>Add tclsqlite.c to the libsqlite.a library</li> } chng {2000 Sep 13 (Version 1.0.5)} { <li>Changed the print format for floating point values from "%g" to "%.15g". </li> <li>Changed the comparison function so that numbers in exponential notation (ex: 1.234e+05) sort in numerical order.</li> } chng {2000 Aug 28 (Version 1.0.4)} { <li>Added functions <b>length()</b> and <b>substr()</b>.</li> <li>Fix a bug in the <b>sqlite</b> shell program that was causing a coredump when the output mode was "column" and the first row of data contained a NULL.</li> } chng {2000 Aug 22 (Version 1.0.3)} { <li>In the sqlite shell, print the "Database opened READ ONLY" message to stderr instead of stdout.</li> <li>In the sqlite shell, now print the version number on initial startup.</li> <li>Add the <b>sqlite_version[]</b> string constant to the library</li> <li>Makefile updates</li> <li>Bug fix: incorrect VDBE code was being generated for the following circumstance: a query on an indexed table containing a WHERE clause with an IN operator that had a subquery on its right-hand side.</li> } chng {2000 Aug 18 (Version 1.0.1)} { <li>Fix a bug in the configure script.</li> <li>Minor revisions to the website.</li> } chng {2000 Aug 17 (Version 1.0)} { <li>Change the <b>sqlite</b> program so that it can read databases for which it lacks write permission. (It used to refuse all access if it could not write.)</li> } chng {2000 Aug 9} { <li>Treat carriage returns as white space.</li> } chng {2000 Aug 8} { <li>Added pattern matching to the ".table" command in the "sqlite" command shell.</li> } chng {2000 Aug 4} { <li>Documentation updates</li> <li>Added "busy" and "timeout" methods to the Tcl interface</li> } chng {2000 Aug 3} { <li>File format version number was being stored in sqlite_master.tcl multiple times. This was harmless, but unnecessary. It is now fixed.</li> } chng {2000 Aug 2} { <li>The file format for indices was changed slightly in order to work around an inefficiency that can sometimes come up with GDBM when there are large indices having many entries with the same key. <font color="red">** Incompatible Change **</font></li> } chng {2000 Aug 1} { <li>The parser's stack was overflowing on a very long UPDATE statement. This is now fixed.</li> } chng {2000 July 31} { <li>Finish the <a href="vdbe.html">VDBE tutorial</a>.</li> <li>Added documentation on compiling to WindowsNT.</li> <li>Fix a configuration program for WindowsNT.</li> <li>Fix a configuration problem for HPUX.</li> } chng {2000 July 29} { <li>Better labels on column names of the result.</li> } chng {2000 July 28} { <li>Added the <b>sqlite_busy_handler()</b> and <b>sqlite_busy_timeout()</b> interface.</li> } chng {2000 June 23} { <li>Begin writing the <a href="vdbe.html">VDBE tutorial</a>.</li> } chng {2000 June 21} { <li>Clean up comments and variable names. Changes to documentation. No functional changes to the code.</li> } chng {2000 June 19} { <li>Column names in UPDATE statements were case sensitive. This mistake has now been fixed.</li> } chng {2000 June 16} { <li>Added the concatenate string operator (||)</li> } chng {2000 June 12} { <li>Added the fcnt() function to the SQL interpreter. The fcnt() function returns the number of database "Fetch" operations that have occurred. This function is designed for use in test scripts to verify that queries are efficient and appropriately optimized. Fcnt() has no other useful purpose, as far as I know.</li> <li>Added a bunch more tests that take advantage of the new fcnt() function. The new tests did not uncover any new problems.</li> } chng {2000 June 8} { <li>Added lots of new test cases</li> <li>Fix a few bugs discovered while adding test cases</li> <li>Begin adding lots of new documentation</li> } chng {2000 June 6} { <li>Added compound select operators: <B>UNION</b>, <b>UNION ALL</B>, <b>INTERSECT</b>, and <b>EXCEPT</b></li> <li>Added support for using <b>(SELECT ...)</b> within expressions</li> <li>Added support for <b>IN</b> and <b>BETWEEN</b> operators</li> <li>Added support for <b>GROUP BY</b> and <b>HAVING</b></li> <li>NULL values are now reported to the callback as a NULL pointer rather than an empty string.</li> } chng {2000 June 3} { <li>Added support for default values on columns of a table.</li> <li>Improved test coverage. Fixed a few obscure bugs found by the improved tests.</li> } chng {2000 June 2} { <li>All database files to be modified by an UPDATE, INSERT or DELETE are now locked before any changes are made to any files. This makes it safe (I think) to access the same database simultaneously from multiple processes.</li> <li>The code appears stable so we are now calling it "beta".</li> } chng {2000 June 1} { <li>Better support for file locking so that two or more processes (or threads) can access the same database simultaneously. More work needed in this area, though.</li> } chng {2000 May 31} { <li>Added support for aggregate functions (Ex: <b>COUNT(*)</b>, <b>MIN(...)</b>) to the SELECT statement.</li> <li>Added support for <B>SELECT DISTINCT ...</B></li> } chng {2000 May 30} { <li>Added the <b>LIKE</b> operator.</li> <li>Added a <b>GLOB</b> operator: similar to <B>LIKE</B> but it uses Unix shell globbing wildcards instead of the '%' and '_' wildcards of SQL.</li> <li>Added the <B>COPY</b> command patterned after <a href="http://www.postgresql.org/">PostgreSQL</a> so that SQLite can now read the output of the <b>pg_dump</b> database dump utility of PostgreSQL.</li> <li>Added a <B>VACUUM</B> command that that calls the <b>gdbm_reorganize()</b> function on the underlying database files.</li> <li>And many, many bug fixes...</li> } chng {2000 May 29} { <li>Initial Public Release of Alpha code</li> } puts { </DL> } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | <title>Well-Known Users Of SQLite</title> <h2>Well-Known Users of SQLite:</h2> <p> There are many companies using SQLite in their products. Exactly how many is unknown. SQLite is in the public domain and so many companies use it in their products without ever telling us. But here are a few examples of well-known companies and/or software projects which we do know are using SQLite: </p> <table border="0" cellpadding="15"> <tr><td valign="top"><img src="foreignlogos/adobe.gif"></td> <td valign="top"> Adobe uses SQLite as the application file format for their Lightroom product. This is publically acknowledged on the Lightroom/About_Lightroom menu popup. Adobe has also announced that their AIR project will include SQLite. It is reported that Acrobat Reader also uses SQLite. </td></tr> <tr><td valign="top"><img src="foreignlogos/apple.gif"></td> <td valign="top"> Apple SQLite for many functions within Mac OS-X, including Apple Mail, Safari, and in Aperture. </td></tr> <tr><td valign="top"><img src="foreignlogos/firefox.gif"></td> <td> The Firefox Web Browser from Mozilla has recently been updated to use SQLite to store all kinds of history information. SQLite is replacing Mork. </td></tr> <tr><td valign="top"><img src="foreignlogos/ge.gif"></td> <td> We believe that General Electric uses SQLite in some product or another because they twice wrote the to SQLite developers requesting the US Export Control Number for SQLite. So presumably GE is using SQLite in something that they are exporting. But nobody (outside of GE) seems to know what that might be. </td> <tr><td valign="top"><img src="foreignlogos/google.gif"></td> <td> Google use SQLite in their Desktop for Mac and in, Google Gears. The Google Gears project allows web applications to work offline, and uses SQLite for the offline data storage. </td> <tr><td valign="top"><img src="foreignlogos/mcaffee.gif"></td> <td> McAfee appears to use SQLite in its antivirus programs. Mentioned here and implied here </td> <tr><td valign="top"><img src="foreignlogos/microsoft.gif"></td> <td> It can inferred from traffic on the SQLite mailing list that at least one group within Microsoft is using SQLite in the development of a game program. No word yet if this game has actually been released or if they are still using SQLite. </td> <tr><td valign="top"><img src="foreignlogos/monotone.gif"></td> <td> The Monotone configuration management system stores an entire project history in an SQLite database. Each file is a separate BLOB. </td> <tr><td valign="top"><img src="foreignlogos/philips.gif"></td> <td> It is reported that Philips MP3 Players use SQLite to store metadata about the music they hold. Apparently, if you plug a Philips MP3 player into your USB port, you can see the SQLite database file there in plain sight. </td> <tr><td valign="top"><img src="foreignlogos/php.gif"></td> <td> The popular PHP programming language comes with both SQLite2 and SQLite3 built in. </td></t> <tr><td valign="top"><img src="foreignlogos/python.gif"></td> <td> SQLite comes bundled with the Python programming langauge since Python 2.5. </td></tr> <tr><td valign="top"><img src="foreignlogos/realbasic.gif"></td> <td> The REALbasic programming environment comes bundled with an enhanced version of SQLite that supports AES encryption. </td></tr> <tr><td valign="top"><img src="foreignlogos/skype.gif"></td> <td> There are multiple sightings of SQLite in the Skype client for MacOSX and Windows. </td></tr> <tr><td valign="top"><img src="foreignlogos/sunmicro.gif"></td> <td> Solaris 10 uses SQLite as the storage format for its Service Management Facility. Thus, Sun as essentially replaced the traditional unix /etc/inittab file with an SQLite database. </td></tr> <tr><td valign="top"><img src="foreignlogos/symbian.gif"></td> <td> SQLite is an integral part of Symbian's operating system commonly found on high-end cellphones. </td></tr> <tr><td valign="top"><img src="foreignlogos/toshiba.gif"></td> <td> A representative of Toshiba wrote to the SQLite developers and requested the US Export Control Number for SQLite. We infer from this that Toshiba is exporting something from the US that uses SQLite, but we do not know what that something is. </td></tr> </table> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 | <title>Compilation Options For SQLite</title> <h1>Compilation Options For SQLite</h1> <p> For most purposes, SQLite can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to <a href="#omitfeatures">omit SQLite features</a> (resulting in a smaller compiled library size) or to change the <a href="#defaults">default values</a> of some parameters. </p> <p> Every effort has been made to ensure that the various combinations of compilation options work harmoniously and produce a working library. Nevertheless, it is strongly recommended that the SQLite test-suite be executed to check for errors before using an SQLite library built with non-standard compilation options. </p> <a name="defaults"></a> <h2>Options To Set Default Parameter Values</h2> <p><b>SQLITE_DEFAULT_AUTOVACUUM=<i><1 or 0></i></b><br> This macro determines if SQLite creates databases with the <a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a> flag set by default. The default value is 0 (do not create auto-vacuum databases). In any case the compile-time default may be overridden by the "PRAGMA auto_vacuum" command. </p> <p><b>SQLITE_DEFAULT_CACHE_SIZE=<i><pages></i></b><br> This macro sets the default size of the page-cache for each attached database, in pages. This can be overridden by the "PRAGMA cache_size" comamnd. The default value is 2000. </p> <p><b>SQLITE_DEFAULT_PAGE_SIZE=<i><bytes></i></b><br> This macro is used to set the default page-size used when a database is created. The value assigned must be a power of 2. The default value is 1024. The compile-time default may be overridden at runtime by the "PRAGMA page_size" command. </p> <p><b>SQLITE_DEFAULT_TEMP_CACHE_SIZE=<i><pages></i></b><br> This macro sets the default size of the page-cache for temporary files created by SQLite to store intermediate results, in pages. It does not affect the page-cache for the temp database, where tables created using "CREATE TEMP TABLE" are stored. The default value is 500. </p> <p><b>SQLITE_MAX_PAGE_SIZE=<i><bytes></i></b><br> This is used to set the maximum allowable page-size that can be specified by the "PRAGMA page_size" command. The default value is 8192. </p> <a name="omitfeatures"></a> <h2>Options To Omit Features</h2> <p>The following options are used to reduce the size of the compiled library by omiting optional features. This is probably only useful in embedded systems where space is especially tight, as even with all features included the SQLite library is relatively small. Don't forget to tell your compiler to optimize for binary size! (the -Os option if using GCC).</p> <p>The macros in this section do not require values. The following compilation switches all have the same effect:<br> -DSQLITE_OMIT_ALTERTABLE<br> -DSQLITE_OMIT_ALTERTABLE=1<br> -DSQLITE_OMIT_ALTERTABLE=0 </p> <p>If any of these options are defined, then the same set of SQLITE_OMIT_XXX options must also be defined when using the 'lemon' tool to generate a parse.c file. Because of this, these options may only used when the library is built from source, not from the collection of pre-packaged C files provided for non-UNIX like platforms on the website. </p> <p><b>SQLITE_OMIT_ALTERTABLE</b><br> When this option is defined, the <a href="lang_altertable.html">ALTER TABLE</a> command is not included in the library. Executing an ALTER TABLE statement causes a parse error. </p> <p><b>SQLITE_OMIT_AUTHORIZATION</b><br> Defining this option omits the authorization callback feature from the library. The <a href="capi3ref.html#sqlite3_set_authorizer"> sqlite3_set_authorizer()</a> API function is not present in the library. </p> <p><b>SQLITE_OMIT_AUTOVACUUM</b><br> If this option is defined, the library cannot create or write to databases that support <a href="pragma.html#pragma_auto_vacuum">auto-vacuum</a>. Executing a "PRAGMA auto_vacuum" statement is not an error, but does not return a value or modify the auto-vacuum flag in the database file. If a database that supports auto-vacuum is opened by a library compiled with this option, it is automatically opened in read-only mode. </p> <p><b>SQLITE_OMIT_AUTOINCREMENT</b><br> This option is used to omit the AUTOINCREMENT functionality. When this is macro is defined, columns declared as "INTEGER PRIMARY KEY AUTOINCREMENT" behave in the same way as columns declared as "INTEGER PRIMARY KEY" when a NULL is inserted. The sqlite_sequence system table is neither created, nor respected if it already exists. </p> <p><i>TODO: Need a link here - AUTOINCREMENT is not yet documented</i><p> <p><b>SQLITE_OMIT_BLOB_LITERAL</b><br> When this option is defined, it is not possible to specify a blob in an SQL statement using the X'ABCD' syntax.</p> } #<p>WARNING: The VACUUM command depends on this syntax for vacuuming databases #that contain blobs, so disabling this functionality may render a database #unvacuumable. #</p> #<p><i>TODO: Need a link here - is that syntax documented anywhere?</i><p> puts { <p><b>SQLITE_OMIT_COMPLETE</b><br> This option causes the <a href="capi3ref.html#sqlite3_complete"> sqlite3_complete</a> API to be omitted. </p> <p><b>SQLITE_OMIT_COMPOUND_SELECT</b><br> This option is used to omit the compound SELECT functionality. <a href="lang_select.html">SELECT statements</a> that use the UNION, UNION ALL, INTERSECT or EXCEPT compound SELECT operators will cause a parse error. </p> <p><b>SQLITE_OMIT_CONFLICT_CLAUSE</b><br> In the future, this option will be used to omit the <a href="lang_conflict.html">ON CONFLICT</a> clause from the library. </p> <p><b>SQLITE_OMIT_DATETIME_FUNCS</b><br> If this option is defined, SQLite's built-in date and time manipulation functions are omitted. Specifically, the SQL functions julianday(), date(), time(), datetime() and strftime() are not available. The default column values CURRENT_TIME, CURRENT_DATE and CURRENT_DATETIME are still available. </p> <p><b>SQLITE_OMIT_EXPLAIN</b><br> Defining this option causes the EXPLAIN command to be omitted from the library. Attempting to execute an EXPLAIN statement will cause a parse error. </p> <p><b>SQLITE_OMIT_FLOATING_POINT</b><br> This option is used to omit floating-point number support from the SQLite library. When specified, specifying a floating point number as a literal (i.e. "1.01") results in a parse error. </p> <p>In the future, this option may also disable other floating point functionality, for example the sqlite3_result_double(), sqlite3_bind_double(), sqlite3_value_double() and sqlite3_column_double() API functions. </p> <p><b>SQLITE_OMIT_FOREIGN_KEY</b><br> If this option is defined, FOREIGN KEY clauses in column declarations are ignored. </p> <p><b>SQLITE_OMIT_INTEGRITY_CHECK</b><br> This option may be used to omit the <a href="pragma.html#pragma_integrity_check">"PRAGMA integrity_check"</a> command from the compiled library. </p> <p><b>SQLITE_OMIT_MEMORYDB</b><br> 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(), a file with this name will be opened or created. </p> <p><b>SQLITE_OMIT_PAGER_PRAGMAS</b><br> Defining this option omits pragmas related to the pager subsystem from the build. Currently, the <a href="pragma.html#pragma_default_cache_size">default_cache_size</a> and <a href="pragma.html#pragma_cache_size">cache_size</a> pragmas are omitted. </p> <p><b>SQLITE_OMIT_PRAGMA</b><br> This option is used to omit the <a href="pragma.html">PRAGMA command</a> from the library. Note that it is useful to define the macros that omit specific pragmas in addition to this, as they may also remove supporting code in other sub-systems. This macro removes the PRAGMA command only. </p> <p><b>SQLITE_OMIT_PROGRESS_CALLBACK</b><br> This option may be defined to omit the capability to issue "progress" callbacks during long-running SQL statements. The <a href="capi3ref.html#sqlite3_progress_handler">sqlite3_progress_handler()</a> API function is not present in the library. <p><b>SQLITE_OMIT_REINDEX</b><br> When this option is defined, the <a href="lang_reindex.html">REINDEX</a> command is not included in the library. Executing a REINDEX statement causes a parse error. </p> <p><b>SQLITE_OMIT_SCHEMA_PRAGMAS</b><br> Defining this option omits pragmas for querying the database schema from the build. Currently, the <a href="pragma.html#pragma_table_info">table_info</a>, <a href="pragma.html#pragma_index_info">index_info</a>, <a href="pragma.html#pragma_index_list">index_list</a> and <a href="pragma.html#pragma_database_list">database_list</a> pragmas are omitted. </p> <p><b>SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS</b><br> Defining this option omits pragmas for querying and modifying the database schema version and user version from the build. Specifically, the <a href="pragma.html#pragma_schema_version">schema_version</a> and <a href="pragma.html#pragma_user_version">user_version</a> pragmas are omitted. <p><b>SQLITE_OMIT_SUBQUERY</b><br> <p>If defined, support for sub-selects and the IN() operator are omitted. </p> <p><b>SQLITE_OMIT_TCL_VARIABLE</b><br> <p>If this macro is defined, then the special "$<variable-name>" syntax used to automatically bind SQL variables to TCL variables is omitted. </p> <p><b>SQLITE_OMIT_TRIGGER</b><br> Defining this option omits support for VIEW objects. Neither the <a href="lang_createtrigger.html">CREATE TRIGGER</a> or <a href="lang_droptrigger.html">DROP TRIGGER</a> commands are available in this case, attempting to execute either will result in a parse error. </p> <p> WARNING: If this macro is defined, it will not be possible to open a database for which the schema contains TRIGGER objects. </p> <p><b>SQLITE_OMIT_UTF16</b><br> This macro is used to omit support for UTF16 text encoding. When this is defined all API functions that return or accept UTF16 encoded text are unavailable. These functions can be identified by the fact that they end with '16', for example sqlite3_prepare16(), sqlite3_column_text16() and sqlite3_bind_text16(). </p> <p><b>SQLITE_OMIT_VACUUM</b><br> When this option is defined, the <a href="lang_vacuum.html">VACUUM</a> command is not included in the library. Executing a VACUUM statement causes a parse error. </p> <p><b>SQLITE_OMIT_VIEW</b><br> Defining this option omits support for VIEW objects. Neither the <a href="lang_createview.html">CREATE VIEW</a> or <a href="lang_dropview.html">DROP VIEW</a> commands are available in this case, attempting to execute either will result in a parse error. </p> <p> WARNING: If this macro is defined, it will not be possible to open a database for which the schema contains VIEW objects. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 | <title>Constraint Conflict Resolution in SQLite</title> <h1>Constraint Conflict Resolution in SQLite</h1> <p> In most SQL databases, if you have a UNIQUE constraint on a table and you try to do an UPDATE or INSERT that violates the constraint, the database will abort the operation in progress, back out any prior changes associated with UPDATE or INSERT command, and return an error. This is the default behavior of SQLite. Beginning with version 2.3.0, though, SQLite allows you to define alternative ways for dealing with constraint violations. This article describes those alternatives and how to use them. </p> <h2>Conflict Resolution Algorithms</h2> <p> SQLite defines five constraint conflict resolution algorithms as follows: </p> <dl> <dt><b>ROLLBACK</b></dt> <dd><p>When a constraint violation occurs, an immediate ROLLBACK occurs, thus ending the current transaction, and the command aborts with a return code of SQLITE_CONSTRAINT. If no transaction is active (other than the implied transaction that is created on every command) then this algorithm works the same as ABORT.</p></dd> <dt><b>ABORT</b></dt> <dd><p>When a constraint violation occurs, the command backs out any prior changes it might have made and aborts with a return code of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes from prior commands within the same transaction are preserved. This is the default behavior for SQLite.</p></dd> <dt><b>FAIL</b></dt> <dd><p>When a constraint violation occurs, the command aborts with a return code SQLITE_CONSTRAINT. But any changes to the database that the command made prior to encountering the constraint violation are preserved and are not backed out. For example, if an UPDATE statement encountered a constraint violation on the 100th row that it attempts to update, then the first 99 row changes are preserved by change to rows 100 and beyond never occur.</p></dd> <dt><b>IGNORE</b></dt> <dd><p>When a constraint violation occurs, the one row that contains the constraint violation is not inserted or changed. But the command continues executing normally. Other rows before and after the row that contained the constraint violation continue to be inserted or updated normally. No error is returned.</p></dd> <dt><b>REPLACE</b></dt> <dd><p>When a UNIQUE constraint violation occurs, the pre-existing row that caused the constraint violation is removed prior to inserting or updating the current row. Thus the insert or update always occurs. The command continues executing normally. No error is returned.</p></dd> </dl> <h2>Why So Many Choices?</h2> <p>SQLite provides multiple conflict resolution algorithms for a couple of reasons. First, SQLite tries to be roughly compatible with as many other SQL databases as possible, but different SQL database engines exhibit different conflict resolution strategies. For example, PostgreSQL always uses ROLLBACK, Oracle always uses ABORT, and MySQL usually uses FAIL but can be instructed to use IGNORE or REPLACE. By supporting all five alternatives, SQLite provides maximum portability.</p> <p>Another reason for supporting multiple algorithms is that sometimes it is useful to use an algorithm other than the default. Suppose, for example, you are inserting 1000 records into a database, all within a single transaction, but one of those records is malformed and causes a constraint error. Under PostgreSQL or Oracle, none of the 1000 records would get inserted. In MySQL, some subset of the records that appeared before the malformed record would be inserted but the rest would not. Neither behavior is especially helpful. What you really want is to use the IGNORE algorithm to insert all but the malformed record.</p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | <title>SQLite Copyright</title> <h2>SQLite Copyright</h2> <table align="right" vspace="0" hspace="10" border="1" cellpadding="20"> <tr><td align="center"> <img src="images/nocopy.gif"><br> SQLite is in the<br> <a href="http://en.wikipedia.org/wiki/Public_Domain">Public Domain</a> </td></tr> </table> <p> All of the deliverable code in SQLite has been dedicated to the <a href="http://en.wikipedia.org/wiki/Public_Domain">public domain</a> by the authors. All code authors, and representatives of the companies they work for, have signed affidavits dedicating their contributions to the public domain and originals of those signed affidavits are stored in a firesafe at the main offices of <a href="http://www.hwaci.com">Hwaci</a>. Anyone is free to copy, modify, publish, use, compile, sell, or distribute the original SQLite code, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means. </p> <p> The previous paragraph applies to the deliverable code in SQLite - those parts of the SQLite library that you actually bundle and ship with a larger application. Portions of the documentation and some code used as part of the build process might fall under other licenses. The details here are unclear. We do not worry about the licensing of the documentation and build code so much because none of these things are part of the core deliverable SQLite library. </p> <p> All of the deliverable code in SQLite has been written from scratch. No code has been taken from other projects or from the open internet. Every line of code can be traced back to its original author, and all of those authors have public domain dedications on file. So the SQLite code base is clean and is uncontaminated with licensed code from other projects. </p> <h2>Obtaining An Explicit License To Use SQLite</h2> <p> Even though SQLite is in the public domain and does not require a license, some users want to obtain a license anyway. Some reasons for obtaining a license include: </p> <ul> <li> You are using SQLite in a jurisdiction that does not recognize the public domain. </li> <li> You are using SQLite in a jurisdiction that does not recognize the right of an author to dedicate their work to the public domain. </li> <li> You want to hold a tangible legal document as evidence that you have the legal right to use and distribute SQLite. </li> <li> Your legal department tells you that you have to purchase a license. </li> </ul> <p> If you feel like you really have to purchase a license for SQLite, <a href="http://www.hwaci.com/">Hwaci</a>, the company that employs the architect and principal developers of SQLite, will sell you one. Please contact: </p> <blockquote> D. Richard Hipp <br /> Hwaci - Applied Software Research <br /> 704.948.4565 <br /> <a href="mailto:drh@hwaci.com">drh@hwaci.com</a> </blockquote> <h2>Contributed Code</h2> <p> In order to keep SQLite completely free and unencumbered by copyright, all new contributors to the SQLite code base are asked to dedicate their contributions to the public domain. If you want to send a patch or enhancement for possible inclusion in the SQLite source tree, please accompany the patch with the following statement: </p> <blockquote><i> The author or authors of this code dedicate any and all copyright interest in this code to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this code under copyright law. </i></blockquote> <p> We are not able to accept patches or changes to SQLite that are not accompanied by a statement such as the above. In addition, if you make changes or enhancements as an employee, then a simple statement such as the above is insufficient. You must also send by surface mail a copyright release signed by a company officer. A signed original of the copyright release should be mailed to:</p> <blockquote> Hwaci<br> 6200 Maple Cove Lane<br> Charlotte, NC 28269<br> USA </blockquote> <p> A template copyright release is available in <a href="copyright-release.pdf">PDF</a> or <a href="copyright-release.html">HTML</a>. You can use this release to make future changes. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | <title>Datatypes In SQLite Version 3</title> <h2>Datatypes In SQLite Version 3</h2> <h3>1. Storage Classes</h3> <P>Version 2 of SQLite stores all column values as ASCII text. Version 3 enhances this by providing the ability to store integer and real numbers in a more compact format and the capability to store BLOB data.</P> <P>Each value stored in an SQLite database (or manipulated by the database engine) has one of the following storage classes:</P> <UL> <LI><P><B>NULL</B>. The value is a NULL value.</P> <LI><P><B>INTEGER</B>. The value is a signed integer, stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value.</P> <LI><P><B>REAL</B>. The value is a floating point value, stored as an 8-byte IEEE floating point number.</P> <LI><P><B>TEXT</B>. The value is a text string, stored using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).</P> <LI><P><B>BLOB</B>. The value is a blob of data, stored exactly as it was input.</P> </UL> <P>As in SQLite version 2, any column in a version 3 database except an INTEGER PRIMARY KEY may be used to store any type of value. The exception to this rule is described below under 'Strict Affinity Mode'.</P> <P>All values supplied to SQLite, whether as literals embedded in SQL statements or values bound to pre-compiled SQL statements are assigned a storage class before the SQL statement is executed. Under circumstances described below, the database engine may convert values between numeric storage classes (INTEGER and REAL) and TEXT during query execution. </P> <P>Storage classes are initially assigned as follows:</P> <UL> <LI><P>Values specified as literals as part of SQL statements are assigned storage class TEXT if they are enclosed by single or double quotes, INTEGER if the literal is specified as an unquoted number with no decimal point or exponent, REAL if the literal is an unquoted number with a decimal point or exponent and NULL if the value is a NULL. Literals with storage class BLOB are specified using the X'ABCD' notation.</P> <LI><P>Values supplied using the sqlite3_bind_* APIs are assigned the storage class that most closely matches the native type bound (i.e. sqlite3_bind_blob() binds a value with storage class BLOB).</P> </UL> <P>The storage class of a value that is the result of an SQL scalar operator depends on the outermost operator of the expression. User-defined functions may return values with any storage class. It is not generally possible to determine the storage class of the result of an expression at compile time.</P> <a name="affinity"></a> <h3>2. Column Affinity</h3> <p> In SQLite version 3, the type of a value is associated with the value itself, not with the column or variable in which the value is stored. (This is sometimes called <a href="http://www.cliki.net/manifest%20type%20system"> manifest typing</a>.) All other SQL databases engines that we are aware of use the more restrictive system of static typing where the type is associated with the container, not the value. </p> <p> In order to maximize compatibility between SQLite and other database engines, SQLite support the concept of "type affinity" on columns. The type affinity of a column is the recommended type for data stored in that column. The key here is that the type is recommended, not required. Any column can still store any type of data, in theory. It is just that some columns, given the choice, will prefer to use one storage class over another. The preferred storage class for a column is called its "affinity". </p> <P>Each column in an SQLite 3 database is assigned one of the following type affinities:</P> <UL> <LI>TEXT</LI> <LI>NUMERIC</LI> <LI>INTEGER</LI> <LI>REAL</li> <LI>NONE</LI> </UL> <P>A column with TEXT affinity stores all data using storage classes NULL, TEXT or BLOB. If numerical data is inserted into a column with TEXT affinity it is converted to text form before being stored.</P> <P>A column with NUMERIC affinity may contain values using all five storage classes. When text data is inserted into a NUMERIC column, an attempt is made to convert it to an integer or real number before it is stored. If the conversion is successful, then the value is stored using the INTEGER or REAL storage class. If the conversion cannot be performed the value is stored using the TEXT storage class. No attempt is made to convert NULL or blob values.</P> <P>A column that uses INTEGER affinity behaves in the same way as a column with NUMERIC affinity, except that if a real value with no floating point component (or text value that converts to such) is inserted it is converted to an integer and stored using the INTEGER storage class.</P> <P>A column with REAL affinity behaves like a column with NUMERIC affinity except that it forces integer values into floating point representation. (As an optimization, integer values are stored on disk as integers in order to take up less space and are only converted to floating point as the value is read out of the table.)</P> <P>A column with affinity NONE does not prefer one storage class over another. It makes no attempt to coerce data before it is inserted.</P> <h4>2.1 Determination Of Column Affinity</h4> <P>The type affinity of a column is determined by the declared type of the column, according to the following rules:</P> <OL> <LI><P>If the datatype contains the string "INT" then it is assigned INTEGER affinity.</P> <LI><P>If the datatype of the column contains any of the strings "CHAR", "CLOB", or "TEXT" then that column has TEXT affinity. Notice that the type VARCHAR contains the string "CHAR" and is thus assigned TEXT affinity.</P> <LI><P>If the datatype for a column contains the string "BLOB" or if no datatype is specified then the column has affinity NONE.</P> <LI><P>If the datatype for a column contains any of the strings "REAL", "FLOA", or "DOUB" then the column has REAL affinity</P> <LI><P>Otherwise, the affinity is NUMERIC.</P> </OL> <P>If a table is created using a "CREATE TABLE <table> AS SELECT..." statement, then all columns have no datatype specified and they are given no affinity.</P> <h4>2.2 Column Affinity Example</h4> <blockquote> <PRE>CREATE TABLE t1( t TEXT, nu NUMERIC, i INTEGER, no BLOB ); -- Storage classes for the following row: -- TEXT, REAL, INTEGER, TEXT INSERT INTO t1 VALUES('500.0', '500.0', '500.0', '500.0'); -- Storage classes for the following row: -- TEXT, REAL, INTEGER, REAL INSERT INTO t1 VALUES(500.0, 500.0, 500.0, 500.0); </PRE> </blockquote> <a name="comparisons"></a> <h3>3. Comparison Expressions</h3> <P>Like SQLite version 2, version 3 features the binary comparison operators '=', '<', '<=', '>=' and '!=', an operation to test for set membership, 'IN', and the ternary comparison operator 'BETWEEN'.</P> <P>The results of a comparison depend on the storage classes of the two values being compared, according to the following rules:</P> <UL> <LI><P>A value with storage class NULL is considered less than any other value (including another value with storage class NULL).</P> <LI><P>An INTEGER or REAL value is less than any TEXT or BLOB value. When an INTEGER or REAL is compared to another INTEGER or REAL, a numerical comparison is performed.</P> <LI><P>A TEXT value is less than a BLOB value. When two TEXT values are compared, the C library function memcmp() is usually used to determine the result. However this can be overridden, as described under 'User-defined collation Sequences' below.</P> <LI><P>When two BLOB values are compared, the result is always determined using memcmp().</P> </UL> <P>SQLite may attempt to convert values between the numeric storage classes (INTEGER and REAL) and TEXT before performing a comparison. For binary comparisons, this is done in the cases enumerated below. The term "expression" used in the bullet points below means any SQL scalar expression or literal other than a column value. Note that if X and Y.Z are a column names, then +X and +Y.Z are considered expressions.</P> <UL> <LI><P>When a column value is compared to the result of an expression, the affinity of the column is applied to the result of the expression before the comparison takes place.</P> <LI><P>When two column values are compared, if one column has INTEGER or REAL or NUMERIC affinity and the other does not, then NUMERIC affinity is applied to any values with storage class TEXT extracted from the non-NUMERIC column.</P> <LI><P>When the results of two expressions are compared, no conversions occur. The results are compared as is. If a string is compared to a number, the number will always be less than the string.</P> </UL> <P> In SQLite, the expression "a BETWEEN b AND c" is equivalent to "a >= b AND a <= c", even if this means that different affinities are applied to 'a' in each of the comparisons required to evaluate the expression. </P> <P>Expressions of the type "a IN (SELECT b ....)" are handled by the three rules enumerated above for binary comparisons (e.g. in a similar manner to "a = b"). For example if 'b' is a column value and 'a' is an expression, then the affinity of 'b' is applied to 'a' before any comparisons take place.</P> <P>SQLite treats the expression "a IN (x, y, z)" as equivalent to "a = +x OR a = +y OR a = +z". The values to the right of the IN operator (the "x", "y", and "z" values in this example) are considered to be expressions, even if they happen to be column values. If the value of the left of the IN operator is a column, then the affinity of that column is used. If the value is an expression then no conversions occur. </P> <h4>3.1 Comparison Example</h4> <blockquote> <PRE> CREATE TABLE t1( a TEXT, b NUMERIC, c BLOB ); -- Storage classes for the following row: -- TEXT, REAL, TEXT INSERT INTO t1 VALUES('500', '500', '500'); -- 60 and 40 are converted to '60' and '40' and values are compared as TEXT. SELECT a < 60, a < 40 FROM t1; 1|0 -- Comparisons are numeric. No conversions are required. SELECT b < 60, b < 600 FROM t1; 0|1 -- Both 60 and 600 (storage class NUMERIC) are less than '500' -- (storage class TEXT). SELECT c < 60, c < 600 FROM t1; 0|0 </PRE> </blockquote> <h3>4. Operators</h3> <P>All mathematical operators (which is to say, all operators other than the concatenation operator "||") apply NUMERIC affinity to all operands prior to being carried out. If one or both operands cannot be converted to NUMERIC then the result of the operation is NULL.</P> <P>For the concatenation operator, TEXT affinity is applied to both operands. If either operand cannot be converted to TEXT (because it is NULL or a BLOB) then the result of the concatenation is NULL.</P> <h3>5. Sorting, Grouping and Compound SELECTs</h3> <P>When values are sorted by an ORDER by clause, values with storage class NULL come first, followed by INTEGER and REAL values interspersed in numeric order, followed by TEXT values usually in memcmp() order, and finally BLOB values in memcmp() order. No storage class conversions occur before the sort.</P> <P>When grouping values with the GROUP BY clause values with different storage classes are considered distinct, except for INTEGER and REAL values which are considered equal if they are numerically equal. No affinities are applied to any values as the result of a GROUP by clause.</P> <P>The compound SELECT operators UNION, INTERSECT and EXCEPT perform implicit comparisons between values. Before these comparisons are performed an affinity may be applied to each value. The same affinity, if any, is applied to all values that may be returned in a single column of the compound SELECT result set. The affinity applied is the affinity of the column returned by the left most component SELECTs that has a column value (and not some other kind of expression) in that position. If for a given compound SELECT column none of the component SELECTs return a column value, no affinity is applied to the values from that column before they are compared.</P> <h3>6. Other Affinity Modes</h3> <P>The above sections describe the operation of the database engine in 'normal' affinity mode. SQLite version 3 will feature two other affinity modes, as follows:</P> <UL> <LI><P><B>Strict affinity</B> mode. In this mode if a conversion between storage classes is ever required, the database engine returns an error and the current statement is rolled back.</P> <LI><P><B>No affinity</B> mode. In this mode no conversions between storage classes are ever performed. Comparisons between values of different storage classes (except for INTEGER and REAL) are always false.</P> </UL> <a name="collation"></a> <h3>7. User-defined Collation Sequences</h3> <p> By default, when SQLite compares two text values, the result of the comparison is determined using memcmp(), regardless of the encoding of the string. SQLite v3 provides the ability for users to supply arbitrary comparison functions, known as user-defined collation sequences, to be used instead of memcmp(). </p> <p> Aside from the default collation sequence BINARY, implemented using memcmp(), SQLite features one extra built-in collation sequences intended for testing purposes, the NOCASE collation: </p> <UL> <LI><b>BINARY</b> - Compares string data using memcmp(), regardless of text encoding.</LI> <LI><b>NOCASE</b> - The same as binary, except the 26 upper case characters used by the English language are folded to their lower case equivalents before the comparison is performed. </UL> <h4>7.1 Assigning Collation Sequences from SQL</h4> <p> Each column of each table has a default collation type. If a collation type other than BINARY is required, a COLLATE clause is specified as part of the <a href="lang_createtable.html">column definition</a> to define it. </p> <p> Whenever two text values are compared by SQLite, a collation sequence is used to determine the results of the comparison according to the following rules. Sections 3 and 5 of this document describe the circumstances under which such a comparison takes place. </p> <p> For binary comparison operators (=, <, >, <= and >=) if either operand is a column, then the default collation type of the column determines the collation sequence to use for the comparison. If both operands are columns, then the collation type for the left operand determines the collation sequence used. If neither operand is a column, then the BINARY collation sequence is used. For the purposes of this paragraph, a column name preceded by one or more unary "+" operators is considered a column name. </p> <p> The expression "x BETWEEN y and z" is equivalent to "x >= y AND x <= z". The expression "x IN (SELECT y ...)" is handled in the same way as the expression "x = y" for the purposes of determining the collation sequence to use. The collation sequence used for expressions of the form "x IN (y, z ...)" is the default collation type of x if x is a column, or BINARY otherwise. </p> <p> An <a href="lang_select.html">ORDER BY</a> clause that is part of a SELECT statement may be assigned a collation sequence to be used for the sort operation explicitly. In this case the explicit collation sequence is always used. Otherwise, if the expression sorted by an ORDER BY clause is a column, then the default collation type of the column is used to determine sort order. If the expression is not a column, then the BINARY collation sequence is used. </p> <h4>7.2 Collation Sequences Example</h4> <p> The examples below identify the collation sequences that would be used to determine the results of text comparisons that may be performed by various SQL statements. Note that a text comparison may not be required, and no collation sequence used, in the case of numeric, blob or NULL values. </p> <blockquote> <PRE> CREATE TABLE t1( a, -- default collation type BINARY b COLLATE BINARY, -- default collation type BINARY c COLLATE REVERSE, -- default collation type REVERSE d COLLATE NOCASE -- default collation type NOCASE ); -- Text comparison is performed using the BINARY collation sequence. SELECT (a = b) FROM t1; -- Text comparison is performed using the NOCASE collation sequence. SELECT (d = a) FROM t1; -- Text comparison is performed using the BINARY collation sequence. SELECT (a = d) FROM t1; -- Text comparison is performed using the REVERSE collation sequence. SELECT ('abc' = c) FROM t1; -- Text comparison is performed using the REVERSE collation sequence. SELECT (c = 'abc') FROM t1; -- Grouping is performed using the NOCASE collation sequence (i.e. values -- 'abc' and 'ABC' are placed in the same group). SELECT count(*) GROUP BY d FROM t1; -- Grouping is performed using the BINARY collation sequence. SELECT count(*) GROUP BY (d || '') FROM t1; -- Sorting is performed using the REVERSE collation sequence. SELECT * FROM t1 ORDER BY c; -- Sorting is performed using the BINARY collation sequence. SELECT * FROM t1 ORDER BY (c || ''); -- Sorting is performed using the NOCASE collation sequence. SELECT * FROM t1 ORDER BY c COLLATE NOCASE; </PRE> </blockquote> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | <title>Datatypes In SQLite version 2</title> <h2>Datatypes In SQLite Version 2</h2> <h3>1.0 Typelessness</h3> <p> SQLite is "typeless". This means that you can store any kind of data you want in any column of any table, regardless of the declared datatype of that column. (See the one exception to this rule in section 2.0 below.) This behavior is a feature, not a bug. A database is suppose to store and retrieve data and it should not matter to the database what format that data is in. The strong typing system found in most other SQL engines and codified in the SQL language spec is a misfeature - it is an example of the implementation showing through into the interface. SQLite seeks to overcome this misfeature by allowing you to store any kind of data into any kind of column and by allowing flexibility in the specification of datatypes. </p> <p> A datatype to SQLite is any sequence of zero or more names optionally followed by a parenthesized lists of one or two signed integers. Notice in particular that a datatype may be <em>zero</em> or more names. That means that an empty string is a valid datatype as far as SQLite is concerned. So you can declare tables where the datatype of each column is left unspecified, like this: </p> <blockquote><pre> CREATE TABLE ex1(a,b,c); </pre></blockquote> <p> Even though SQLite allows the datatype to be omitted, it is still a good idea to include it in your CREATE TABLE statements, since the data type often serves as a good hint to other programmers about what you intend to put in the column. And if you ever port your code to another database engine, that other engine will probably require a datatype of some kind. SQLite accepts all the usual datatypes. For example: </p> <blockquote><pre> CREATE TABLE ex2( a VARCHAR(10), b NVARCHAR(15), c TEXT, d INTEGER, e FLOAT, f BOOLEAN, g CLOB, h BLOB, i TIMESTAMP, j NUMERIC(10,5) k VARYING CHARACTER (24), l NATIONAL VARYING CHARACTER(16) ); </pre></blockquote> <p> And so forth. Basically any sequence of names optionally followed by one or two signed integers in parentheses will do. </p> <h3>2.0 The INTEGER PRIMARY KEY</h3> <p> One exception to the typelessness of SQLite is a column whose type is INTEGER PRIMARY KEY. (And you must use "INTEGER" not "INT". A column of type INT PRIMARY KEY is typeless just like any other.) INTEGER PRIMARY KEY columns must contain a 32-bit signed integer. Any attempt to insert non-integer data will result in an error. </p> <p> INTEGER PRIMARY KEY columns can be used to implement the equivalent of AUTOINCREMENT. If you try to insert a NULL into an INTEGER PRIMARY KEY column, the column will actually be filled with a integer that is one greater than the largest key already in the table. Or if the largest key is 2147483647, then the column will be filled with a random integer. Either way, the INTEGER PRIMARY KEY column will be assigned a unique integer. You can retrieve this integer using the <b>sqlite_last_insert_rowid()</b> API function or using the <b>last_insert_rowid()</b> SQL function in a subsequent SELECT statement. </p> <h3>3.0 Comparison and Sort Order</h3> <p> SQLite is typeless for the purpose of deciding what data is allowed to be stored in a column. But some notion of type comes into play when sorting and comparing data. For these purposes, a column or an expression can be one of two types: <b>numeric</b> and <b>text</b>. The sort or comparison may give different results depending on which type of data is being sorted or compared. </p> <p> If data is of type <b>text</b> then the comparison is determined by the standard C data comparison functions <b>memcmp()</b> or <b>strcmp()</b>. The comparison looks at bytes from two inputs one by one and returns the first non-zero difference. Strings are '\000' terminated so shorter strings sort before longer strings, as you would expect. </p> <p> For numeric data, this situation is more complex. If both inputs look like well-formed numbers, then they are converted into floating point values using <b>atof()</b> and compared numerically. If one input is not a well-formed number but the other is, then the number is considered to be less than the non-number. If neither inputs is a well-formed number, then <b>strcmp()</b> is used to do the comparison. </p> <p> Do not be confused by the fact that a column might have a "numeric" datatype. This does not mean that the column can contain only numbers. It merely means that if the column does contain a number, that number will sort in numerical order. </p> <p> For both text and numeric values, NULL sorts before any other value. A comparison of any value against NULL using operators like "<" or ">=" is always false. </p> <h3>4.0 How SQLite Determines Datatypes</h3> <p> For SQLite version 2.6.3 and earlier, all values used the numeric datatype. The text datatype appears in version 2.7.0 and later. In the sequel it is assumed that you are using version 2.7.0 or later of SQLite. </p> <p> For an expression, the datatype of the result is often determined by the outermost operator. For example, arithmetic operators ("+", "*", "%") always return a numeric results. The string concatenation operator ("||") returns a text result. And so forth. If you are ever in doubt about the datatype of an expression you can use the special <b>typeof()</b> SQL function to determine what the datatype is. For example: </p> <blockquote><pre> sqlite> SELECT typeof('abc'+123); numeric sqlite> SELECT typeof('abc'||123); text </pre></blockquote> <p> For table columns, the datatype is determined by the type declaration of the CREATE TABLE statement. The datatype is text if and only if the type declaration contains one or more of the following strings: </p> <blockquote> BLOB<br> CHAR<br> CLOB</br> TEXT </blockquote> <p> The search for these strings in the type declaration is case insensitive, of course. If any of the above strings occur anywhere in the type declaration, then the datatype of the column is text. Notice that the type "VARCHAR" contains "CHAR" as a substring so it is considered text.</p> <p>If none of the strings above occur anywhere in the type declaration, then the datatype is numeric. Note in particular that the datatype for columns with an empty type declaration is numeric. </p> <h3>5.0 Examples</h3> <p> Consider the following two command sequences: </p> <blockquote><pre> CREATE TABLE t1(a INTEGER UNIQUE); CREATE TABLE t2(b TEXT UNIQUE); INSERT INTO t1 VALUES('0'); INSERT INTO t2 VALUES(0); INSERT INTO t1 VALUES('0.0'); INSERT INTO t2 VALUES(0.0); </pre></blockquote> <p>In the sequence on the left, the second insert will fail. In this case, the strings '0' and '0.0' are treated as numbers since they are being inserted into a numeric column but 0==0.0 which violates the uniqueness constraint. However, the second insert in the right-hand sequence works. In this case, the constants 0 and 0.0 are treated a strings which means that they are distinct.</p> <p>SQLite always converts numbers into double-precision (64-bit) floats for comparison purposes. This means that a long sequence of digits that differ only in insignificant digits will compare equal if they are in a numeric column but will compare unequal if they are in a text column. We have:</p> <blockquote><pre> INSERT INTO t1 INSERT INTO t2 VALUES('12345678901234567890'); VALUES(12345678901234567890); INSERT INTO t1 INSERT INTO t2 VALUES('12345678901234567891'); VALUES(12345678901234567891); </pre></blockquote> <p>As before, the second insert on the left will fail because the comparison will convert both strings into floating-point number first and the only difference in the strings is in the 20-th digit which exceeds the resolution of a 64-bit float. In contrast, the second insert on the right will work because in that case, the numbers being inserted are strings and are compared using memcmp().</p> <p> Numeric and text types make a difference for the DISTINCT keyword too: </p> <blockquote><pre> CREATE TABLE t3(a INTEGER); CREATE TABLE t4(b TEXT); INSERT INTO t3 VALUES('0'); INSERT INTO t4 VALUES(0); INSERT INTO t3 VALUES('0.0'); INSERT INTO t4 VALUES(0.0); SELECT DISTINCT * FROM t3; SELECT DISTINCT * FROM t4; </pre></blockquote> <p> The SELECT statement on the left returns a single row since '0' and '0.0' are treated as numbers and are therefore indistinct. But the SELECT statement on the right returns two rows since 0 and 0.0 are treated a strings which are different.</p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 | <title>Distinctive Features Of SQLite</title> <p> This page highlights some of the characteristics of SQLite that are unusual and which make SQLite different from many other SQL database engines. </p> <tcl> proc feature {tag name text} { puts "<a name=\"$tag\" /></a>" puts "<p><b>$name</b></p>\n" puts "<blockquote>$text</blockquote>\n" } feature zeroconfig {Zero-Configuration} { SQLite does not need to be "installed" before it is used. There is no "setup" procedure. There is no server process that needs to be started, stopped, or configured. There is no need for an administrator to create a new database instance or assign access permissions to users. SQLite uses no configuration files. Nothing needs to be done to tell the system that SQLite is running. No actions are required to recover after a system crash or power failure. There is nothing to troubleshoot. <p> SQLite just works. <p> Other more familiar database engines run great once you get them going. But doing the initial installation and configuration can be intimidatingly complex. } feature serverless {Serverless} { Most SQL database engines are implemented as a separate server process. Programs that want to access the database communicate with the server using some kind of interprocess communcation (typically TCP/IP) to send requests to the server and to receive back results. SQLite does not work this way. With SQLite, the process that wants to access the database reads and writes directly from the database files on disk. There is no intermediary server process. <p> There are advantages and disadvantages to being serverless. The main advantage is that there is no separate server process to install, setup, configure, initialize, manage, and troubleshoot. This is one reason why SQLite is a "zero-configuration" database engine. Programs that use SQLite require no administrative support for setting up the database engine before they are run. Any program that is able to access the disk is able to use an SQLite database. <p> On the other hand, a database engine that uses a server can provide better protection from bugs in the client application - stray pointers in a client cannot corrupt memory on the server. And because a server is a single persistent process, it is able control database access with more precision, allowing for finer grain locking and better concurrancy. <p> Most SQL database engines are client/server based. Of those that are serverless, SQLite is the only one that this author knows of that allows multiple applications to access the same database at the same time. } feature onefile {Single Database File} { An SQLite database is a single ordinary disk file that can be located anywhere in the directory hierarchy. If SQLite can read the disk file then it can read anything in the database. If the disk file and its directory are writable, then SQLite can change anything in the database. Database files can easily be copied onto a USB memory stick or emailed for sharing. <p> Other SQL database engines tend to store data as a large collection of files. Often these files are in a standard location that only the database engine itself can access. This makes the data more secure, but also makes it harder to access. Some SQL database engines provide the option of writing directly to disk and bypassing the filesystem all together. This provides added performance, but at the cost of considerable setup and maintenance complexity. } feature small {Compact} { When optimized for size, the whole SQLite library with everything enabled is less than 225KiB in size (as measured on an ix86 using the "size" utility from the GNU compiler suite.) Unneeded features can be disabled at compile-time to further reduce the size of the library to under 170KiB if desired. <p> Most other SQL database engines are much larger than this. IBM boasts that it's recently released CloudScape database engine is "only" a 2MiB jar file - 10 times larger than SQLite even after it is compressed! Firebird boasts that it's client-side library is only 350KiB. That's 50% larger than SQLite and does not even contain the database engine. The Berkeley DB library from Sleepycat is 450KiB and it omits SQL support, providing the programmer with only simple key/value pairs. } feature typing {Manifest typing} { Most SQL database engines use static typing. A datatype is associated with each column in a table and only values of that particular datatype are allowed to be stored in that column. SQLite relaxes this restriction by using manifest typing. In manifest typing, the datatype is a property of the value itself, not of the column in which the value is stored. SQLite thus allows the user to store any value of any datatype into any column regardless of the declared type of that column. (There are some exceptions to this rule: An INTEGER PRIMARY KEY column may only store integers. And SQLite attempts to coerce values into the declared datatype of the column when it can.) <p> As far as we can tell, the SQL language specification allows the use of manifest typing. Nevertheless, most other SQL database engines are statically typed and so some people feel that the use of manifest typing is a bug in SQLite. But the authors of SQLite feel very strongly that this is a feature. The use of manifest typing in SQLite is a deliberate design decision which has proven in practice to make SQLite more reliable and easier to use, especially when used in combination with dynamically typed programming languages such as Tcl and Python. } feature flex {Variable-length records} { Most other SQL database engines allocated a fixed amount of disk space for each row in most tables. They play special tricks for handling BLOBs and CLOBs which can be of wildly varying length. But for most tables, if you declare a column to be a VARCHAR(100) then the database engine will allocate 100 bytes of disk space regardless of how much information you actually store in that column. <p> SQLite, in contrast, use only the amount of disk space actually needed to store the information in a row. If you store a single character in a VARCHAR(100) column, then only a single byte of disk space is consumed. (Actually two bytes - there is some overhead at the beginning of each column to record its datatype and length.) <p> The use of variable-length records by SQLite has a number of advantages. It results in smaller database files, obviously. It also makes the database run faster, since there is less information to move to and from disk. And, the use of variable-length records makes it possible for SQLite to employ manifest typing instead of static typing. } feature readable {Readable source code} { The source code to SQLite is designed to be readable and accessible to the average programmer. All procedures and data structures and many automatic variables are carefully commented with useful information about what they do. Boilerplate commenting is omitted. } feature vdbe {SQL statements compile into virtual machine code} { Every SQL database engine compiles each SQL statement into some kind of internal data structure which is then used to carry out the work of the statement. But in most SQL engines that internal data structure is a complex web of interlinked structures and objects. In SQLite, the compiled form of statements is a short program in a machine-language like representation. Users of the database can view this <a href="opcode.html">virtual machine language</a> by prepending the <a href="lang_explain.html">EXPLAIN</a> keyword to a query. <p> The use of a virtual machine in SQLite has been a great benefit to library's development. The virtual machine provides a crisp, well-defined junction between the front-end of SQLite (the part that parses SQL statements and generates virtual machine code) and the back-end (the part that executes the virtual machine code and computes a result.) The virtual machine allows the developers to see clearly and in an easily readable form what SQLite is trying to do with each statement it compiles, which is a tremendous help in debugging. Depending on how it is compiled, SQLite also has the capability of tracing the execution of the virtual machine - printing each virtual machine instruction and its result as it executes. } #feature binding {Tight bindings to dynamic languages} { # Because it is embedded, SQLite can have a much tighter and more natural # binding to high-level dynamic languages such as Tcl, Perl, Python, # PHP, and Ruby. # For example, #} feature license {Public domain} { The source code for SQLite is in the public domain. No claim of copyright is made on any part of the core source code. (The documentation and test code is a different matter - some sections of documentation and test logic are governed by open-sources licenses.) All contributors to the SQLite core software have signed affidavits specifically disavowing any copyright interest in the code. This means that anybody is able to legally do anything they want with the SQLite source code. <p> There are other SQL database engines with liberal licenses that allow the code to be broadly and freely used. But those other engines are still governed by copyright law. SQLite is different in that copyright law simply does not apply. <p> The source code files for other SQL database engines typically begin with a comment describing your license rights to view and copy that file. The SQLite source code contains no license since it is not governed by copyright. Instead of a license, the SQLite source code offers a blessing: <blockquote> <i>May you do good and not evil<br> May you find forgiveness for yourself and forgive others<br> May you share freely, never taking more than you give.</i> </blockquote> } feature extensions {SQL language extensions} { SQLite provides a number of enhancements to the SQL language not normally found in other database engines. The EXPLAIN keyword and manifest typing have already been mentioned above. SQLite also provides statements such as <a href="lang_replace.html">REPLACE</a> and the <a href="lang_conflict.html">ON CONFLICT</a> clause that allow for added control over the resolution of constraint conflicts. SQLite supports <a href="lang_attach.html">ATTACH</a> and <a href="lang_detach.html">DETACH</a> commands that allow multiple independent databases to be used together in the same query. And SQLite defines APIs that allows the user to add new <a href="capi3ref.html#sqlite3_create_function">SQL functions</a> and <a href="capi3ref.html#sqlite3_create_collation">collating sequences</a>. } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>SQLite Documentation</title> <h2>Available Documentation</h2> <table width="100%" cellpadding="5"> <tcl> proc doc {name url desc} { puts {<tr><td valign="top" align="right">} regsub -all { +} $name {\ } name puts "<a href=\"$url\">$name</a></td>" puts {<td width="10"></td>} puts {<td valign="top" align="left">} puts $desc puts {</td></tr>} } doc {Appropriate Uses For SQLite} {whentouse.html} { This document describes situations where SQLite is an approriate database engine to use versus situations where a client/server database engine might be a better choice. } doc {Distinctive Features} {different.html} { This document enumerates and describes some of the features of SQLite that make it different from other SQL database engines. } doc {SQLite In 5 Minutes Or Less} {quickstart.html} { A very quick introduction to programming with SQLite. } doc {SQL Syntax} {lang.html} { This document describes the SQL language that is understood by SQLite. } doc {Version 3 C/C++ API<br>Reference} {capi3ref.html} { This document describes each API function separately. } doc {Sharing Cache Mode} {sharedcache.html} { Version 3.3.0 and later supports the ability for two or more database connections to share the same page and schema cache. This feature is useful for certain specialized applications. } doc {Tcl API} {tclsqlite.html} { A description of the TCL interface bindings for SQLite. } doc {How SQLite Implements Atomic Commit} {ac/atomiccommit.html} { A description of the logic within SQLite that implements transactions with atomic commit, even in the face of power failures. } doc {Moving From SQLite 3.4 to 3.5} {34to35.html} { A document describing the differences between SQLite version 3.4.2 and 3.5.0. } doc {Pragma commands} {pragma.html} { This document describes SQLite performance tuning options and other special purpose database commands. } doc {SQLite Version 3} {version3.html} { A summary of of the changes between SQLite version 2.8 and SQLite version 3.0. } doc {Version 3 C/C++ API} {capi3.html} { A description of the C/C++ interface bindings for SQLite version 3.0.0 and following. } doc {Version 3 DataTypes } {datatype3.html} { SQLite version 3 introduces the concept of manifest typing, where the type of a value is associated with the value itself, not the column that it is stored in. This page describes data typing for SQLite version 3 in further detail. } doc {Locking And Concurrency<br>In SQLite Version 3} {lockingv3.html} { A description of how the new locking code in version 3 increases concurrancy and decreases the problem of writer starvation. } doc {Overview Of The Optimizer} {optoverview.html} { A quick overview of the various query optimizations that are attempted by the SQLite code generator. } doc {Null Handling} {nulls.html} { Different SQL database engines handle NULLs in different ways. The SQL standards are ambiguous. This document describes how SQLite handles NULLs in comparison with other SQL database engines. } doc {Copyright} {copyright.html} { SQLite is in the public domain. This document describes what that means and the implications for contributors. } doc {Unsupported SQL} {omitted.html} { This page describes features of SQL that SQLite does not support. } doc {Version 2 C/C++ API} {c_interface.html} { A description of the C/C++ interface bindings for SQLite through version 2.8 } doc {Version 2 DataTypes } {datatypes.html} { A description of how SQLite version 2 handles SQL datatypes. Short summary: Everything is a string. } doc {Release History} {changes.html} { A chronology of SQLite releases going back to version 1.0.0 } doc {Speed Comparison} {speed.html} { The speed of version 2.7.6 of SQLite is compared against PostgreSQL and MySQL. } doc {Architecture} {arch.html} { An architectural overview of the SQLite library, useful for those who want to hack the code. } doc {VDBE Tutorial} {vdbe.html} { The VDBE is the subsystem within SQLite that does the actual work of executing SQL statements. This page describes the principles of operation for the VDBE in SQLite version 2.7. This is essential reading for anyone who want to modify the SQLite sources. } doc {VDBE Opcodes} {opcode.html} { This document is an automatically generated description of the various opcodes that the VDBE understands. Programmers can use this document as a reference to better understand the output of EXPLAIN listings from SQLite. } doc {Compilation Options} {compile.html} { This document describes the compile time options that may be set to modify the default behaviour of the library or omit optional features in order to reduce binary size. } doc {Backwards Compatibility} {formatchng.html} { This document details all of the incompatible changes to the SQLite file format that have occurred since version 1.0.0. } </tcl> </table> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 | <title>SQLite Download Page</title> <h2>SQLite Download Page</h1> <table width="100%" cellpadding="5"> <tcl> proc Product {pattern desc} { regsub {V[23]} $pattern {*} p3 regsub V2 $pattern {(2[0-9a-z._]+)} pattern regsub V3 $pattern {(3[0-9a-z._]+)} pattern set p2 [string map {* .*} $pattern] set flist [glob -nocomplain $p3] foreach file [lsort -dict $flist] { if {![regexp ^$p2\$ $file all version]} continue regsub -all _ $version . version set size [file size $file] set units bytes if {$size>1024*1024} { set size [format %.2f [expr {$size/(1024.0*1024.0)}]] set units MiB } elseif {$size>1024} { set size [format %.2f [expr {$size/(1024.0)}]] set units KiB } puts "<tr><td width=\"10\"></td>" puts "<td valign=\"top\" align=\"right\">" puts "<a href=\"$file\">$file</a><br>($size $units)</td>" puts "<td width=\"5\"></td>" regsub -all VERSION $desc $version d2 puts "<td valign=\"top\">[string trim $d2]</td></tr>" } } cd $::DEST proc Heading {title} { puts "<tr><td colspan=4><big><b>$title</b></big></td></tr>" } Heading {Precompiled Binaries for Linux} Product sqlite3-V3.bin.gz { A command-line program for accessing and modifying SQLite version 3.* databases. See <a href="sqlite.html">the documentation</a> for additional information. } Product sqlite-V3.bin.gz { A command-line program for accessing and modifying SQLite databases. See <a href="sqlite.html">the documentation</a> for additional information. } Product tclsqlite-V3.so.gz { Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>. You can import this shared library into either tclsh or wish to get SQLite database access from Tcl/Tk. See <a href="tclsqlite.html">the documentation</a> for details. } Product sqlite-V3.so.gz { A precompiled shared-library for Linux without the TCL bindings. } Product fts1-V3.so.gz { A precompiled <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> for Linux. } Product fts2-V3.so.gz { A precompiled <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> for Linux. } Product sqlite-devel-V3.i386.rpm { RPM containing documentation, header files, and static library for SQLite version VERSION. } Product sqlite-V3-1.i386.rpm { RPM containing shared libraries and the <b>sqlite</b> command-line program for SQLite version VERSION. } Product sqlite*_analyzer-V3.bin.gz { An analysis program for database files compatible with SQLite version VERSION and later. } Heading {Precompiled Binaries For Windows} Product sqlite-V3.zip { A command-line program for accessing and modifing SQLite databases. See <a href="sqlite.html">the documentation</a> for additional information. } Product tclsqlite-V3.zip { Bindings for <a href="http://www.tcl.tk/">Tcl/Tk</a>. You can import this shared library into either tclsh or wish to get SQLite database access from Tcl/Tk. See <a href="tclsqlite.html">the documentation</a> for details. } Product sqlitedll-V3.zip { This is a DLL of the SQLite library without the TCL bindings. The only external dependency is MSVCRT.DLL. } Product fts1dll-V3.zip { A precompiled <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 Module</a> for win32. } Product fts2dll-V3.zip { A precompiled <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsTwo">FTS2 Module</a> for win32. } Product sqlite*_analyzer-V3.zip { An analysis program for database files compatible with SQLite version VERSION and later. } Heading {Source Code} Product {sqlite-V3.tar.gz} { A tarball of the complete source tree for SQLite version VERSION including all of the documentation. } Product {sqlite-source-V3.zip} { This ZIP archive contains preprocessed C code for the SQLite library as individual source files. Unlike the tarballs below, all of the preprocessing and automatic code generation has already been done on these C code files, so they can be converted to object code directly with any ordinary C compiler. } Product {sqlite-amalgamation-V3.zip} { This ZIP archive contains all preprocessed C code combined into a single source file (the <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation"> amalgamation</a>). } Product {sqlite-V3-tea.tar.gz} { A tarball of proprocessed source code together with a <a href="http://www.tcl.tk/doc/tea/">Tcl Extension Architecture (TEA)</a> compatible configure script and makefile. } Product {sqlite-V3.src.rpm} { An RPM containing complete source code for SQLite version VERSION } Heading {Cross-Platform Binaries} Product {sqlite-V3.kit} { A <a href="http://www.equi4.com/starkit.html">starkit</a> containing precompiled SQLite binaries and Tcl bindings for Linux-x86, Windows, and Mac OS-X ppc and x86. } Heading {Historical Binaries And Source Code} Product sqlite-V2.bin.gz { A command-line program for accessing and modifying SQLite version 2.* databases on Linux-x86. } Product sqlite-V2.zip { A command-line program for accessing and modifying SQLite version 2.* databases on win32. } Product sqlite*_analyzer-V2.bin.gz { An analysis program for version 2.* database files on Linux-x86 } Product sqlite*_analyzer-V2.zip { An analysis program for version 2.* database files on win32. } Product {sqlite-source-V2.zip} { This ZIP archive contains C source code for the SQLite library version VERSION. } </tcl> </table> <a name="cvs"></a> <h3>Direct Access To The Sources Via Anonymous CVS</h3> <p> All SQLite source code is maintained in a <a href="http://www.cvshome.org/">CVS</a> repository that is available for read-only access by anyone. You can interactively view the repository contents and download individual files by visiting <a href="http://www.sqlite.org/cvstrac/dir?d=sqlite"> http://www.sqlite.org/cvstrac/dir?d=sqlite</a>. To access the repository directly, use the following commands: </p> <blockquote><pre> cvs -d :pserver:anonymous@www.sqlite.org:/sqlite login cvs -d :pserver:anonymous@www.sqlite.org:/sqlite checkout sqlite </pre></blockquote> <p> When the first command prompts you for a password, enter "anonymous". </p> <p> To access the SQLite version 2.8 sources, begin by getting the 3.0 tree as described above. Then update to the "version_2" branch as follows: </p> <blockquote><pre> cvs update -r version_2 </pre></blockquote> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | <title>How to build a dynamically loaded Tcl extension for SQLite</title> <h1 align=center> How To Build A Dynamically Loaded Tcl Extension </h1> <p> <i>This note was contributed by <a href="bsaunder@tampabay.rr.com.nospam">Bill Saunders</a>. Thanks, Bill!</i> </p> <p> To compile the SQLite Tcl extension into a dynamically loaded module I did the following: </p> <ol> <li><p>Do a standard compile (I had a dir called bld at the same level as sqlite ie /root/bld /root/sqlite I followed the directions and did a standard build in the bld directory)</p></li> <li><p> Now do the following in the bld directory <blockquote><pre> gcc -shared -I. -lgdbm ../sqlite/src/tclsqlite.c libsqlite.a -o sqlite.so </pre></blockquote></p></li> <li><p> This should produce the file sqlite.so in the bld directory</p></li> <li><p> Create a pkgIndex.tcl file that contains this line <blockquote><pre> package ifneeded sqlite 1.0 [list load [file join $dir sqlite.so]] </pre></blockquote></p></li> <li><p> To use this put sqlite.so and pkgIndex.tcl in the same directory</p></li> <li><p> From that directory start wish</p></li> <li><p> Execute the following tcl command (tells tcl where to fine loadable modules) <blockquote><pre> lappend auto_path [exec pwd] </pre></blockquote></p></li> <li><p> Load the package <blockquote><pre> package require sqlite </pre></blockquote></p></li> <li><p> Have fun....</p></li> </ul> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 | <title>SQLite Frequently Asked Questions</title> <tcl> set cnt 1 proc faq {question answer} { set ::faq($::cnt) [list [string trim $question] [string trim $answer]] incr ::cnt } ############# # Enter questions and answers here. faq { How do I create an AUTOINCREMENT field. } { <p>Short answer: A column declared INTEGER PRIMARY KEY will autoincrement.</p> <p>Here is the long answer: If you declare a column of a table to be INTEGER PRIMARY KEY, then whenever you insert a NULL into that column of the table, the NULL is automatically converted into an integer which is one greater than the largest value of that column over all other rows in the table, or 1 if the table is empty. (If the largest possible integer key, 9223372036854775807, then an unused key value is chosen at random.) For example, suppose you have a table like this: <blockquote><pre> CREATE TABLE t1( a INTEGER PRIMARY KEY, b INTEGER ); </pre></blockquote> <p>With this table, the statement</p> <blockquote><pre> INSERT INTO t1 VALUES(NULL,123); </pre></blockquote> <p>is logically equivalent to saying:</p> <blockquote><pre> INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123); </pre></blockquote> <p>There is a new API function named <a href="capi3ref.html#sqlite3_last_insert_rowid"> sqlite3_last_insert_rowid()</a> which will return the integer key for the most recent insert operation.</p> <p>Note that the integer key is one greater than the largest key that was in the table just prior to the insert. The new key will be unique over all keys currently in the table, but it might overlap with keys that have been previously deleted from the table. To create keys that are unique over the lifetime of the table, add the AUTOINCREMENT keyword to the INTEGER PRIMARY KEY declaration. Then the key chosen will be one more than than the largest key that has ever existed in that table. If the largest possible key has previously existed in that table, then the INSERT will fail with an SQLITE_FULL error code.</p> } faq { What datatypes does SQLite support? } { <p>See <a href="datatype3.html">http://www.sqlite.org/datatype3.html</a>.</p> } faq { SQLite lets me insert a string into a database column of type integer! } { <p>This is a feature, not a bug. SQLite does not enforce data type constraints. Any data can be inserted into any column. You can put arbitrary length strings into integer columns, floating point numbers in boolean columns, or dates in character columns. The datatype you assign to a column in the CREATE TABLE command does not restrict what data can be put into that column. Every column is able to hold an arbitrary length string. (There is one exception: Columns of type INTEGER PRIMARY KEY may only hold a 64-bit signed integer. An error will result if you try to put anything other than an integer into an INTEGER PRIMARY KEY column.)</p> <p>But SQLite does use the declared type of a column as a hint that you prefer values in that format. So, for example, if a column is of type INTEGER and you try to insert a string into that column, SQLite will attempt to convert the string into an integer. If it can, it inserts the integer instead. If not, it inserts the string. This feature is sometimes call <a href="datatype3.html#affinity">type or column affinity</a>. </p> } faq { Why doesn't SQLite allow me to use '0' and '0.0' as the primary key on two different rows of the same table? } { <p>Your primary key must have a numeric type. Change the datatype of your primary key to TEXT and it should work.</p> <p>Every row must have a unique primary key. For a column with a numeric type, SQLite thinks that <b>'0'</b> and <b>'0.0'</b> are the same value because they compare equal to one another numerically. (See the previous question.) Hence the values are not unique.</p> } faq { Can multiple applications or multiple instances of the same application access a single database file at the same time? } { <p>Multiple processes can have the same database open at the same time. Multiple processes can be doing a SELECT at the same time. But only one process can be making changes to the database at any moment in time, however.</p> <p>SQLite uses reader/writer locks to control access to the database. (Under Win95/98/ME which lacks support for reader/writer locks, a probabilistic simulation is used instead.) But use caution: this locking mechanism might not work correctly if the database file is kept on an NFS filesystem. This is because fcntl() file locking is broken on many NFS implementations. You should avoid putting SQLite database files on NFS if multiple processes might try to access the file at the same time. On Windows, Microsoft's documentation says that locking may not work under FAT filesystems if you are not running the Share.exe daemon. People who have a lot of experience with Windows tell me that file locking of network files is very buggy and is not dependable. If what they say is true, sharing an SQLite database between two or more Windows machines might cause unexpected problems.</p> <p>We are aware of no other <i>embedded</i> SQL database engine that supports as much concurrancy as SQLite. SQLite allows multiple processes to have the database file open at once, and for multiple processes to read the database at once. When any process wants to write, it must lock the entire database file for the duration of its update. But that normally only takes a few milliseconds. Other processes just wait on the writer to finish then continue about their business. Other embedded SQL database engines typically only allow a single process to connect to the database at once.</p> <p>However, client/server database engines (such as PostgreSQL, MySQL, or Oracle) usually support a higher level of concurrency and allow multiple processes to be writing to the same database at the same time. This is possible in a client/server database because there is always a single well-controlled server process available to coordinate access. If your application has a need for a lot of concurrency, then you should consider using a client/server database. But experience suggests that most applications need much less concurrency than their designers imagine. </p> <p>When SQLite tries to access a file that is locked by another process, the default behavior is to return SQLITE_BUSY. You can adjust this behavior from C code using the <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a> API functions.</p> } faq { Is SQLite threadsafe? } { <p>Yes. Sometimes. In order to be thread-safe, SQLite must be compiled with the SQLITE_THREADSAFE preprocessor macro set to 1. Both the windows and linux precompiled binaries in the distribution are compiled this way. If you are unsure if the SQLite library you are linking against is compiled to be threadsafe you can call the <a href="capi3ref.html#sqlite3_threadsafe">sqlite3_threadsafe()</a> interface to find out. </p> <p>Prior to version 3.3.1, an <b>sqlite3</b> structure could only be used in the same thread that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a> to create it. You could not open a database in one thread then pass the handle off to another thread for it to use. This was due to limitations (bugs?) in many common threading implementations such as on RedHat9. Specifically, an fcntl() lock created by one thread cannot be removed or modified by a different thread on the troublesome systems. And since SQLite uses fcntl() locks heavily for concurrency control, serious problems arose if you start moving database connections across threads.</p> <p>The restriction on moving database connections across threads was relaxed somewhat in version 3.3.1. With that and subsequent versions, it is safe to move a connection handle across threads as long as the connection is not holding any fcntl() locks. You can safely assume that no locks are being held if no transaction is pending and all statements have been finalized.</p> <p>Under UNIX, you should not carry an open SQLite database across a fork() system call into the child process. Problems will result if you do.</p> } faq { How do I list all tables/indices contained in an SQLite database } { <p>If you are running the <b>sqlite3</b> command-line access program you can type "<b>.tables</b>" to get a list of all tables. Or you can type "<b>.schema</b>" to see the complete database schema including all tables and indices. Either of these commands can be followed by a LIKE pattern that will restrict the tables that are displayed.</p> <p>From within a C/C++ program (or a script using Tcl/Ruby/Perl/Python bindings) you can get access to table and index names by doing a SELECT on a special table named "<b>SQLITE_MASTER</b>". Every SQLite database has an SQLITE_MASTER table that defines the schema for the database. The SQLITE_MASTER table looks like this:</p> <blockquote><pre> CREATE TABLE sqlite_master ( type TEXT, name TEXT, tbl_name TEXT, rootpage INTEGER, sql TEXT ); </pre></blockquote> <p>For tables, the <b>type</b> field will always be <b>'table'</b> and the <b>name</b> field will be the name of the table. So to get a list of all tables in the database, use the following SELECT command:</p> <blockquote><pre> SELECT name FROM sqlite_master WHERE type='table' ORDER BY name; </pre></blockquote> <p>For indices, <b>type</b> is equal to <b>'index'</b>, <b>name</b> is the name of the index and <b>tbl_name</b> is the name of the table to which the index belongs. For both tables and indices, the <b>sql</b> field is the text of the original CREATE TABLE or CREATE INDEX statement that created the table or index. For automatically created indices (used to implement the PRIMARY KEY or UNIQUE constraints) the <b>sql</b> field is NULL.</p> <p>The SQLITE_MASTER table is read-only. You cannot change this table using UPDATE, INSERT, or DELETE. The table is automatically updated by CREATE TABLE, CREATE INDEX, DROP TABLE, and DROP INDEX commands.</p> <p>Temporary tables do not appear in the SQLITE_MASTER table. Temporary tables and their indices and triggers occur in another special table named SQLITE_TEMP_MASTER. SQLITE_TEMP_MASTER works just like SQLITE_MASTER except that it is only visible to the application that created the temporary tables. To get a list of all tables, both permanent and temporary, one can use a command similar to the following: <blockquote><pre> SELECT name FROM (SELECT * FROM sqlite_master UNION ALL SELECT * FROM sqlite_temp_master) WHERE type='table' ORDER BY name </pre></blockquote> } faq { Are there any known size limits to SQLite databases? } { <p>See <a href="limits.html">limits.html</a> for a full discussion of the limits of SQLite.</p> } faq { What is the maximum size of a VARCHAR in SQLite? } { <p>SQLite does not enforce the length of a VARCHAR. You can declare a VARCHAR(10) and SQLite will be happy to let you put 500 characters in it. And it will keep all 500 characters intact - it never truncates. </p> } faq { Does SQLite support a BLOB type? } { <p>SQLite versions 3.0 and later allow you to store BLOB data in any column, even columns that are declared to hold some other type.</p> } faq { How do I add or delete columns from an existing table in SQLite. } { <p>SQLite has limited <a href="lang_altertable.html">ALTER TABLE</a> support that you can use to add a column to the end of a table or to change the name of a table. If you what make more complex changes the structure of a table, you will have to recreate the table. You can save existing data to a temporary table, drop the old table, create the new table, then copy the data back in from the temporary table.</p> <p>For example, suppose you have a table named "t1" with columns names "a", "b", and "c" and that you want to delete column "c" from this table. The following steps illustrate how this could be done: </p> <blockquote><pre> BEGIN TRANSACTION; CREATE TEMPORARY TABLE t1_backup(a,b); INSERT INTO t1_backup SELECT a,b FROM t1; DROP TABLE t1; CREATE TABLE t1(a,b); INSERT INTO t1 SELECT a,b FROM t1_backup; DROP TABLE t1_backup; COMMIT; </pre></blockquote> } faq { I deleted a lot of data but the database file did not get any smaller. Is this a bug? } { <p>No. When you delete information from an SQLite database, the unused disk space is added to an internal "free-list" and is reused the next time you insert data. The disk space is not lost. But neither is it returned to the operating system.</p> <p>If you delete a lot of data and want to shrink the database file, run the <a href="lang_vacuum.html">VACUUM</a> command. VACUUM will reconstruct the database from scratch. This will leave the database with an empty free-list and a file that is minimal in size. Note, however, that the VACUUM can take some time to run (around a half second per megabyte on the Linux box where SQLite is developed) and it can use up to twice as much temporary disk space as the original file while it is running. </p> <p>As of SQLite version 3.1, an alternative to using the VACUUM command is auto-vacuum mode, enabled using the <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>.</p> } faq { Can I use SQLite in my commercial product without paying royalties? } { <p>Yes. SQLite is in the <a href="copyright.html">public domain</a>. No claim of ownership is made to any part of the code. You can do anything you want with it.</p> } faq { How do I use a string literal that contains an embedded single-quote (') character? } { <p>The SQL standard specifies that single-quotes in strings are escaped by putting two single quotes in a row. SQL works like the Pascal programming language in the regard. SQLite follows this standard. Example: </p> <blockquote><pre> INSERT INTO xyz VALUES('5 O''clock'); </pre></blockquote> } faq {What is an SQLITE_SCHEMA error, and why am I getting one?} { <p>An SQLITE_SCHEMA error is returned when a prepared SQL statement is no longer valid and cannot be executed. When this occurs, the statement must be recompiled from SQL using the <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a> API. In SQLite version 3, an SQLITE_SCHEMA error can only occur when using the <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a> API to execute SQL, not when using the <a href="capi3ref.html#sqlite3_exec">sqlite3_exec()</a>. This was not the case in version 2.</p> <p>The most common reason for a prepared statement to become invalid is that the schema of the database was modified after the SQL was prepared (possibly by another process). The other reasons this can happen are:</p> <ul> <li>A database was <a href="lang_detach.html">DETACH</a>ed. <li>The database was <a href="lang_vacuum.html">VACUUM</a>ed <li>A user-function definition was deleted or changed. <li>A collation sequence definition was deleted or changed. <li>The authorization function was changed. </ul> <p>In all cases, the solution is to recompile the statement from SQL and attempt to execute it again. Because a prepared statement can be invalidated by another process changing the database schema, all code that uses the <a href="capi3ref.html#sqlite3_prepare">sqlite3_prepare()</a>/<a href="capi3ref.html#sqlite3_step">sqlite3_step()</a>/<a href="capi3ref.html#sqlite3_finalize">sqlite3_finalize()</a> API should be prepared to handle SQLITE_SCHEMA errors. An example of one approach to this follows:</p> <blockquote><pre> int rc; sqlite3_stmt *pStmt; char zSql[] = "SELECT ....."; do { /* Compile the statement from SQL. Assume success. */ sqlite3_prepare(pDb, zSql, -1, &pStmt, 0); while( SQLITE_ROW==sqlite3_step(pStmt) ){ /* Do something with the row of available data */ } /* Finalize the statement. If an SQLITE_SCHEMA error has ** occured, then the above call to sqlite3_step() will have ** returned SQLITE_ERROR. sqlite3_finalize() will return ** SQLITE_SCHEMA. In this case the loop will execute again. */ rc = sqlite3_finalize(pStmt); } while( rc==SQLITE_SCHEMA ); </pre></blockquote> } faq {Why does ROUND(9.95,1) return 9.9 instead of 10.0? Shouldn't 9.95 round up?} { <p>SQLite uses binary arithmetic and in binary, there is no way to write 9.95 in a finite number of bits. The closest to you can get to 9.95 in a 64-bit IEEE float (which is what SQLite uses) is 9.949999999999999289457264239899814128875732421875. So when you type "9.95", SQLite really understands the number to be the much longer value shown above. And that value rounds down.</p> <p>This kind of problem comes up all the time when dealing with floating point binary numbers. The general rule to remember is that most fractional numbers that have a finite representation in decimal (a.k.a "base-10") do not have a finite representation in binary (a.k.a "base-2"). And so they are approximated using the closest binary number available. That approximation is usually very close, but it will be slightly off and in some cases can cause your results to be a little different from what you might expect.</p> } # End of questions and answers. ############# puts {<h2>Frequently Asked Questions</h2>} # puts {<DL COMPACT>} # for {set i 1} {$i<$cnt} {incr i} { # puts " <DT><A HREF=\"#q$i\">($i)</A></DT>" # puts " <DD>[lindex $faq($i) 0]</DD>" # } # puts {</DL>} puts {<OL>} for {set i 1} {$i<$cnt} {incr i} { puts "<li><a href=\"#q$i\">[lindex $faq($i) 0]</a></li>" } puts {</OL>} for {set i 1} {$i<$cnt} {incr i} { puts "<A NAME=\"q$i\"></A><HR />" puts "<P><B>($i) [lindex $faq($i) 0]</B></P>\n" puts "<BLOCKQUOTE>[lindex $faq($i) 1]</BLOCKQUOTE></LI>\n" } puts {</OL>} </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 | <title>SQLite Database File Format (Version 2)</title> <h2>SQLite 2.X Database File Format</h2> <p> This document describes the disk file format for SQLite versions 2.1 through 2.8. SQLite version 3.0 and following uses a very different format which is described separately. </p> <h3>1.0 Layers</h3> <p> SQLite is implemented in layers. (See the <a href="arch.html">architecture description</a>.) The format of database files is determined by three different layers in the architecture. </p> <ul> <li>The <b>schema</b> layer implemented by the VDBE.</li> <li>The <b>b-tree</b> layer implemented by btree.c</li> <li>The <b>pager</b> layer implemented by pager.c</li> </ul> <p> We will describe each layer beginning with the bottom (pager) layer and working upwards. </p> <h3>2.0 The Pager Layer</h3> <p> An SQLite database consists of "pages" of data. Each page is 1024 bytes in size. Pages are numbered beginning with 1. A page number of 0 is used to indicate "no such page" in the B-Tree and Schema layers. </p> <p> The pager layer is responsible for implementing transactions with atomic commit and rollback. It does this using a separate journal file. Whenever a new transaction is started, a journal file is created that records the original state of the database. If the program terminates before completing the transaction, the next process to open the database can use the journal file to restore the database to its original state. </p> <p> The journal file is located in the same directory as the database file and has the same name as the database file but with the characters "<tt>-journal</tt>" appended. </p> <p> The pager layer does not impose any content restrictions on the main database file. As far as the pager is concerned, each page contains 1024 bytes of arbitrary data. But there is structure to the journal file. </p> <p> A journal file begins with 8 bytes as follows: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, and 0xd6. Processes that are attempting to rollback a journal use these 8 bytes as a sanity check to make sure the file they think is a journal really is a valid journal. Prior version of SQLite used different journal file formats. The magic numbers for these prior formats are different so that if a new version of the library attempts to rollback a journal created by an earlier version, it can detect that the journal uses an obsolete format and make the necessary adjustments. This article describes only the newest journal format - supported as of version 2.8.0. </p> <p> Following the 8 byte prefix is a three 4-byte integers that tell us the number of pages that have been committed to the journal, a magic number used for sanity checking each page, and the original size of the main database file before the transaction was started. The number of committed pages is used to limit how far into the journal to read. The use of the checksum magic number is described below. The original size of the database is used to restore the database file back to its original size. The size is expressed in pages (1024 bytes per page). </p> <p> All three integers in the journal header and all other multi-byte numbers used in the journal file are big-endian. That means that the most significant byte occurs first. That way, a journal file that is originally created on one machine can be rolled back by another machine that uses a different byte order. So, for example, a transaction that failed to complete on your big-endian SparcStation can still be rolled back on your little-endian Linux box. </p> <p> After the 8-byte prefix and the three 4-byte integers, the journal file consists of zero or more page records. Each page record is a 4-byte (big-endian) page number followed by 1024 bytes of data and a 4-byte checksum. The data is the original content of the database page before the transaction was started. So to roll back the transaction, the data is simply written into the corresponding page of the main database file. Pages can appear in the journal in any order, but they are guaranteed to appear only once. All page numbers will be between 1 and the maximum specified by the page size integer that appeared at the beginning of the journal. </p> <p> The so-called checksum at the end of each record is not really a checksum - it is the sum of the page number and the magic number which was the second integer in the journal header. The purpose of this value is to try to detect journal corruption that might have occurred because of a power loss or OS crash that occurred which the journal file was being written to disk. It could have been the case that the meta-data for the journal file, specifically the size of the file, had been written to the disk so that when the machine reboots it appears that file is large enough to hold the current record. But even though the file size has changed, the data for the file might not have made it to the disk surface at the time of the OS crash or power loss. This means that after reboot, the end of the journal file will contain quasi-random garbage data. The checksum is an attempt to detect such corruption. If the checksum does not match, that page of the journal is not rolled back. </p> <p> Here is a summary of the journal file format: </p> <ul> <li>8 byte prefix: 0xd9, 0xd5, 0x05, 0xf9, 0x20, 0xa1, 0x63, 0xd6</li> <li>4 byte number of records in journal</li> <li>4 byte magic number used for page checksums</li> <li>4 byte initial database page count</li> <li>Zero or more instances of the following: <ul> <li>4 byte page number</li> <li>1024 bytes of original data for the page</li> <li>4 byte checksum</li> </ul> </li> </ul> <h3>3.0 The B-Tree Layer</h3> <p> The B-Tree layer builds on top of the pager layer to implement one or more separate b-trees all in the same disk file. The algorithms used are taken from Knuth's <i>The Art Of Computer Programming.</i></p> <p> Page 1 of a database contains a header string used for sanity checking, a few 32-bit words of configuration data, and a pointer to the beginning of a list of unused pages in the database. All other pages in the database are either pages of a b-tree, overflow pages, or unused pages on the freelist. </p> <p> Each b-tree page contains zero or more database entries. Each entry has an unique key of one or more bytes and data of zero or more bytes. Both the key and data are arbitrary byte sequences. The combination of key and data are collectively known as "payload". The current implementation limits the amount of payload in a single entry to 1048576 bytes. This limit can be raised to 16777216 by adjusting a single #define in the source code and recompiling. But most entries contain less than a hundred bytes of payload so a megabyte limit seems more than enough. </p> <p> Up to 238 bytes of payload for an entry can be held directly on a b-tree page. Any additional payload is contained on a linked list of overflow pages. This limit on the amount of payload held directly on b-tree pages guarantees that each b-tree page can hold at least 4 entries. In practice, most entries are smaller than 238 bytes and thus most pages can hold more than 4 entries. </p> <p> A single database file can hold any number of separate, independent b-trees. Each b-tree is identified by its root page, which never changes. Child pages of the b-tree may change as entries are added and removed and pages split and combine. But the root page always stays the same. The b-tree itself does not record which pages are root pages and which are not. That information is handled entirely at the schema layer. </p> <h4>3.1 B-Tree Page 1 Details</h4> <p> Page 1 begins with the following 48-byte string: </p> <blockquote><pre> ** This file contains an SQLite 2.1 database ** </pre></blockquote> <p> If you count the number of characters in the string above, you will see that there are only 47. A '\000' terminator byte is added to bring the total to 48. </p> <p> A frequent question is why the string says version 2.1 when (as of this writing) we are up to version 2.7.0 of SQLite and any change to the second digit of the version is suppose to represent a database format change. The answer to this is that the B-tree layer has not changed any since version 2.1. There have been database format changes since version 2.1 but those changes have all been in the schema layer. Because the format of the b-tree layer is unchanged since version 2.1.0, the header string still says version 2.1. </p> <p> After the format string is a 4-byte integer used to determine the byte-order of the database. The integer has a value of 0xdae37528. If this number is expressed as 0xda, 0xe3, 0x75, 0x28, then the database is in a big-endian format and all 16 and 32-bit integers elsewhere in the b-tree layer are also big-endian. If the number is expressed as 0x28, 0x75, 0xe3, and 0xda, then the database is in a little-endian format and all other multi-byte numbers in the b-tree layer are also little-endian. Prior to version 2.6.3, the SQLite engine was only able to read databases that used the same byte order as the processor they were running on. But beginning with 2.6.3, SQLite can read or write databases in any byte order. </p> <p> After the byte-order code are six 4-byte integers. Each integer is in the byte order determined by the byte-order code. The first integer is the page number for the first page of the freelist. If there are no unused pages in the database, then this integer is 0. The second integer is the number of unused pages in the database. The last 4 integers are not used by the b-tree layer. These are the so-called "meta" values that are passed up to the schema layer and used there for configuration and format version information. All bytes of page 1 past beyond the meta-value integers are unused and are initialized to zero. </p> <p> Here is a summary of the information contained on page 1 in the b-tree layer: </p> <ul> <li>48 byte header string</li> <li>4 byte integer used to determine the byte-order</li> <li>4 byte integer which is the first page of the freelist</li> <li>4 byte integer which is the number of pages on the freelist</li> <li>36 bytes of meta-data arranged as nine 4-byte integers</li> <li>928 bytes of unused space</li> </ul> <h4>3.2 Structure Of A Single B-Tree Page</h4> <p> Conceptually, a b-tree page contains N database entries and N+1 pointers to other b-tree pages. </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center">Ptr<br>0</td> <td align="center">Entry<br>0</td> <td align="center">Ptr<br>1</td> <td align="center">Entry<br>1</td> <td align="center"><b>...</b></td> <td align="center">Ptr<br>N-1</td> <td align="center">Entry<br>N-1</td> <td align="center">Ptr<br>N</td> </tr> </table> </blockquote> <p> The entries are arranged in increasing order. That is, the key to Entry 0 is less than the key to Entry 1, and the key to Entry 1 is less than the key of Entry 2, and so forth. The pointers point to pages containing additional entries that have keys in between the entries on either side. So Ptr 0 points to another b-tree page that contains entries that all have keys less than Key 0, and Ptr 1 points to a b-tree pages where all entries have keys greater than Key 0 but less than Key 1, and so forth. </p> <p> Each b-tree page in SQLite consists of a header, zero or more "cells" each holding a single entry and pointer, and zero or more "free blocks" that represent unused space on the page. </p> <p> The header on a b-tree page is the first 8 bytes of the page. The header contains the value of the right-most pointer (Ptr N) and the byte offset into the page of the first cell and the first free block. The pointer is a 32-bit value and the offsets are each 16-bit values. We have: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center" width=30>0</td> <td align="center" width=30>1</td> <td align="center" width=30>2</td> <td align="center" width=30>3</td> <td align="center" width=30>4</td> <td align="center" width=30>5</td> <td align="center" width=30>6</td> <td align="center" width=30>7</td> </tr> <tr> <td align="center" colspan=4>Ptr N</td> <td align="center" colspan=2>Cell 0</td> <td align="center" colspan=2>Freeblock 0</td> </tr> </table> </blockquote> <p> The 1016 bytes of a b-tree page that come after the header contain cells and freeblocks. All 1016 bytes are covered by either a cell or a freeblock. </p> <p> The cells are connected in a linked list. Cell 0 contains Ptr 0 and Entry 0. Bytes 4 and 5 of the header point to Cell 0. Cell 0 then points to Cell 1 which contains Ptr 1 and Entry 1. And so forth. Cells vary in size. Every cell has a 12-byte header and at least 4 bytes of payload space. Space is allocated to payload in increments of 4 bytes. Thus the minimum size of a cell is 16 bytes and up to 63 cells can fit on a single page. The size of a cell is always a multiple of 4 bytes. A cell can have up to 238 bytes of payload space. If the payload is more than 238 bytes, then an additional 4 byte page number is appended to the cell which is the page number of the first overflow page containing the additional payload. The maximum size of a cell is thus 254 bytes, meaning that a least 4 cells can fit into the 1016 bytes of space available on a b-tree page. An average cell is usually around 52 to 100 bytes in size with about 10 or 20 cells to a page. </p> <p> The data layout of a cell looks like this: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center" width=20>0</td> <td align="center" width=20>1</td> <td align="center" width=20>2</td> <td align="center" width=20>3</td> <td align="center" width=20>4</td> <td align="center" width=20>5</td> <td align="center" width=20>6</td> <td align="center" width=20>7</td> <td align="center" width=20>8</td> <td align="center" width=20>9</td> <td align="center" width=20>10</td> <td align="center" width=20>11</td> <td align="center" width=100>12 ... 249</td> <td align="center" width=20>250</td> <td align="center" width=20>251</td> <td align="center" width=20>252</td> <td align="center" width=20>253</td> </tr> <tr> <td align="center" colspan=4>Ptr</td> <td align="center" colspan=2>Keysize<br>(low)</td> <td align="center" colspan=2>Next</td> <td align="center" colspan=1>Ksz<br>(hi)</td> <td align="center" colspan=1>Dsz<br>(hi)</td> <td align="center" colspan=2>Datasize<br>(low)</td> <td align="center" colspan=1>Payload</td> <td align="center" colspan=4>Overflow<br>Pointer</td> </tr> </table> </blockquote> <p> The first four bytes are the pointer. The size of the key is a 24-bit where the upper 8 bits are taken from byte 8 and the lower 16 bits are taken from bytes 4 and 5 (or bytes 5 and 4 on little-endian machines.) The size of the data is another 24-bit value where the upper 8 bits are taken from byte 9 and the lower 16 bits are taken from bytes 10 and 11 or 11 and 10, depending on the byte order. Bytes 6 and 7 are the offset to the next cell in the linked list of all cells on the current page. This offset is 0 for the last cell on the page. </p> <p> The payload itself can be any number of bytes between 1 and 1048576. But space to hold the payload is allocated in 4-byte chunks up to 238 bytes. If the entry contains more than 238 bytes of payload, then additional payload data is stored on a linked list of overflow pages. A 4 byte page number is appended to the cell that contains the first page of this linked list. </p> <p> Each overflow page begins with a 4-byte value which is the page number of the next overflow page in the list. This value is 0 for the last page in the list. The remaining 1020 bytes of the overflow page are available for storing payload. Note that a full page is allocated regardless of the number of overflow bytes stored. Thus, if the total payload for an entry is 239 bytes, the first 238 are stored in the cell and the overflow page stores just one byte. </p> <p> The structure of an overflow page looks like this: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center" width=20>0</td> <td align="center" width=20>1</td> <td align="center" width=20>2</td> <td align="center" width=20>3</td> <td align="center" width=200>4 ... 1023</td> </tr> <tr> <td align="center" colspan=4>Next Page</td> <td align="center" colspan=1>Overflow Data</td> </tr> </table> </blockquote> <p> All space on a b-tree page which is not used by the header or by cells is filled by freeblocks. Freeblocks, like cells, are variable in size. The size of a freeblock is at least 4 bytes and is always a multiple of 4 bytes. The first 4 bytes contain a header and the remaining bytes are unused. The structure of the freeblock is as follows: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center" width=20>0</td> <td align="center" width=20>1</td> <td align="center" width=20>2</td> <td align="center" width=20>3</td> <td align="center" width=200>4 ... 1015</td> </tr> <tr> <td align="center" colspan=2>Size</td> <td align="center" colspan=2>Next</td> <td align="center" colspan=1>Unused</td> </tr> </table> </blockquote> <p> Freeblocks are stored in a linked list in increasing order. That is to say, the first freeblock occurs at a lower index into the page than the second free block, and so forth. The first 2 bytes of the header are an integer which is the total number of bytes in the freeblock. The second 2 bytes are the index into the page of the next freeblock in the list. The last freeblock has a Next value of 0. </p> <p> When a new b-tree is created in a database, the root page of the b-tree consist of a header and a single 1016 byte freeblock. As entries are added, space is carved off of that freeblock and used to make cells. When b-tree entries are deleted, the space used by their cells is converted into freeblocks. Adjacent freeblocks are merged, but the page can still become fragmented. The b-tree code will occasionally try to defragment the page by moving all cells to the beginning and constructing a single freeblock at the end to take up all remaining space. </p> <h4>3.3 The B-Tree Free Page List</h4> <p> When information is removed from an SQLite database such that one or more pages are no longer needed, those pages are added to a list of free pages so that they can be reused later when new information is added. This subsection describes the structure of this freelist. </p> <p> The 32-bit integer beginning at byte-offset 52 in page 1 of the database contains the address of the first page in a linked list of free pages. If there are no free pages available, this integer has a value of 0. The 32-bit integer at byte-offset 56 in page 1 contains the number of free pages on the freelist. </p> <p> The freelist contains a trunk and many branches. The trunk of the freelist is composed of overflow pages. That is to say, each page contains a single 32-bit integer at byte offset 0 which is the page number of the next page on the freelist trunk. The payload area of each trunk page is used to record pointers to branch pages. The first 32-bit integer in the payload area of a trunk page is the number of branch pages to follow (between 0 and 254) and each subsequent 32-bit integer is a page number for a branch page. The following diagram shows the structure of a trunk freelist page: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td align="center" width=20>0</td> <td align="center" width=20>1</td> <td align="center" width=20>2</td> <td align="center" width=20>3</td> <td align="center" width=20>4</td> <td align="center" width=20>5</td> <td align="center" width=20>6</td> <td align="center" width=20>7</td> <td align="center" width=200>8 ... 1023</td> </tr> <tr> <td align="center" colspan=4>Next trunk page</td> <td align="center" colspan=4># of branch pages</td> <td align="center" colspan=1>Page numbers for branch pages</td> </tr> </table> </blockquote> <p> It is important to note that only the pages on the trunk of the freelist contain pointers to other pages. The branch pages contain no data whatsoever. The fact that the branch pages are completely blank allows for an important optimization in the paging layer. When a branch page is removed from the freelist to be reused, it is not necessary to write the original content of that page into the rollback journal. The branch page contained no data to begin with, so there is no need to restore the page in the event of a rollback. Similarly, when a page is not longer needed and is added to the freelist as a branch page, it is not necessary to write the content of that page into the database file. Again, the page contains no real data so it is not necessary to record the content of that page. By reducing the amount of disk I/O required, these two optimizations allow some database operations to go four to six times faster than they would otherwise. </p> <h3>4.0 The Schema Layer</h3> <p> The schema layer implements an SQL database on top of one or more b-trees and keeps track of the root page numbers for all b-trees. Where the b-tree layer provides only unformatted data storage with a unique key, the schema layer allows each entry to contain multiple columns. The schema layer also allows indices and non-unique key values. </p> <p> The schema layer implements two separate data storage abstractions: tables and indices. Each table and each index uses its own b-tree but they use the b-tree capabilities in different ways. For a table, the b-tree key is a unique 4-byte integer and the b-tree data is the content of the table row, encoded so that columns can be separately extracted. For indices, the b-tree key varies in size depending on the size of the fields being indexed and the b-tree data is empty. </p> <h4>4.1 SQL Table Implementation Details</h4> <p>Each row of an SQL table is stored in a single b-tree entry. The b-tree key is a 4-byte big-endian integer that is the ROWID or INTEGER PRIMARY KEY for that table row. The key is stored in a big-endian format so that keys will sort in numerical order using memcmp() function.</p> <p>The content of a table row is stored in the data portion of the corresponding b-tree table. The content is encoded to allow individual columns of the row to be extracted as necessary. Assuming that the table has N columns, the content is encoded as N+1 offsets followed by N column values, as follows: </p> <blockquote> <table border=1 cellspacing=0 cellpadding=5> <tr> <td>offset 0</td> <td>offset 1</td> <td><b>...</b></td> <td>offset N-1</td> <td>offset N</td> <td>value 0</td> <td>value 1</td> <td><b>...</b></td> <td>value N-1</td> </tr> </table> </blockquote> <p> The offsets can be either 8-bit, 16-bit, or 24-bit integers depending on how much data is to be stored. If the total size of the content is less than 256 bytes then 8-bit offsets are used. If the total size of the b-tree data is less than 65536 then 16-bit offsets are used. 24-bit offsets are used otherwise. Offsets are always little-endian, which means that the least significant byte occurs first. </p> <p> Data is stored as a nul-terminated string. Any empty string consists of just the nul terminator. A NULL value is an empty string with no nul-terminator. Thus a NULL value occupies zero bytes and an empty string occupies 1 byte. </p> <p> Column values are stored in the order that they appear in the CREATE TABLE statement. The offsets at the beginning of the record contain the byte index of the corresponding column value. Thus, Offset 0 contains the byte index for Value 0, Offset 1 contains the byte offset of Value 1, and so forth. The number of bytes in a column value can always be found by subtracting offsets. This allows NULLs to be recovered from the record unambiguously. </p> <p> Most columns are stored in the b-tree data as described above. The one exception is column that has type INTEGER PRIMARY KEY. INTEGER PRIMARY KEY columns correspond to the 4-byte b-tree key. When an SQL statement attempts to read the INTEGER PRIMARY KEY, the 4-byte b-tree key is read rather than information out of the b-tree data. But there is still an Offset associated with the INTEGER PRIMARY KEY, just like any other column. But the Value associated with that offset is always NULL. </p> <h4>4.2 SQL Index Implementation Details</h4> <p> SQL indices are implement using a b-tree in which the key is used but the data is always empty. The purpose of an index is to map one or more column values into the ROWID for the table entry that contains those column values. </p> <p> Each b-tree in an index consists of one or more column values followed by a 4-byte ROWID. Each column value is nul-terminated (even NULL values) and begins with a single character that indicates the datatype for that column value. Only three datatypes are supported: NULL, Number, and Text. NULL values are encoded as the character 'a' followed by the nul terminator. Numbers are encoded as the character 'b' followed by a string that has been crafted so that sorting the string using memcmp() will sort the corresponding numbers in numerical order. (See the sqliteRealToSortable() function in util.c of the SQLite sources for additional information on this encoding.) Numbers are also nul-terminated. Text values consists of the character 'c' followed by a copy of the text string and a nul-terminator. These encoding rules result in NULLs being sorted first, followed by numerical values in numerical order, followed by text values in lexicographical order. </p> <h4>4.4 SQL Schema Storage And Root B-Tree Page Numbers</h4> <p> The database schema is stored in the database in a special tabled named "sqlite_master" and which always has a root b-tree page number of 2. This table contains the original CREATE TABLE, CREATE INDEX, CREATE VIEW, and CREATE TRIGGER statements used to define the database to begin with. Whenever an SQLite database is opened, the sqlite_master table is scanned from beginning to end and all the original CREATE statements are played back through the parser in order to reconstruct an in-memory representation of the database schema for use in subsequent command parsing. For each CREATE TABLE and CREATE INDEX statement, the root page number for the corresponding b-tree is also recorded in the sqlite_master table so that SQLite will know where to look for the appropriate b-tree. </p> <p> SQLite users can query the sqlite_master table just like any other table in the database. But the sqlite_master table cannot be directly written. The sqlite_master table is automatically updated in response to CREATE and DROP statements but it cannot be changed using INSERT, UPDATE, or DELETE statements as that would risk corrupting the database. </p> <p> SQLite stores temporary tables and indices in a separate file from the main database file. The temporary table database file is the same structure as the main database file. The schema table for the temporary tables is stored on page 2 just as in the main database. But the schema table for the temporary database named "sqlite_temp_master" instead of "sqlite_master". Other than the name change, it works exactly the same. </p> <h4>4.4 Schema Version Numbering And Other Meta-Information</h4> <p> The nine 32-bit integers that are stored beginning at byte offset 60 of Page 1 in the b-tree layer are passed up into the schema layer and used for versioning and configuration information. The meaning of the first four integers is shown below. The other five are currently unused. </p> <ol> <li>The schema version number</li> <li>The format version number</li> <li>The recommended pager cache size</li> <li>The safety level</li> </ol> <p> The first meta-value, the schema version number, is used to detect when the schema of the database is changed by a CREATE or DROP statement. Recall that when a database is first opened the sqlite_master table is scanned and an internal representation of the tables, indices, views, and triggers for the database is built in memory. This internal representation is used for all subsequent SQL command parsing and execution. But what if another process were to change the schema by adding or removing a table, index, view, or trigger? If the original process were to continue using the old schema, it could potentially corrupt the database by writing to a table that no longer exists. To avoid this problem, the schema version number is changed whenever a CREATE or DROP statement is executed. Before each command is executed, the current schema version number for the database file is compared against the schema version number from when the sqlite_master table was last read. If those numbers are different, the internal schema representation is erased and the sqlite_master table is reread to reconstruct the internal schema representation. (Calls to sqlite_exec() generally return SQLITE_SCHEMA when this happens.) </p> <p> The second meta-value is the schema format version number. This number tells what version of the schema layer should be used to interpret the file. There have been changes to the schema layer over time and this number is used to detect when an older database file is being processed by a newer version of the library. As of this writing (SQLite version 2.7.0) the current format version is "4". </p> <p> The third meta-value is the recommended pager cache size as set by the DEFAULT_CACHE_SIZE pragma. If the value is positive it means that synchronous behavior is enable (via the DEFAULT_SYNCHRONOUS pragma) and if negative it means that synchronous behavior is disabled. </p> <p> The fourth meta-value is safety level added in version 2.8.0. A value of 1 corresponds to a SYNCHRONOUS setting of OFF. In other words, SQLite does not pause to wait for journal data to reach the disk surface before overwriting pages of the database. A value of 2 corresponds to a SYNCHRONOUS setting of NORMAL. A value of 3 corresponds to a SYNCHRONOUS setting of FULL. If the value is 0, that means it has not been initialized so the default synchronous setting of NORMAL is used. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 | <title>File Format Changes in SQLite</title> <h2>File Format Changes in SQLite</h2> <p> Every effort is made to keep SQLite fully backwards compatible from one release to the next. Rarely, however, some enhancements or bug fixes may require a change to the underlying file format. When this happens and you must convert the contents of your databases into a portable ASCII representation using the old version of the library then reload the data using the new version of the library. </p> <p> You can tell if you should reload your databases by comparing the version numbers of the old and new libraries. If the first digit of the version number is different, then a reload of the database will be required. If the second digit changes, newer versions of SQLite will be able to read and write older database files, but older versions of the library may have difficulty reading or writing newer database files. For example, upgrading from version 2.8.14 to 3.0.0 requires a reload. Going from version 3.0.8 to 3.1.0 is backwards compatible but not necessarily forwards compatible. </p> <p> The following table summarizes the SQLite file format changes that have occurred since version 1.0.0: </p> <blockquote> <table border=2 cellpadding=5> <tr> <th>Version Change</th> <th>Approx. Date</th> <th>Description Of File Format Change</th> </tr> <tr> <td valign="top">1.0.32 to 2.0.0</td> <td valign="top">2001-Sep-20</td> <td>Version 1.0.X of SQLite used the GDBM library as its backend interface to the disk. Beginning in version 2.0.0, GDBM was replaced by a custom B-Tree library written especially for SQLite. The new B-Tree backend is twice as fast as GDBM, supports atomic commits and rollback, and stores an entire database in a single disk file instead using a separate file for each table as GDBM does. The two file formats are not even remotely similar.</td> </tr> <tr> <td valign="top">2.0.8 to 2.1.0</td> <td valign="top">2001-Nov-12</td> <td>The same basic B-Tree format is used but the details of the index keys were changed in order to provide better query optimization opportunities. Some of the headers were also changed in order to increase the maximum size of a row from 64KB to 24MB.<p> This change is an exception to the version number rule described above in that it is neither forwards or backwards compatible. A complete reload of the database is required. This is the only exception.</td> </tr> <tr> <td valign="top">2.1.7 to 2.2.0</td> <td valign="top">2001-Dec-21</td> <td>Beginning with version 2.2.0, SQLite no longer builds an index for an INTEGER PRIMARY KEY column. Instead, it uses that column as the actual B-Tree key for the main table.<p>Version 2.2.0 and later of the library will automatically detect when it is reading a 2.1.x database and will disable the new INTEGER PRIMARY KEY feature. In other words, version 2.2.x is backwards compatible to version 2.1.x. But version 2.1.x is not forward compatible with version 2.2.x. If you try to open a 2.2.x database with an older 2.1.x library and that database contains an INTEGER PRIMARY KEY, you will likely get a coredump. If the database schema does not contain any INTEGER PRIMARY KEYs, then the version 2.1.x and version 2.2.x database files will be identical and completely interchangeable.</p> </tr> <tr> <td valign="top">2.2.5 to 2.3.0</td> <td valign="top">2002-Jan-30</td> <td>Beginning with version 2.3.0, SQLite supports some additional syntax (the "ON CONFLICT" clause) in the CREATE TABLE and CREATE INDEX statements that are stored in the SQLITE_MASTER table. If you create a database that contains this new syntax, then try to read that database using version 2.2.5 or earlier, the parser will not understand the new syntax and you will get an error. Otherwise, databases for 2.2.x and 2.3.x are interchangeable.</td> </tr> <tr> <td valign="top">2.3.3 to 2.4.0</td> <td valign="top">2002-Mar-10</td> <td>Beginning with version 2.4.0, SQLite added support for views. Information about views is stored in the SQLITE_MASTER table. If an older version of SQLite attempts to read a database that contains VIEW information in the SQLITE_MASTER table, the parser will not understand the new syntax and initialization will fail. Also, the way SQLite keeps track of unused disk blocks in the database file changed slightly. If an older version of SQLite attempts to write a database that was previously written by version 2.4.0 or later, then it may leak disk blocks.</td> </tr> <tr> <td valign="top">2.4.12 to 2.5.0</td> <td valign="top">2002-Jun-17</td> <td>Beginning with version 2.5.0, SQLite added support for triggers. Information about triggers is stored in the SQLITE_MASTER table. If an older version of SQLite attempts to read a database that contains a CREATE TRIGGER in the SQLITE_MASTER table, the parser will not understand the new syntax and initialization will fail. </td> </tr> <tr> <td valign="top">2.5.6 to 2.6.0</td> <td valign="top">2002-July-17</td> <td>A design flaw in the layout of indices required a file format change to correct. This change appeared in version 2.6.0.<p> If you use version 2.6.0 or later of the library to open a database file that was originally created by version 2.5.6 or earlier, an attempt to rebuild the database into the new format will occur automatically. This can take some time for a large database. (Allow 1 or 2 seconds per megabyte of database under Unix - longer under Windows.) This format conversion is irreversible. It is <strong>strongly</strong> suggested that you make a backup copy of older database files prior to opening them with version 2.6.0 or later of the library, in case there are errors in the format conversion logic.<p> Version 2.6.0 or later of the library cannot open read-only database files from version 2.5.6 or earlier, since read-only files cannot be upgraded to the new format.</p> </td> </tr> <tr> <td valign="top">2.6.3 to 2.7.0</td> <td valign="top">2002-Aug-13</td> <td><p>Beginning with version 2.7.0, SQLite understands two different datatypes: text and numeric. Text data sorts in memcmp() order. Numeric data sorts in numerical order if it looks like a number, or in memcmp() order if it does not.</p> <p>When SQLite version 2.7.0 or later opens a 2.6.3 or earlier database, it assumes all columns of all tables have type "numeric". For 2.7.0 and later databases, columns have type "text" if their datatype string contains the substrings "char" or "clob" or "blob" or "text". Otherwise they are of type "numeric".</p> <p>Because "text" columns have a different sort order from numeric, indices on "text" columns occur in a different order for version 2.7.0 and later database. Hence version 2.6.3 and earlier of SQLite will be unable to read a 2.7.0 or later database. But version 2.7.0 and later of SQLite will read earlier databases.</p> </td> </tr> <tr> <td valign="top">2.7.6 to 2.8.0</td> <td valign="top">2003-Feb-14</td> <td><p>Version 2.8.0 introduces a change to the format of the rollback journal file. The main database file format is unchanged. Versions 2.7.6 and earlier can read and write 2.8.0 databases and vice versa. Version 2.8.0 can rollback a transaction that was started by version 2.7.6 and earlier. But version 2.7.6 and earlier cannot rollback a transaction started by version 2.8.0 or later.</p> <p>The only time this would ever be an issue is when you have a program using version 2.8.0 or later that crashes with an incomplete transaction, then you try to examine the database using version 2.7.6 or earlier. The 2.7.6 code will not be able to read the journal file and thus will not be able to rollback the incomplete transaction to restore the database.</p> </td> </tr> <tr> <td valign="top">2.8.14 to 3.0.0</td> <td valign="top">2004-Jun-18</td> <td><p>Version 3.0.0 is a major upgrade for SQLite that incorporates support for UTF-16, BLOBs, and a more compact encoding that results in database files that are typically 25% to 50% smaller. The new file format is very different and is completely incompatible with the version 2 file format.</p> </td> </tr> <tr> <td valign="top">3.0.8 to 3.1.0</td> <td valign="top">2005-Jan-21</td> <td><p>Version 3.1.0 adds support for <a href="pragma.html#pragma_auto_vacuum">autovacuum mode</a>. Prior versions of SQLite will be able to read an autovacuumed database but will not be able to write it. If autovaccum is disabled (which is the default condition) then databases are fully forwards and backwards compatible.</p> </td> </tr> <tr> <td valign="top">3.1.6 to 3.2.0</td> <td valign="top">2005-Mar-19</td> <td><p>Version 3.2.0 adds support for the <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a> command. A database that has been modified by this command can not be read by a version of SQLite prior to 3.1.4. Running <a href="lang_vacuum.html">VACUUM</a> after the ALTER TABLE restores the database to a format such that it can be read by earlier SQLite versions.</p> </td> </tr> <tr> <td valign="top">3.2.8 to 3.3.0</td> <td valign="top">2006-Jan-10</td> <td><p>Version 3.3.0 adds support for descending indices and uses a new encoding for boolean values that requires less disk space. Version 3.3.0 can read and write database files created by prior versions of SQLite. But prior versions of SQLite will not be able to read or write databases created by Version 3.3.0</p> <p>If you need backwards and forwards capatibility, you can compile with -DSQLITE_DEFAULT_FILE_FORMAT=1. Or at runtime you can say "PRAGMA legacy_file_format=ON" prior to creating a new database file</p> <p>Once a database file is created, its format is fixed. So a database file created by SQLite 3.2.8 and merely modified by version 3.3.0 or later will retain the old format. Except, the VACUUM command recreates the database so running VACUUM on 3.3.0 or later will change the file format to the latest edition.</p> </td> </tr> <tr> <td valign="top">3.3.6 to 3.3.7</td> <td valign="top">2006-Aug-12</td> <td><p>The previous file format change has caused so much grief that the default behavior has been changed back to the original file format. This means that DESC option on indices is ignored by default that the more efficient encoding of boolean values is not used. In that way, older versions of SQLite can read and write databases created by newer versions. If the new features are desired, they can be enabled using pragma: "PRAGMA legacy_file_format=OFF".</p> <p>To be clear: both old and new file formats continue to be understood and continue to work. But the old file format is used by default instead of the new. This might change again in some future release - we may go back to generating the new file format by default - but probably not until all users have upgraded to a version of SQLite that will understand the new file format. That might take several years.</p></td> </tr> <tr> <td valign="top">3.4.2 to 3.5.0</td> <td valign="top">2007-Sep-3</td> <td><p>The design of the OS interface layer was changed for release 3.5.0. Applications that implemented a custom OS interface will need to be modified in order to upgrade. There are also some subtly different semantics a few obscure APIs. An <a href="34to35.html">article</a> is avilable which describing the changes in detail.</p> <p>The on-disk file format is unchanged.</p> </td> </tr> </table> </blockquote> <p> To perform a database reload, have ready versions of the <b>sqlite</b> command-line utility for both the old and new version of SQLite. Call these two executables "<b>sqlite-old</b>" and "<b>sqlite-new</b>". Suppose the name of your old database is "<b>old.db</b>" and you want to create a new database with the same information named "<b>new.db</b>". The command to do this is as follows: </p> <blockquote> sqlite-old old.db .dump | sqlite-new new.db </blockquote> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 | <title>SQLite Home Page</title> <table border="0" cellspacing="20"> <tr><td valign="top"> <b>About Sqlite</b> </td><td valign="top"> <li>SQLite is a C-library that implements a high-efficiency, transactional SQL database engine using databases stored in ordinary disk files. <a href="about.html">More info...</a></li> </td></tr> <tr><td valign="top"> <b>Current Status</b> </td><td valign="top"> <li><a href="download.html">Version 3.5.2</a> of SQLite is stable and is recommended for all users. There are no known issues effecting database integrity or correctness.</li> </td></tr> <tr><td valign="top"> <b>Recent News</b> </td><td valign="top"> <li> 2007-Nov-05: <a href="news.html">Version 3.5.2 released</a>. </li> <li> 2007-Oct-04: <a href="news.html">Version 3.5.1 released</a>. </li> <li> 2007-Sep-04: <a href="news.html">Version 3.5.0 released</a>. </li> </td></tr> <tr><td valign="top"> <b>Quick Links</b> </td><td valign="top"> <li> More details <a href="about.html">about SQLite</a> - what it is and what it is not.</li> <li> <a href="faq.html">Frequently Asked Questions</a> about SQLite. </li> <li> <a href="companiesusing.html">Well-known companies using SQLite in their products.</li> <li> <a href="http://www.sqlite.org/cvstrac/timeline">Timeline</a> of recent development activity. </li> </td></tr> </table> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 | <title>Query Language Understood by SQLite</title> <tcl> if 0 { if {[llength $argv]>0} { set outputdir [lindex $argv 0] } else { set outputdir "" } puts { <h1 class="pdf_section">SQL As Understood By SQLite</h1> <p>The SQLite library understands most of the standard SQL language. But it does <a href="omitted.html">omit some features</a> while at the same time adding a few features of its own. This document attempts to describe precisely what parts of the SQL language SQLite does and does not support. A list of <a href="lang_keywords.html">keywords</a> is also provided.</p> <p>In all of the syntax diagrams that follow, literal text is shown in bold blue. Non-terminal symbols are shown in italic red. Operators that are part of the syntactic markup itself are shown in black roman.</p> <p>This document is just an overview of the SQL syntax implemented by SQLite. Many low-level productions are omitted. For detailed information on the language that SQLite understands, refer to the source code and the grammar file "parse.y".</p> <div class="pdf_ignore"> <p>SQLite implements the follow syntax:</p> <p><ul> } proc slink {label} { if {[string match *.html $label]} { return $label } if {[string length $::outputdir]==0} { return #$label } else { return lang_$label.html } } foreach {section} [lsort -index 0 -dictionary { {{CREATE TABLE} createtable} {{CREATE VIRTUAL TABLE} createvtab} {{CREATE INDEX} createindex} {VACUUM vacuum} {{DROP TABLE} droptable} {{DROP INDEX} dropindex} {INSERT insert} {REPLACE replace} {DELETE delete} {UPDATE update} {SELECT select} {comment comment} {COPY copy} {EXPLAIN explain} {expression expr} {{BEGIN TRANSACTION} transaction} {{COMMIT TRANSACTION} transaction} {{END TRANSACTION} transaction} {{ROLLBACK TRANSACTION} transaction} {PRAGMA pragma.html} {{ON CONFLICT clause} conflict} {{CREATE VIEW} createview} {{DROP VIEW} dropview} {{CREATE TRIGGER} createtrigger} {{DROP TRIGGER} droptrigger} {{ATTACH DATABASE} attach} {{DETACH DATABASE} detach} {REINDEX reindex} {{ALTER TABLE} altertable} {{ANALYZE} analyze} }] { foreach {s_title s_tag} $section {} puts "<li><a href=\"[slink $s_tag]\">$s_title</a></li>" } puts {</ul></p> </div> <p>Details on the implementation of each command are provided in the sequel.</p> } proc Operator {name} { return "<font color=\"#2c2cf0\"><big>$name</big></font>" } proc Nonterminal {name} { return "<i><font color=\"#ff3434\">$name</font></i>" } proc Keyword {name} { return "<font color=\"#2c2cf0\">$name</font>" } proc Example {text} { puts "<blockquote><pre>$text</pre></blockquote>" } proc Section {name label} { global outputdir if {[string length $outputdir]!=0} { if {[llength [info commands puts_standard]]>0} { footer $::rcsid } if {[string length $label]>0} { rename puts puts_standard proc puts {str} { regsub -all {href="#([a-z]+)"} $str {href="lang_\1.html"} str puts_standard $::section_file $str } rename footer footer_standard proc footer {id} { footer_standard $id rename footer "" rename puts "" rename puts_standard puts rename footer_standard footer } set ::section_file [open [file join $outputdir lang_$label.html] w] header "Query Language Understood by SQLite: $name" puts "<h1>SQL As Understood By SQLite</h1>" puts "<a href=\"lang.html\">\[Contents\]</a>" puts "<h2>$name</h2>" return } } puts "\n<hr />" if {$label!=""} { puts "<a name=\"$label\"></a>" } puts "<h1>$name</h1>\n" } Section {ALTER TABLE} altertable Syntax {sql-statement} { ALTER TABLE [<database-name> .] <table-name> <alteration> } {alteration} { RENAME TO <new-table-name> } {alteration} { ADD [COLUMN] <column-def> } puts { <p>SQLite's version of the ALTER TABLE command allows the user to rename or add a new column to an existing table. It is not possible to remove a column from a table. </p> <p>The RENAME TO syntax is used to rename the table identified by <i>[database-name.]table-name</i> to <i>new-table-name</i>. This command cannot be used to move a table between attached databases, only to rename a table within the same database.</p> <p>If the table being renamed has triggers or indices, then these remain attached to the table after it has been renamed. However, if there are any view definitions, or statements executed by triggers that refer to the table being renamed, these are not automatically modified to use the new table name. If this is required, the triggers or view definitions must be dropped and recreated to use the new table name by hand. </p> <p>The ADD [COLUMN] syntax is used to add a new column to an existing table. The new column is always appended to the end of the list of existing columns. <i>Column-def</i> may take any of the forms permissable in a CREATE TABLE statement, with the following restrictions: <ul> <li>The column may not have a PRIMARY KEY or UNIQUE constraint.</li> <li>The column may not have a default value of CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP.</li> <li>If a NOT NULL constraint is specified, then the column must have a default value other than NULL. </ul> <p>The execution time of the ALTER TABLE command is independent of the amount of data in the table. The ALTER TABLE command runs as quickly on a table with 10 million rows as it does on a table with 1 row. </p> <p>After ADD COLUMN has been run on a database, that database will not be readable by SQLite version 3.1.3 and earlier until the database is <a href="lang_vacuum.html">VACUUM</a>ed.</p> } Section {ANALYZE} analyze Syntax {sql-statement} { ANALYZE } Syntax {sql-statement} { ANALYZE <database-name> } Syntax {sql-statement} { ANALYZE [<database-name> .] <table-name> } puts { <p>The ANALYZE command gathers statistics about indices and stores them in a special tables in the database where the query optimizer can use them to help make better index choices. If no arguments are given, all indices in all attached databases are analyzed. If a database name is given as the argument, all indices in that one database are analyzed. If the argument is a table name, then only indices associated with that one table are analyzed.</p> <p>The initial implementation stores all statistics in a single table named <b>sqlite_stat1</b>. Future enhancements may create additional tables with the same name pattern except with the "1" changed to a different digit. The <b>sqlite_stat1</b> table cannot be <a href="#droptable">DROP</a>ped, but all the content can be <a href="#delete">DELETE</a>d which has the same effect.</p> } Section {ATTACH DATABASE} attach Syntax {sql-statement} { ATTACH [DATABASE] <database-filename> AS <database-name> } puts { <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 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 <a href="#detach">DETACH DATABASE</a> statement.</p> <p>You can read from and write to an attached database and you can modify the schema of the attached database. This is a new feature of SQLite version 3.0. In SQLite 2.8, schema changes to attached databases were not allowed.</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 doesn't require a database name 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 table 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. Atomic commit of attached databases is a new feature of SQLite version 3.0. In SQLite version 2.8, all commits to attached databases behaved as if the main database were ":memory:". </p> <p>There is a compile-time limit of 10 attached database files.</p> } Section {BEGIN TRANSACTION} transaction Syntax {sql-statement} { BEGIN [ DEFERRED | IMMEDIATE | EXCLUSIVE ] [TRANSACTION [<name>]] } Syntax {sql-statement} { END [TRANSACTION [<name>]] } Syntax {sql-statement} { COMMIT [TRANSACTION [<name>]] } Syntax {sql-statement} { ROLLBACK [TRANSACTION [<name>]] } puts { <p> No changes can be made to the database except within a transaction. Any command that changes the database (basically, any SQL command other than SELECT) will automatically start a transaction if one is not already in effect. Automatically started transactions are committed at the conclusion of the command. </p> <p> Transactions can be started manually using the BEGIN command. Such transactions usually persist until the next COMMIT or ROLLBACK command. But a transaction will also ROLLBACK if the database is closed or if an error occurs and the ROLLBACK conflict resolution algorithm is specified. See the documentation on the <a href="#conflict">ON CONFLICT</a> clause for additional information about the ROLLBACK conflict resolution algorithm. </p> <p> END TRANSACTION is an alias for COMMIT. </p> <p>The optional transaction name is current ignored. SQLite does not recognize nested transactions at this time. However, future versions of SQLite may be enhanced to support nested transactions and the transaction name would then become significant. Application are advised not to use the transaction name in order to avoid future compatibility problems.</p> <p> Transactions can be deferred, immediate, or exclusive. The default transaction behavior is deferred. Deferred means that no locks are acquired on the database until the database is first accessed. Thus with a deferred transaction, the BEGIN statement itself does nothing. Locks are not acquired until the first read or write operation. The first read operation against a database creates a SHARED lock and the first write operation creates a RESERVED lock. Because the acquisition of locks is deferred until they are needed, it is possible that another thread or process could create a separate transaction and write to the database after the BEGIN on the current thread has executed. If the transaction is immediate, then RESERVED locks are acquired on all databases as soon as the BEGIN command is executed, without waiting for the database to be used. After a BEGIN IMMEDIATE, you are guaranteed that no other thread or process will be able to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue to read from the database, however. An exclusive transaction causes EXCLUSIVE locks to be acquired on all databases. After a BEGIN EXCLUSIVE, you are guaranteed that no other thread or process will be able to read or write the database until the transaction is complete. </p> <p> A description of the meaning of SHARED, RESERVED, and EXCLUSIVE locks is available <a href="lockingv3.html">separately</a>. </p> <p> The COMMIT command does not actually perform a commit until all pending SQL commands finish. Thus if two or more SELECT statements are in the middle of processing and a COMMIT is executed, the commit will not actually occur until all SELECT statements finish. </p> <p> An attempt to execute COMMIT might result in an SQLITE_BUSY return code. This indicates that another thread or process had a read lock on the database that prevented the database from being updated. When COMMIT fails in this way, the transaction remains active and the COMMIT can be retried later after the reader has had a chance to clear. </p> <h3>Response To Errors Within A Transaction</h3> <p>If certain kinds of errors occur within a transaction, the transaction may or may not be rolled back automatically. The errors that cause the behavior include:</p> <ul> <li> SQLITE_FULL: database or disk full <li> SQLITE_IOERR: disk I/O error <li> SQLITE_BUSY: database in use by another process <li> SQLITE_NOMEM: out or memory <li> SQLITE_INTERRUPT: processing interrupted by user request </ul> <p> For all of these errors, SQLite attempts to undo just the one statement it was working on and leave changes from prior statements within the same transaction intact and continue with the transaction. However, depending on the statement being evaluated and the point at which the error occurs, it might be necessary for SQLite to rollback and cancel the transaction. An application can tell which course of action SQLite took by using the <a href="capi3ref.html#sqlite3_get_autocommit">sqlite3_get_autocommit()</a> C-language interface.</p> <p>It is recommended that applications respond to the errors listed above by explicitly issuing a ROLLBACK command. If the transaction has already been rolled back automatically by the error response, then the ROLLBACK command will fail with an error, but no harm is caused by this.</p> <p>Future versions of SQLite may extend the list of errors which might cause automatic transaction rollback. Future versions of SQLite might change the error response. In particular, we may choose to simplify the interface in future versions of SQLite by causing the errors above to force an unconditional rollback.</p> } Section comment comment Syntax {comment} {<SQL-comment> | <C-comment> } {SQL-comment} {-- <single-line> } {C-comment} {/STAR <multiple-lines> [STAR/] } puts { <p> Comments aren't SQL commands, but can occur in SQL queries. They are treated as whitespace by the parser. They can begin anywhere whitespace can be found, including inside expressions that span multiple lines. </p> <p> SQL comments only extend to the end of the current line.</p> <p> C comments can span any number of lines. If there is no terminating delimiter, they extend to the end of the input. This is not treated as an error. A new SQL statement can begin on a line after a multiline comment ends. C comments can be embedded anywhere whitespace can occur, including inside expressions, and in the middle of other SQL statements. C comments do not nest. SQL comments inside a C comment will be ignored. </p> } Section COPY copy Syntax {sql-statement} { COPY [ OR <conflict-algorithm> ] [<database-name> .] <table-name> FROM <filename> [ USING DELIMITERS <delim> ] } puts { <p>The COPY command is available in SQLite version 2.8 and earlier. The COPY command has been removed from SQLite version 3.0 due to complications in trying to support it in a mixed UTF-8/16 environment. In version 3.0, the <a href="sqlite.html">command-line shell</a> contains a new command <b>.import</b> that can be used as a substitute for COPY. </p> <p>The COPY command is an extension used to load large amounts of data into a table. It is modeled after a similar command found in PostgreSQL. In fact, the SQLite COPY command is specifically designed to be able to read the output of the PostgreSQL dump utility <b>pg_dump</b> so that data can be easily transferred from PostgreSQL into SQLite.</p> <p>The table-name is the name of an existing table which is to be filled with data. The filename is a string or identifier that names a file from which data will be read. The filename can be the <b>STDIN</b> to read data from standard input.</p> <p>Each line of the input file is converted into a single record in the table. Columns are separated by tabs. If a tab occurs as data within a column, then that tab is preceded by a baskslash "\" character. A baskslash in the data appears as two backslashes in a row. The optional USING DELIMITERS clause can specify a delimiter other than tab.</p> <p>If a column consists of the character "\N", that column is filled with the value NULL.</p> <p>The optional conflict-clause allows the specification of an alternative constraint conflict resolution algorithm to use for this one command. See the section titled <a href="#conflict">ON CONFLICT</a> for additional information.</p> <p>When the input data source is STDIN, the input can be terminated by a line that contains only a baskslash and a dot:} puts "\"[Operator \\.]\".</p>" Section {CREATE INDEX} createindex Syntax {sql-statement} { CREATE [UNIQUE] INDEX [IF NOT EXISTS] [<database-name> .] <index-name> ON <table-name> ( <column-name> [, <column-name>]* ) } {column-name} { <name> [ COLLATE <collation-name>] [ ASC | DESC ] } puts { <p>The CREATE INDEX command consists of the keywords "CREATE INDEX" followed by the name of the new index, the keyword "ON", the name of a previously created table that is to be indexed, and a parenthesized list of names of columns in the table that are used for the index key. Each column name can be followed by one of the "ASC" or "DESC" keywords to indicate sort order, but the sort order is ignored in the current implementation. Sorting is always done in ascending order.</p> <p>The COLLATE clause following each column name defines a collating sequence used for text entires in that column. The default collating sequence is the collating sequence defined for that column in the CREATE TABLE statement. Or if no collating sequence is otherwise defined, the built-in BINARY collating sequence is used.</p> <p>There are no arbitrary limits on the number of indices that can be attached to a single table, nor on the number of columns in an index.</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.</p> <p>The exact 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 SQLite's internal representation of the index layout.</p> <p>If the optional IF NOT EXISTS clause is present and another index with the same name aleady exists, then this command becomes a no-op.</p> <p>Indexes are removed with the <a href="#dropindex">DROP INDEX</a> command.</p> } Section {CREATE TABLE} {createtable} Syntax {sql-command} { CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [<database-name> .] <table-name> ( <column-def> [, <column-def>]* [, <constraint>]* ) } {sql-command} { CREATE [TEMP | TEMPORARY] TABLE [<database-name>.] <table-name> AS <select-statement> } {column-def} { <name> [<type>] [[CONSTRAINT <name>] <column-constraint>]* } {type} { <typename> | <typename> ( <number> ) | <typename> ( <number> , <number> ) } {column-constraint} { NOT NULL [ <conflict-clause> ] | PRIMARY KEY [<sort-order>] [ <conflict-clause> ] [AUTOINCREMENT] | UNIQUE [ <conflict-clause> ] | CHECK ( <expr> ) | DEFAULT <value> | COLLATE <collation-name> } {constraint} { PRIMARY KEY ( <column-list> ) [ <conflict-clause> ] | UNIQUE ( <column-list> ) [ <conflict-clause> ] | CHECK ( <expr> ) } {conflict-clause} { ON CONFLICT <conflict-algorithm> } puts { <p>A CREATE TABLE statement is basically the keywords "CREATE TABLE" followed by the name of a new table and a parenthesized list of column definitions and constraints. The table name can be either an identifier or a string. Tables names that begin with "<b>sqlite_</b>" are reserved for use by the engine.</p> <p>Each column definition is the name of the column followed by the datatype for that column, then one or more optional column constraints. The datatype for the column does not restrict what data may be put in that column. See <a href="datatype3.html">Datatypes In SQLite Version 3</a> for additional information. The UNIQUE constraint causes an index to be created on the specified columns. This index must contain unique keys. The COLLATE clause specifies what text <a href="datatype3.html#collation"> collating function</a> to use when comparing text entries for the column. The built-in BINARY collating function is used by default. <p> The DEFAULT constraint specifies a default value to use when doing an INSERT. The value may be NULL, a string constant or a number. Starting with version 3.1.0, the default value may also be one of the special case-independant keywords CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP. If the value is NULL, a string constant or number, it is literally inserted into the column whenever an INSERT statement that does not specify a value for the column is executed. If the value is CURRENT_TIME, CURRENT_DATE or CURRENT_TIMESTAMP, then the current UTC date and/or time is inserted into the columns. For CURRENT_TIME, the format is HH:MM:SS. For CURRENT_DATE, YYYY-MM-DD. The format for CURRENT_TIMESTAMP is "YYYY-MM-DD HH:MM:SS". </p> <p>Specifying a PRIMARY KEY normally just creates a UNIQUE index on the corresponding columns. However, if primary key is on a single column that has datatype INTEGER, then that column is used internally as the actual key of the B-Tree for the table. This means that the column may only hold unique integer values. (Except for this one case, SQLite ignores the datatype specification of columns and allows any kind of data to be put in a column regardless of its declared datatype.) If a table does not have an INTEGER PRIMARY KEY column, then the B-Tree key will be a automatically generated integer. <a name="rowid"> The B-Tree key for a row can always be accessed using one of the special names "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>". This is true regardless of whether or not there is an INTEGER PRIMARY KEY. An INTEGER PRIMARY KEY column can also include the keyword AUTOINCREMENT. The AUTOINCREMENT keyword modified the way that B-Tree keys are automatically generated. Additional detail on automatic B-Tree key generation is available <a href="autoinc.html">separately</a>.</p> <p>According to the SQL standard, PRIMARY KEY should imply NOT NULL. Unfortunately, due to a long-standing coding oversight, this is not the case in SQLite. SQLite allows NULL values in a PRIMARY KEY column. We could change SQLite to conform to the standard (and we might do so in the future), but by the time the oversight was discovered, SQLite was in such wide use that we feared breaking legacy code if we fixed the problem. So for now we have chosen to contain allowing NULLs in PRIMARY KEY columns. Developers should be aware, however, that we may change SQLite to conform to the SQL standard in future and should design new programs accordingly.</p> <p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE" and "TABLE" then the table that is created is only visible within that same database connection and is automatically deleted when the database connection is closed. Any indices created on a temporary table are also temporary. Temporary tables and indices are stored in a separate file distinct from the main database file.</p> <p> If a <database-name> is specified, then the table is created in the named database. It is an error to specify both a <database-name> and the TEMP keyword, unless the <database-name> is "temp". If no database name is specified, and the TEMP keyword is not present, the table is created in the main database.</p> <p>The optional conflict-clause following each constraint allows the specification of an alternative default constraint conflict resolution algorithm for that constraint. The default is abort ABORT. Different constraints within the same table may have different default conflict resolution algorithms. If an COPY, INSERT, or UPDATE command specifies a different conflict resolution algorithm, then that algorithm is used in place of the default algorithm specified in the CREATE TABLE statement. See the section titled <a href="#conflict">ON CONFLICT</a> for additional information.</p> <p>CHECK constraints are supported as of version 3.3.0. Prior to version 3.3.0, CHECK constraints were parsed but not enforced.</p> <p>There are no arbitrary limits on the number of columns or on the number of constraints in a table. The total amount of data in a single row is limited to about 1 megabytes in version 2.8. In version 3.0 there is no arbitrary limit on the amount of data in a row.</p> <p>The CREATE TABLE AS form defines the table to be the result set of a query. The names of the table columns are the names of the columns in the result.</p> <p>The exact text of each CREATE TABLE statement is stored in the <b>sqlite_master</b> table. Every time the database is opened, all CREATE TABLE statements are read from the <b>sqlite_master</b> table and used to regenerate SQLite's internal representation of the table layout. If the original command was a CREATE TABLE AS then then an equivalent CREATE TABLE statement is synthesized and store in <b>sqlite_master</b> in place of the original command. The text of CREATE TEMPORARY TABLE statements are stored in the <b>sqlite_temp_master</b> table. </p> <p>If the optional IF NOT EXISTS clause is present and another table with the same name aleady exists, then this command becomes a no-op.</p> <p>Tables are removed using the <a href="#droptable">DROP TABLE</a> statement. </p> } Section {CREATE TRIGGER} createtrigger Syntax {sql-statement} { CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> [ BEFORE | AFTER ] <database-event> ON [<database-name> .] <table-name> <trigger-action> } Syntax {sql-statement} { CREATE [TEMP | TEMPORARY] TRIGGER [IF NOT EXISTS] <trigger-name> INSTEAD OF <database-event> ON [<database-name> .] <view-name> <trigger-action> } Syntax {database-event} { DELETE | INSERT | UPDATE | UPDATE OF <column-list> } Syntax {trigger-action} { [ FOR EACH ROW ] [ WHEN <expression> ] BEGIN <trigger-step> ; [ <trigger-step> ; ]* END } Syntax {trigger-step} { <update-statement> | <insert-statement> | <delete-statement> | <select-statement> } puts { <p>The CREATE TRIGGER statement is used to add triggers to the database schema. Triggers are database operations (the <i>trigger-action</i>) that are automatically performed when a specified database event (the <i>database-event</i>) occurs. </p> <p>A trigger may be specified to fire whenever a DELETE, INSERT or UPDATE of a particular database table occurs, or whenever an UPDATE of one or more specified columns of a table are updated.</p> <p>At this time SQLite supports only FOR EACH ROW triggers, not FOR EACH STATEMENT triggers. Hence explicitly specifying FOR EACH ROW is optional. FOR EACH ROW implies that the SQL statements specified as <i>trigger-steps</i> may be executed (depending on the WHEN clause) for each database row being inserted, updated or deleted by the statement causing the trigger to fire.</p> <p>Both the WHEN clause and the <i>trigger-steps</i> may access elements of the row being inserted, deleted or updated using references of the form "NEW.<i>column-name</i>" and "OLD.<i>column-name</i>", where <i>column-name</i> is the name of a column from the table that the trigger is associated with. OLD and NEW references may only be used in triggers on <i>trigger-event</i>s for which they are relevant, as follows:</p> <table border=0 cellpadding=10> <tr> <td valign="top" align="right" width=120><i>INSERT</i></td> <td valign="top">NEW references are valid</td> </tr> <tr> <td valign="top" align="right" width=120><i>UPDATE</i></td> <td valign="top">NEW and OLD references are valid</td> </tr> <tr> <td valign="top" align="right" width=120><i>DELETE</i></td> <td valign="top">OLD references are valid</td> </tr> </table> </p> <p>If a WHEN clause is supplied, the SQL statements specified as <i>trigger-steps</i> are only executed for rows for which the WHEN clause is true. If no WHEN clause is supplied, the SQL statements are executed for all rows.</p> <p>The specified <i>trigger-time</i> determines when the <i>trigger-steps</i> will be executed relative to the insertion, modification or removal of the associated row.</p> <p>An ON CONFLICT clause may be specified as part of an UPDATE or INSERT <i>trigger-step</i>. However if an ON CONFLICT clause is specified as part of the statement causing the trigger to fire, then this conflict handling policy is used instead.</p> <p>Triggers are automatically dropped when the table that they are associated with is dropped.</p> <p>Triggers may be created on views, as well as ordinary tables, by specifying INSTEAD OF in the CREATE TRIGGER statement. If one or more ON INSERT, ON DELETE or ON UPDATE triggers are defined on a view, then it is not an error to execute an INSERT, DELETE or UPDATE statement on the view, respectively. Thereafter, executing an INSERT, DELETE or UPDATE on the view causes the associated triggers to fire. The real tables underlying the view are not modified (except possibly explicitly, by a trigger program).</p> <p><b>Example:</b></p> <p>Assuming that customer records are stored in the "customers" table, and that order records are stored in the "orders" table, the following trigger ensures that all associated orders are redirected when a customer changes his or her address:</p> } Example { CREATE TRIGGER update_customer_address UPDATE OF address ON customers BEGIN UPDATE orders SET address = new.address WHERE customer_name = old.name; END; } puts { <p>With this trigger installed, executing the statement:</p> } Example { UPDATE customers SET address = '1 Main St.' WHERE name = 'Jack Jones'; } puts { <p>causes the following to be automatically executed:</p> } Example { UPDATE orders SET address = '1 Main St.' WHERE customer_name = 'Jack Jones'; } puts { <p>Note that currently, triggers may behave oddly when created on tables with INTEGER PRIMARY KEY fields. If a BEFORE trigger program modifies the INTEGER PRIMARY KEY field of a row that will be subsequently updated by the statement that causes the trigger to fire, then the update may not occur. The workaround is to declare the table with a PRIMARY KEY column instead of an INTEGER PRIMARY KEY column.</p> } puts { <p>A special SQL function RAISE() may be used within a trigger-program, with the following syntax</p> } Syntax {raise-function} { RAISE ( ABORT, <error-message> ) | RAISE ( FAIL, <error-message> ) | RAISE ( ROLLBACK, <error-message> ) | RAISE ( IGNORE ) } puts { <p>When one of the first three forms is called during trigger-program execution, the specified ON CONFLICT processing is performed (either ABORT, FAIL or ROLLBACK) and the current query terminates. An error code of SQLITE_CONSTRAINT is returned to the user, along with the specified error message.</p> <p>When RAISE(IGNORE) is called, the remainder of the current trigger program, the statement that caused the trigger program to execute and any subsequent trigger programs that would of been executed are abandoned. No database changes are rolled back. If the statement that caused the trigger program to execute is itself part of a trigger program, then that trigger program resumes execution at the beginning of the next step. </p> <p>Triggers are removed using the <a href="#droptrigger">DROP TRIGGER</a> statement.</p> } Section {CREATE VIEW} {createview} Syntax {sql-command} { CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] [<database-name>.] <view-name> AS <select-statement> } puts { <p>The CREATE VIEW command assigns a name to a pre-packaged <a href="#select">SELECT</a> statement. Once the view is created, it can be used in the FROM clause of another SELECT in place of a table name. </p> <p>If the "TEMP" or "TEMPORARY" keyword occurs in between "CREATE" and "VIEW" then the view that is created is only visible to the process that opened the database and is automatically deleted when the database is closed.</p> <p> If a <database-name> is specified, then the view is created in the named database. It is an error to specify both a <database-name> and the TEMP keyword, unless the <database-name> is "temp". If no database name is specified, and the TEMP keyword is not present, the table is created in the main database.</p> <p>You cannot COPY, DELETE, INSERT or UPDATE a view. Views are read-only in SQLite. However, in many cases you can use a <a href="#createtrigger"> TRIGGER</a> on the view to accomplish the same thing. Views are removed with the <a href="#dropview">DROP VIEW</a> command.</p> } Section {CREATE VIRTUAL TABLE} {createvtab} Syntax {sql-command} { CREATE VIRTUAL TABLE [<database-name> .] <table-name> USING <module-name> [( <arguments> )] } puts { <p>A virtual table is an interface to an external storage or computation engine that appears to be a table but does not actually store information in the database file.</p> <p>In general, you can do anything with a virtual table that can be done with an ordinary table, except that you cannot create triggers on a virtual table. Some virtual table implementations might impose additional restrictions. For example, many virtual tables are read-only.</p> <p>The <module-name> is the name of an object that implements the virtual table. The <module-name> must be registered with the SQLite database connection using <a href="capi3ref.html#sqlite3_create_module">sqlite3_create_module</a> prior to issuing the CREATE VIRTUAL TABLE statement. The module takes zero or more comma-separated arguments. The arguments can be just about any text as long as it has balanced parentheses. The argument syntax is sufficiently general that the arguments can be made to appear as column definitions in a traditional <a href="#createtable">CREATE TABLE</a> statement. SQLite passes the module arguments directly to the module without any interpretation. It is the responsibility of the module implementation to parse and interpret its own arguments.</p> <p>A virtual table is destroyed using the ordinary <a href="#droptable">DROP TABLE</a> statement. There is no DROP VIRTUAL TABLE statement.</p> } Section DELETE delete Syntax {sql-statement} { DELETE FROM [<database-name> .] <table-name> [WHERE <expr>] } puts { <p>The DELETE command is used to remove records from a table. The command consists of the "DELETE FROM" keywords followed by the name of the table from which records are to be removed. </p> <p>Without a WHERE clause, all rows of the table are removed. If a WHERE clause is supplied, then only those rows that match the expression are removed.</p> } Section {DETACH DATABASE} detach Syntax {sql-command} { DETACH [DATABASE] <database-name> } puts { <p>This statement detaches an additional database connection previously attached using the <a href="#attach">ATTACH DATABASE</a> statement. It is possible to have the same database file attached multiple times using different names, and detaching one connection to a file will leave the others intact.</p> <p>This statement will fail if SQLite is in the middle of a transaction.</p> } Section {DROP INDEX} dropindex Syntax {sql-command} { DROP INDEX [IF EXISTS] [<database-name> .] <index-name> } puts { <p>The DROP INDEX statement removes an index added with the <a href="#createindex"> CREATE INDEX</a> statement. The index named is completely removed from the disk. The only way to recover the index is to reenter the appropriate CREATE INDEX command.</p> <p>The DROP INDEX statement does not reduce the size of the database file in the default mode. Empty space in the database is retained for later INSERTs. To remove free space in the database, use the <a href="#vacuum">VACUUM</a> command. If AUTOVACUUM mode is enabled for a database then space will be freed automatically by DROP INDEX.</p> } Section {DROP TABLE} droptable Syntax {sql-command} { DROP TABLE [IF EXISTS] [<database-name>.] <table-name> } puts { <p>The DROP TABLE statement removes a table added with the <a href= "#createtable">CREATE TABLE</a> statement. The name specified is the table name. It is completely removed from the database schema and the disk file. The table can not be recovered. All indices associated with the table are also deleted.</p> <p>The DROP TABLE statement does not reduce the size of the database file in the default mode. Empty space in the database is retained for later INSERTs. To remove free space in the database, use the <a href="#vacuum">VACUUM</a> command. If AUTOVACUUM mode is enabled for a database then space will be freed automatically by DROP TABLE.</p> <p>The optional IF EXISTS clause suppresses the error that would normally result if the table does not exist.</p> } Section {DROP TRIGGER} droptrigger Syntax {sql-statement} { DROP TRIGGER [IF EXISTS] [<database-name> .] <trigger-name> } puts { <p>The DROP TRIGGER statement removes a trigger created by the <a href="#createtrigger">CREATE TRIGGER</a> statement. The trigger is deleted from the database schema. Note that triggers are automatically dropped when the associated table is dropped.</p> } Section {DROP VIEW} dropview Syntax {sql-command} { DROP VIEW [IF EXISTS] <view-name> } puts { <p>The DROP VIEW statement removes a view created by the <a href= "#createview">CREATE VIEW</a> statement. The name specified is the view name. It is removed from the database schema, but no actual data in the underlying base tables is modified.</p> } Section EXPLAIN explain Syntax {sql-statement} { EXPLAIN <sql-statement> } puts { <p>The EXPLAIN command modifier is a non-standard extension. The idea comes from a similar command found in PostgreSQL, but the operation is completely different.</p> <p>If the EXPLAIN keyword appears before any other SQLite SQL command then instead of actually executing the command, the SQLite library will report back the sequence of virtual machine instructions it would have used to execute the command had the EXPLAIN keyword not been present. For additional information about virtual machine instructions see the <a href="arch.html">architecture description</a> or the documentation on <a href="opcode.html">available opcodes</a> for the virtual machine.</p> } Section expression expr Syntax {expr} { <expr> <binary-op> <expr> | <expr> [NOT] <like-op> <expr> [ESCAPE <expr>] | <unary-op> <expr> | ( <expr> ) | <column-name> | <table-name> . <column-name> | <database-name> . <table-name> . <column-name> | <literal-value> | <parameter> | <function-name> ( <expr-list> | STAR ) | <expr> ISNULL | <expr> NOTNULL | <expr> [NOT] BETWEEN <expr> AND <expr> | <expr> [NOT] IN ( <value-list> ) | <expr> [NOT] IN ( <select-statement> ) | <expr> [NOT] IN [<database-name> .] <table-name> | [EXISTS] ( <select-statement> ) | CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END | CAST ( <expr> AS <type> ) | <expr> COLLATE <collation-name> } {like-op} { LIKE | GLOB | REGEXP | MATCH } puts { <p>This section is different from the others. Most other sections of this document talks about a particular SQL command. This section does not talk about a standalone command but about "expressions" which are subcomponents of most other commands.</p> <p>SQLite understands the following binary operators, in order from highest to lowest precedence:</p> <blockquote><pre> <font color="#2c2cf0"><big>|| * / % + - << >> & | < <= > >= = == != <> </big>IN AND OR</font> </pre></blockquote> <p>Supported unary prefix operators are these:</p> <blockquote><pre> <font color="#2c2cf0"><big>- + ! ~ NOT</big></font> </pre></blockquote> <p>The COLLATE operator can be thought of as a unary postfix operator. The COLLATE operator has the highest precedence. It always binds more tightly than any prefix unary operator or any binary operator.</p> <p>The unary operator [Operator +] is a no-op. It can be applied to strings, numbers, or blobs and it always gives as its result the value of the operand.</p> <p>Note that there are two variations of the equals and not equals operators. Equals can be either} puts "[Operator =] or [Operator ==]. The non-equals operator can be either [Operator !=] or [Operator {<>}]. The [Operator ||] operator is \"concatenate\" - it joins together the two strings of its operands. The operator [Operator %] outputs the remainder of its left operand modulo its right operand.</p> <p>The result of any binary operator is a numeric value, except for the [Operator ||] concatenation operator which gives a string result.</p>" puts { <a name="literal_value"></a> <p> A literal value is an integer number or a floating point number. Scientific notation is supported. The "." character is always used as the decimal point even if the locale setting specifies "," for this role - the use of "," for the decimal point would result in syntactic ambiguity. A string constant is formed by enclosing the string in single quotes ('). A single quote within the string can be encoded by putting two single quotes in a row - as in Pascal. C-style escapes using the backslash character are not supported because they are not standard SQL. BLOB literals are string literals containing hexadecimal data and preceded by a single "x" or "X" character. For example:</p> <blockquote><pre> X'53514C697465' </pre></blockquote> <p> A literal value can also be the token "NULL". </p> <p> A parameter specifies a placeholder in the expression for a literal value that is filled in at runtime using the <a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API. Parameters can take several forms: </p <blockquote> <table class="pdf_functions"> <tr> <td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td> <td>A question mark followed by a number <i>NNN</i> holds a spot for the NNN-th parameter. NNN must be between 1 and 999.</td> </tr> <tr> <td align="right" valign="top"><b>?</b></td><td width="20"></td> <td>A question mark that is not followed by a number holds a spot for the next unused parameter.</td> </tr> <tr> <td align="right" valign="top"><b>:</b><i>AAAA</i></td><td width="20"></td> <td>A colon followed by an identifier name holds a spot for a named parameter with the name AAAA. Named parameters are also numbered. The number assigned is the next unused number. To avoid confusion, it is best to avoid mixing named and numbered parameters.</td> </tr> <tr> <td align="right" valign="top"><b>@</b><i>AAAA</i></td><td width="20"></td> <td>An "at" sign works exactly like a colon.</td> </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 occurances of "::" and a suffix enclosed in "(...)" containing any text at all. This syntax is the form of a variable name in the Tcl programming language.</td> </tr> </table> </blockquote> <p>Parameters that are not assigned values using <a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> are treated as NULL.</p> <a name="like"></a> <p>The LIKE operator does a pattern matching comparison. The operand to the right contains the pattern, the left hand operand contains the string to match against the pattern. } puts "A percent symbol [Operator %] in the pattern matches any sequence of zero or more characters in the string. An underscore [Operator _] in the pattern matches any single character in the string. Any other character matches itself or it's lower/upper case equivalent (i.e. case-insensitive matching). (A bug: SQLite only understands upper/lower case for 7-bit Latin characters. Hence the LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8 characters. For example, the expression <b>'a' LIKE 'A'</b> is TRUE but <b>'æ' LIKE 'Æ'</b> is FALSE.).</p>" puts { <p>If the optional ESCAPE clause is present, then the expression following the ESCAPE keyword must evaluate to a string consisting of a single character. This character may be used in the LIKE pattern to include literal percent or underscore characters. The escape character followed by a percent symbol, underscore or itself matches a literal percent symbol, underscore or escape character in the string, respectively. The infix LIKE operator is implemented by calling the user function <a href="#likeFunc"> like(<i>X</i>,<i>Y</i>)</a>.</p> } puts { The LIKE operator is not case sensitive and will match upper case characters on one side against lower case characters on the other. (A bug: SQLite only understands upper/lower case for 7-bit Latin characters. Hence the LIKE operator is case sensitive for 8-bit iso8859 characters or UTF-8 characters. For example, the expression <b>'a' LIKE 'A'</b> is TRUE but <b>'æ' LIKE 'Æ'</b> is FALSE.).</p> <p>The infix LIKE operator is implemented by calling the user function <a href="#likeFunc"> like(<i>X</i>,<i>Y</i>)</a>. If an ESCAPE clause is present, it adds a third parameter to the function call. If the functionality of LIKE can be overridden by defining an alternative implementation of the like() SQL function.</p> </p> <a name="glob"></a> <p>The GLOB operator is similar to LIKE but uses the Unix file globbing syntax for its wildcards. Also, GLOB is case sensitive, unlike LIKE. Both GLOB and LIKE may be preceded by the NOT keyword to invert the sense of the test. The infix GLOB operator is implemented by calling the user function <a href="#globFunc"> glob(<i>X</i>,<i>Y</i>)</a> and can be modified by overriding that function.</p> <a name="regexp"></a> <p>The REGEXP operator is a special syntax for the regexp() user function. No regexp() user function is defined by default and so use of the REGEXP operator will normally result in an error message. If a user-defined function named "regexp" is added at run-time, that function will be called in order to implement the REGEXP operator.</p> <a name="match"></a> <p>The MATCH operator is a special syntax for the match() user function. The default match() function implementation raises and exception and is not really useful for anything. But extensions can override the match() function with more helpful logic.</p> <p>A column name can be any of the names defined in the CREATE TABLE statement or one of the following special identifiers: "<b>ROWID</b>", "<b>OID</b>", or "<b>_ROWID_</b>". These special identifiers all describe the unique integer key (the "row key") associated with every row of every table. The special identifiers only refer to the row key if the CREATE TABLE statement does not define a real column with the same name. Row keys act like read-only columns. A row key can be used anywhere a regular column can be used, except that you cannot change the value of a row key in an UPDATE or INSERT statement. "SELECT * ..." does not return the row key.</p> <p>SELECT statements can appear in expressions as either the right-hand operand of the IN operator, as a scalar quantity, or as the operand of an EXISTS operator. As a scalar quantity or the operand of an IN operator, the SELECT should have only a single column in its result. Compound SELECTs (connected with keywords like UNION or EXCEPT) are allowed. With the EXISTS operator, the columns in the result set of the SELECT are ignored and the expression returns TRUE if one or more rows exist and FALSE if the result set is empty. If no terms in the SELECT expression refer to value in the containing query, then the expression is evaluated once prior to any other processing and the result is reused as necessary. If the SELECT expression does contain variables from the outer query, then the SELECT is reevaluated every time it is needed.</p> <p>When a SELECT is the right operand of the IN operator, the IN operator returns TRUE if the result of the left operand is any of the values generated by the select. The IN operator may be preceded by the NOT keyword to invert the sense of the test.</p> <p>When a SELECT appears within an expression but is not the right operand of an IN operator, then the first row of the result of the SELECT becomes the value used in the expression. If the SELECT yields more than one result row, all rows after the first are ignored. If the SELECT yields no rows, then the value of the SELECT is NULL.</p> <p>A CAST expression changes the datatype of the <expr> into the type specified by <type>. <type> can be any non-empty type name that is valid for the type in a column definition of a CREATE TABLE statement.</p> <p>Both simple and aggregate functions are supported. A simple function can be used in any expression. Simple functions return a result immediately based on their inputs. Aggregate functions may only be used in a SELECT statement. Aggregate functions compute their result across all rows of the result set.</p> <a name="corefunctions"></a> <b>Core Functions</b> <p>The core functions shown below are available by default. Additional functions may be written in C and added to the database engine using the <a href="capi3ref.html#cfunc">sqlite3_create_function()</a> API.</p> <table border=0 cellpadding=10 class="pdf_functions"> <tr> <td valign="top" align="right" width=120>abs(<i>X</i>)</td> <td valign="top">Return the absolute value of argument <i>X</i>.</td> </tr> <tr> <td valign="top" align="right">coalesce(<i>X</i>,<i>Y</i>,...)</td> <td valign="top">Return a copy of the first non-NULL argument. If all arguments are NULL then NULL is returned. There must be at least 2 arguments.</td> </tr> <tr> <td valign="top" align="right"> <a name="globFunc"></a> glob(<i>X</i>,<i>Y</i>)</td> <td valign="top">This function is used to implement the "<b>X GLOB Y</b>" syntax of SQLite. The <a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a> interface can be used to override this function and thereby change the operation of the <a href="#globFunc">GLOB</a> operator.</td> </tr> <tr> <td valign="top" align="right">ifnull(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return a copy of the first non-NULL argument. If both arguments are NULL then NULL is returned. This behaves the same as <b>coalesce()</b> above.</td> </tr> <tr> <td valign="top" align="right"> <a name="hexFunc"> hex(<i>X</i>)</td> <td valign="top">The argument is interpreted as a BLOB. The result is a hexadecimal rendering of the content of that blob.</td> </tr> <tr> <td valign="top" align="right">last_insert_rowid()</td> <td valign="top">Return the <a href="lang_createtable.html#rowid">ROWID</a> of the last row insert from this connection to the database. This is the same value that would be returned from the <b>sqlite_last_insert_rowid()</b> API function.</td> </tr> <tr> <td valign="top" align="right">length(<i>X</i>)</td> <td valign="top">Return the string length of <i>X</i> in characters. If SQLite is configured to support UTF-8, then the number of UTF-8 characters is returned, not the number of bytes.</td> </tr> <tr> <td valign="top" align="right"> <a name="likeFunc"></a> like(<i>X</i>,<i>Y</i>)<br> like(<i>X</i>,<i>Y</i>,<i>Z</i>)</td> <td valign="top"> This function is used to implement the "<b>X LIKE Y [ESCAPE Z]</b>" syntax of SQL. If the optional ESCAPE clause is present, then the user-function is invoked with three arguments. Otherwise, it is invoked with two arguments only. The <a href="capi3ref.html#sqlite3_create_function"> sqlite_create_function()</a> interface can be used to override this function and thereby change the operation of the <a href= "#like">LIKE</a> operator. When doing this, it may be important to override both the two and three argument versions of the like() function. Otherwise, different code may be called to implement the LIKE operator depending on whether or not an ESCAPE clause was specified.</td> </tr> <tr> <td valign="top" align="right">load_extension(<i>X</i>)<br> load_extension(<i>X</i>,<i>Y</i>)</td> <td valign="top">Load SQLite extensions out of the shared library file named <i>X</i> using the entry point <i>Y</i>. The result is a NULL. If <i>Y</i> is omitted then the default entry point of <b>sqlite3_extension_init</b> is used. This function raises an exception if the extension fails to load or initialize correctly. <p>This function will fail if the extension attempts to modify or delete a SQL function or collating sequence. The extension can add new functions or collating sequences, but cannot modify or delete existing functions or collating sequences because those functions and/or collating sequences might be used elsewhere in the currently running SQL statement. To load an extension that changes or deletes functions or collating sequences, use the <a href="capi3ref.html#sqlite3_load_extension">sqlite3_load_extension()</a> C-language API.</p> </tr> <tr> <td valign="top" align="right">lower(<i>X</i>)</td> <td valign="top">Return a copy of string <i>X</i> will all characters converted to lower case. The C library <b>tolower()</b> routine is used for the conversion, which means that this function might not work correctly on UTF-8 characters.</td> </tr> <tr> <td valign="top" align="right"> <a name="ltrimFunc"> ltrim(<i>X</i>)<br>ltrim(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return a string formed by removing any and all characters that appear in <i>Y</i> from the left side of <i>X</i>. If the <i>Y</i> argument is omitted, spaces are removed.</td> </tr> <tr> <td valign="top" align="right">max(<i>X</i>,<i>Y</i>,...)</td> <td valign="top">Return the argument with the maximum value. Arguments may be strings in addition to numbers. The maximum value is determined by the usual sort order. Note that <b>max()</b> is a simple function when it has 2 or more arguments but converts to an aggregate function if given only a single argument.</td> </tr> <tr> <td valign="top" align="right">min(<i>X</i>,<i>Y</i>,...)</td> <td valign="top">Return the argument with the minimum value. Arguments may be strings in addition to numbers. The minimum value is determined by the usual sort order. Note that <b>min()</b> is a simple function when it has 2 or more arguments but converts to an aggregate function if given only a single argument.</td> </tr> <tr> <td valign="top" align="right">nullif(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return the first argument if the arguments are different, otherwise return NULL.</td> </tr> <tr> <td valign="top" align="right">quote(<i>X</i>)</td> <td valign="top">This routine returns a string which is the value of its argument suitable for inclusion into another SQL statement. Strings are surrounded by single-quotes with escapes on interior quotes as needed. BLOBs are encoded as hexadecimal literals. The current implementation of VACUUM uses this function. The function is also useful when writing triggers to implement undo/redo functionality. </td> </tr> <tr> <td valign="top" align="right">random(*)</td> <td valign="top">Return a pseudo-random integer between -9223372036854775808 and +9223372036854775807.</td> </tr> <tr> <td valign="top" align="right"> <a name="replaceFunc"> replace(<i>X</i>,<i>Y</i>,<i>Z</i>)</td> <td valign="top">Return a string formed by substituting string <i>Z</i> for every occurrance of string <i>Y</i> in string <i>X</i>. The BINARY collating sequence is used for comparisons.</td> </tr> <tr> <td valign="top" align="right"> <a name="randomblobFunc"> randomblob(<i>N</i>)</td> <td valign="top">Return a <i>N</i>-byte blob containing pseudo-random bytes. <i>N</i> should be a postive integer.</td> </tr> <tr> <td valign="top" align="right">round(<i>X</i>)<br>round(<i>X</i>,<i>Y</i>)</td> <td valign="top">Round off the number <i>X</i> to <i>Y</i> digits to the right of the decimal point. If the <i>Y</i> argument is omitted, 0 is assumed.</td> </tr> <tr> <td valign="top" align="right"> <a name="rtrimFunc"> rtrim(<i>X</i>)<br>rtrim(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return a string formed by removing any and all characters that appear in <i>Y</i> from the right side of <i>X</i>. If the <i>Y</i> argument is omitted, spaces are removed.</td> </tr> <tr> <td valign="top" align="right">soundex(<i>X</i>)</td> <td valign="top">Compute the soundex encoding of the string <i>X</i>. The string "?000" is returned if the argument is NULL. This function is omitted from SQLite by default. It is only available the -DSQLITE_SOUNDEX=1 compiler option is used when SQLite is built.</td> </tr> <tr> <td valign="top" align="right">sqlite_version(*)</td> <td valign="top">Return the version string for the SQLite library that is running. Example: "2.8.0"</td> </tr> <tr> <td valign="top" align="right"> substr(<i>X</i>,<i>Y</i>,<i>Z</i>)<br> substr(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return a substring of input string <i>X</i> that begins with the <i>Y</i>-th character and which is <i>Z</i> characters long. If <i>Z</i> is omitted then all character through the end of the string are returned. The left-most character of <i>X</i> is number 1. If <i>Y</i> is negative the the first character of the substring is found by counting from the right rather than the left. If <i>X</i> is string then characters indices refer to actual UTF-8 characters. If <i>X</i> is a BLOB then the indices refer to bytes.</td> </tr> <tr> <td valign="top" align="right"> <a name="trimFunc"> trim(<i>X</i>)<br>trim(<i>X</i>,<i>Y</i>)</td> <td valign="top">Return a string formed by removing any and all characters that appear in <i>Y</i> from both ends of <i>X</i>. If the <i>Y</i> argument is omitted, spaces are removed.</td> </tr> <tr> <td valign="top" align="right">typeof(<i>X</i>)</td> <td valign="top">Return the type of the expression <i>X</i>. The only return values are "null", "integer", "real", "text", and "blob". SQLite's type handling is explained in <a href="datatype3.html">Datatypes in SQLite Version 3</a>.</td> </tr> <tr> <td valign="top" align="right">upper(<i>X</i>)</td> <td valign="top">Return a copy of input string <i>X</i> converted to all upper-case letters. The implementation of this function uses the C library routine <b>toupper()</b> which means it may not work correctly on UTF-8 strings.</td> </tr> <tr> <td valign="top" align="right">zeroblob(<i>N</i>)</td> <td valign="top"><a name="zeroblob"> Return a BLOB consisting of N bytes of 0x00. SQLite manages these zeroblobs very efficiently. Zeroblobs can be used to reserve space for a BLOB that is later written using <a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a>.</td> </tr> </table> <b>Date And Time Functions</b> <p>Date and time functions are documented in the <a href="http://www.sqlite.org/cvstrac/wiki?p=DateAndTimeFunctions"> SQLite Wiki</a>.</p> <a name="aggregatefunctions"></a> <b>Aggregate Functions</b> <p> The aggregate functions shown below are available by default. Additional aggregate functions written in C may be added using the <a href="capi3ref.html#sqlite3_create_function">sqlite3_create_function()</a> API.</p> <p> In any aggregate function that takes a single argument, that argument can be preceeded by the keyword DISTINCT. In such cases, duplicate elements are filtered before being passed into the aggregate function. For example, the function "count(distinct X)" will return the number of distinct values of column X instead of the total number of non-null values in column X. </p> <table border=0 cellpadding=10 class="pdf_functions"> <tr> <td valign="top" align="right" width=120>avg(<i>X</i>)</td> <td valign="top">Return the average value of all non-NULL <i>X</i> within a group. String and BLOB values that do not look like numbers are interpreted as 0. The result of avg() is always a floating point value even if all inputs are integers. </p></td> </tr> <tr> <td valign="top" align="right">count(<i>X</i>)<br>count(*)</td> <td valign="top">The first form return a count of the number of times that <i>X</i> is not NULL in a group. The second form (with no argument) returns the total number of rows in the group.</td> </tr> <tr> <td valign="top" align="right">max(<i>X</i>)</td> <td valign="top">Return the maximum value of all values in the group. The usual sort order is used to determine the maximum.</td> </tr> <tr> <td valign="top" align="right">min(<i>X</i>)</td> <td valign="top">Return the minimum non-NULL value of all values in the group. The usual sort order is used to determine the minimum. NULL is only returned if all values in the group are NULL.</td> </tr> <tr> <td valign="top" align="right">sum(<i>X</i>)<br>total(<i>X</i>)</td> <td valign="top">Return the numeric sum of all non-NULL values in the group. If there are no non-NULL input rows then sum() returns NULL but total() returns 0.0. NULL is not normally a helpful result for the sum of no rows but the SQL standard requires it and most other SQL database engines implement sum() that way so SQLite does it in the same way in order to be compatible. The non-standard total() function is provided as a convenient way to work around this design problem in the SQL language.</p> <p>The result of total() is always a floating point value. The result of sum() is an integer value if all non-NULL inputs are integers. If any input to sum() is neither an integer or a NULL then sum() returns a floating point value which might be an approximation to the true sum.</p> <p>Sum() will throw an "integer overflow" exception if all inputs are integers or NULL and an integer overflow occurs at any point during the computation. Total() never throws an exception.</p> </tr> </table> } Section INSERT insert Syntax {sql-statement} { INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] VALUES(<value-list>) | INSERT [OR <conflict-algorithm>] INTO [<database-name> .] <table-name> [(<column-list>)] <select-statement> } puts { <p>The INSERT statement comes in two basic forms. The first form (with the "VALUES" keyword) creates a single new row in an existing table. If no column-list is specified then the number of values must be the same as the number of columns in the table. If a column-list is specified, then the number of values must match the number of specified columns. Columns of the table that do not appear in the column list are filled with the default value, or with NULL if no default value is specified. </p> <p>The second form of the INSERT statement takes it data from a SELECT statement. The number of columns in the result of the SELECT must exactly match the number of columns in the table if no column list is specified, or it must match the number of columns name in the column list. A new entry is made in the table for every row of the SELECT result. The SELECT may be simple or compound.</p> <p>The optional conflict-clause allows the specification of an alternative constraint conflict resolution algorithm to use during this one command. See the section titled <a href="#conflict">ON CONFLICT</a> for additional information. For compatibility with MySQL, the parser allows the use of the single keyword <a href="#replace">REPLACE</a> as an alias for "INSERT OR REPLACE". </p> } Section {ON CONFLICT clause} conflict Syntax {conflict-clause} { ON CONFLICT <conflict-algorithm> } {conflict-algorithm} { ROLLBACK | ABORT | FAIL | IGNORE | REPLACE } puts { <p>The ON CONFLICT clause is not a separate SQL command. It is a non-standard clause that can appear in many other SQL commands. It is given its own section in this document because it is not part of standard SQL and therefore might not be familiar.</p> <p>The syntax for the ON CONFLICT clause is as shown above for the CREATE TABLE command. For the INSERT and UPDATE commands, the keywords "ON CONFLICT" are replaced by "OR", to make the syntax seem more natural. For example, instead of "INSERT ON CONFLICT IGNORE" we have "INSERT OR IGNORE". The keywords change but the meaning of the clause is the same either way.</p> <p>The ON CONFLICT clause specifies an algorithm used to resolve constraint conflicts. There are five choices: ROLLBACK, ABORT, FAIL, IGNORE, and REPLACE. The default algorithm is ABORT. This is what they mean:</p> <dl> <dt><b>ROLLBACK</b></dt> <dd><p>When a constraint violation occurs, an immediate ROLLBACK occurs, thus ending the current transaction, and the command aborts with a return code of SQLITE_CONSTRAINT. If no transaction is active (other than the implied transaction that is created on every command) then this algorithm works the same as ABORT.</p></dd> <dt><b>ABORT</b></dt> <dd><p>When a constraint violation occurs, the command backs out any prior changes it might have made and aborts with a return code of SQLITE_CONSTRAINT. But no ROLLBACK is executed so changes from prior commands within the same transaction are preserved. This is the default behavior.</p></dd> <dt><b>FAIL</b></dt> <dd><p>When a constraint violation occurs, the command aborts with a return code SQLITE_CONSTRAINT. But any changes to the database that the command made prior to encountering the constraint violation are preserved and are not backed out. For example, if an UPDATE statement encountered a constraint violation on the 100th row that it attempts to update, then the first 99 row changes are preserved but changes to rows 100 and beyond never occur.</p></dd> <dt><b>IGNORE</b></dt> <dd><p>When a constraint violation occurs, the one row that contains the constraint violation is not inserted or changed. But the command continues executing normally. Other rows before and after the row that contained the constraint violation continue to be inserted or updated normally. No error is returned.</p></dd> <dt><b>REPLACE</b></dt> <dd><p>When a UNIQUE constraint violation occurs, the pre-existing rows that are causing the constraint violation are removed prior to inserting or updating the current row. Thus the insert or update always occurs. The command continues executing normally. No error is returned. If a NOT NULL constraint violation occurs, the NULL value is replaced by the default value for that column. If the column has no default value, then the ABORT algorithm is used. If a CHECK constraint violation occurs then the IGNORE algorithm is used.</p> <p>When this conflict resolution strategy deletes rows in order to satisfy a constraint, it does not invoke delete triggers on those rows. This behavior might change in a future release.</p> </dl> <p>The algorithm specified in the OR clause of a INSERT or UPDATE overrides any algorithm specified in a CREATE TABLE. If no algorithm is specified anywhere, the ABORT algorithm is used.</p> } Section REINDEX reindex Syntax {sql-statement} { REINDEX <collation name> } Syntax {sql-statement} { REINDEX [<database-name> .] <table/index-name> } puts { <p>The REINDEX command is used to delete and recreate indices from scratch. This is useful when the definition of a collation sequence has changed. </p> <p>In the first form, all indices in all attached databases that use the named collation sequence are recreated. In the second form, if <i>[database-name.]table/index-name</i> identifies a table, then all indices associated with the table are rebuilt. If an index is identified, then only this specific index is deleted and recreated. </p> <p>If no <i>database-name</i> is specified and there exists both a table or index and a collation sequence of the specified name, then indices associated with the collation sequence only are reconstructed. This ambiguity may be dispelled by always specifying a <i>database-name</i> when reindexing a specific table or index. } Section REPLACE replace Syntax {sql-statement} { REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] VALUES ( <value-list> ) | REPLACE INTO [<database-name> .] <table-name> [( <column-list> )] <select-statement> } puts { <p>The REPLACE command is an alias for the "INSERT OR REPLACE" variant of the <a href="#insert">INSERT</a> command. This alias is provided for compatibility with MySQL. See the <a href="#insert">INSERT</a> command documentation for additional information.</p> } Section SELECT select Syntax {sql-statement} { SELECT [ALL | DISTINCT] <result> [FROM <table-list>] [WHERE <expr>] [GROUP BY <expr-list>] [HAVING <expr>] [<compound-op> <select>]* [ORDER BY <sort-expr-list>] [LIMIT <integer> [LP OFFSET | , RP <integer>]] } {result} { <result-column> [, <result-column>]* } {result-column} { STAR | <table-name> . STAR | <expr> [ [AS] <string> ] } {table-list} { <table> [<join-op> <table> <join-args>]* } {table} { <table-name> [AS <alias>] | ( <select> ) [AS <alias>] } {join-op} { , | [NATURAL] [LEFT | RIGHT | FULL] [OUTER | INNER | CROSS] JOIN } {join-args} { [ON <expr>] [USING ( <id-list> )] } {sort-expr-list} { <expr> [<sort-order>] [, <expr> [<sort-order>]]* } {sort-order} { [ COLLATE <collation-name> ] [ ASC | DESC ] } {compound_op} { UNION | UNION ALL | INTERSECT | EXCEPT } puts { <p>The SELECT statement is used to query the database. The result of a SELECT is zero or more rows of data where each row has a fixed number of columns. The number of columns in the result is specified by the expression list in between the SELECT and FROM keywords. Any arbitrary expression can be used as a result. If a result expression is } puts "[Operator *] then all columns of all tables are substituted" puts {for that one expression. If the expression is the name of} puts "a table followed by [Operator .*] then the result is all columns" puts {in that one table.</p> <p>The DISTINCT keyword causes a subset of result rows to be returned, in which each result row is different. NULL values are not treated as distinct from each other. The default behavior is that all result rows be returned, which can be made explicit with the keyword ALL.</p> <p>The query is executed against one or more tables specified after the FROM keyword. If multiple tables names are separated by commas, then the query is against the cross join of the various tables. The full SQL-92 join syntax can also be used to specify joins. A sub-query in parentheses may be substituted for any table name in the FROM clause. The entire FROM clause may be omitted, in which case the result is a single row consisting of the values of the expression list. </p> <p>The WHERE clause can be used to limit the number of rows over which the query operates.</p> <p>The GROUP BY clauses causes one or more rows of the result to be combined into a single row of output. This is especially useful when the result contains aggregate functions. The expressions in the GROUP BY clause do <em>not</em> have to be expressions that appear in the result. The HAVING clause is similar to WHERE except that HAVING applies after grouping has occurred. The HAVING expression may refer to values, even aggregate functions, that are not in the result.</p> <p>The ORDER BY clause causes the output rows to be sorted. The argument to ORDER BY is a list of expressions that are used as the key for the sort. The expressions do not have to be part of the result for a simple SELECT, but in a compound SELECT each sort expression must exactly match one of the result columns. Each sort expression may be optionally followed by a COLLATE keyword and the name of a collating function used for ordering text and/or keywords ASC or DESC to specify the sort order.</p> <p>The LIMIT clause places an upper bound on the number of rows returned in the result. A negative LIMIT indicates no upper bound. The optional OFFSET following LIMIT specifies how many rows to skip at the beginning of the result set. In a compound query, the LIMIT clause may only appear on the final SELECT statement. The limit is applied to the entire query not to the individual SELECT statement to which it is attached. Note that if the OFFSET keyword is used in the LIMIT clause, then the limit is the first number and the offset is the second number. If a comma is used instead of the OFFSET keyword, then the offset is the first number and the limit is the second number. This seeming contradition is intentional - it maximizes compatibility with legacy SQL database systems. </p> <p>A compound SELECT is formed from two or more simple SELECTs connected by one of the operators UNION, UNION ALL, INTERSECT, or EXCEPT. In a compound SELECT, all the constituent SELECTs must specify the same number of result columns. There may be only a single ORDER BY clause at the end of the compound SELECT. The UNION and UNION ALL operators combine the results of the SELECTs to the right and left into a single big table. The difference is that in UNION all result rows are distinct where in UNION ALL there may be duplicates. The INTERSECT operator takes the intersection of the results of the left and right SELECTs. EXCEPT takes the result of left SELECT after removing the results of the right SELECT. When three or more SELECTs are connected into a compound, they group from left to right.</p> } Section UPDATE update Syntax {sql-statement} { UPDATE [ OR <conflict-algorithm> ] [<database-name> .] <table-name> SET <assignment> [, <assignment>]* [WHERE <expr>] } {assignment} { <column-name> = <expr> } puts { <p>The UPDATE statement is used to change the value of columns in selected rows of a table. Each assignment in an UPDATE specifies a column name to the left of the equals sign and an arbitrary expression to the right. The expressions may use the values of other columns. All expressions are evaluated before any assignments are made. A WHERE clause can be used to restrict which rows are updated.</p> <p>The optional conflict-clause allows the specification of an alternative constraint conflict resolution algorithm to use during this one command. See the section titled <a href="#conflict">ON CONFLICT</a> for additional information.</p> } Section VACUUM vacuum Syntax {sql-statement} { VACUUM [<index-or-table-name>] } puts { <p>The VACUUM command is an SQLite extension modeled after a similar command found in PostgreSQL. If VACUUM is invoked with the name of a table or index then it is suppose to clean up the named table or index. In version 1.0 of SQLite, the VACUUM command would invoke <b>gdbm_reorganize()</b> to clean up the backend database file.</p> <p> VACUUM became a no-op when the GDBM backend was removed from SQLITE in version 2.0.0. VACUUM was reimplemented in version 2.8.1. The index or table name argument is now ignored. </p> <p>When an object (table, index, or trigger) is dropped from the database, it leaves behind empty space. This makes the database file larger than it needs to be, but can speed up inserts. In time inserts and deletes can leave the database file structure fragmented, which slows down disk access to the database contents. 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> <p>The VACUUM command may change the <a href="lang_createtable.html#rowid">ROWID</a> of entires in tables that do not have an explicit INTEGER PRIMARY KEY.</p> <p>VACUUM only works on the main database. It is not possible to VACUUM an attached database file.</p> <p>The VACUUM command will fail if there is an active transaction. The VACUUM command is a no-op for in-memory databases.</p> <p>As of SQLite version 3.1, an alternative to using the VACUUM command is auto-vacuum mode, enabled using the <a href="pragma.html#pragma_auto_vacuum">auto_vacuum pragma</a>. 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> } # A list of keywords. A asterisk occurs after the keyword if it is on # the fallback list. # set keyword_list [lsort { ABORT* ADD AFTER* ALL ALTER ANALYZE* AND AS ASC* ATTACH* AUTOINCREMENT BEFORE* BEGIN* BETWEEN BY CASCADE* CASE CAST* CHECK COLLATE COMMIT CONFLICT* CONSTRAINT CREATE CROSS CURRENT_DATE* CURRENT_TIME* CURRENT_TIMESTAMP* DATABASE* DEFAULT DEFERRED* DEFERRABLE DELETE DESC* DETACH* DISTINCT DROP END* EACH* ELSE ESCAPE EXCEPT EXCLUSIVE* EXPLAIN* FAIL* FOR* FOREIGN FROM FULL GLOB* GROUP HAVING IF* IGNORE* IMMEDIATE* IN INDEX INITIALLY* INNER INSERT INSTEAD* INTERSECT INTO IS ISNULL JOIN KEY* LEFT LIKE* LIMIT MATCH* NATURAL NOT NOTNULL NULL OF* OFFSET* ON OR ORDER OUTER PLAN* PRAGMA* PRIMARY QUERY* RAISE* REFERENCES REINDEX* RENAME* REPLACE* RESTRICT* RIGHT ROLLBACK ROW* SELECT SET TABLE TEMP* TEMPORARY* THEN TO TRANSACTION TRIGGER* UNION UNIQUE UPDATE USING VACUUM* VALUES VIEW* VIRTUAL* WHEN WHERE }] puts {<DIV class="pdf_section">} Section {SQLite Keywords} keywords puts {</DIV>} puts { <p>The SQL standard specifies a huge number of keywords which may not be used as the names of tables, indices, columns, databases, user-defined functions, collations, virtual table modules, or any other named object. The list of keywords is so long that few people can remember them all. For most SQL code, your safest bet is to never use any English language word as the name of a user-defined object.</p> <p>If you want to use a keyword as a name, you need to quote it. There are three ways of quoting keywords in SQLite:</p> <p> <blockquote> <table class="pdf_functions"> <tr> <td valign="top"><b>'keyword'</b></td><td width="20"></td> <td>A keyword in single quotes is interpreted as a literal string if it occurs in a context where a string literal is allowed, otherwise it is understood as an identifier.</td></tr> <tr> <td valign="top"><b>"keyword"</b></td><td></td> <td>A keyword in double-quotes is interpreted as an identifier if it matches a known identifier. Otherwise it is interpreted as a string literal.</td></tr> <tr> <td valign="top"><b>[keyword]</b></td><td></td> <td>A keyword enclosed in square brackets is always understood as an identifier. This is not standard SQL. This quoting mechanism is used by MS Access and SQL Server and is included in SQLite for compatibility.</td></tr> </table> </blockquote> </p> <p>Quoted keywords are unaesthetic. To help you avoid them, SQLite allows many keywords to be used unquoted as the names of databases, tables, indices, triggers, views, columns, user-defined functions, collations, attached databases, and virtual function modules. In the list of keywords that follows, those that can be used as identifiers are shown in an italic font. Keywords that must be quoted in order to be used as identifiers are shown in bold.</p> <p> SQLite adds new keywords from time to time when it take on new features. So to prevent your code from being broken by future enhancements, you should normally quote any indentifier that is an English language word, even if you do not have to. </p> <p> The following are the keywords currently recognized by SQLite: </p> <blockquote> <table width="100%" class="pdf_keywords"> <tr> <td align="left" valign="top" width="20%"> } set n [llength $keyword_list] set nCol 5 set nRow [expr {($n+$nCol-1)/$nCol}] set i 0 foreach word $keyword_list { if {[string index $word end]=="*"} { set word [string range $word 0 end-1] set font i } else { set font b } if {$i==$nRow} { puts "</td><td valign=\"top\" align=\"left\" width=\"20%\">" set i 1 } else { incr i } puts "<$font>$word</$font><br>" } puts { </td></tr></table></blockquote> <h2>Special names</h2> <p>The following are not keywords in SQLite, but are used as names of system objects. They can be used as an identifier for a different type of object.</p> <blockquote class="pdf_keywords"><b> _ROWID_<br> MAIN<br> OID<br> ROWID<br> SQLITE_MASTER<br> SQLITE_SEQUENCE<br> SQLITE_TEMP_MASTER<br> TEMP<br> </b></blockquote> } puts {<DIV class="pdf_ignore">} footer $rcsid if {[string length $outputdir]} { footer $rcsid } puts {</DIV>} } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 | <title>Implementation Limits For SQLite</title> <h2>Limits In SQLite</h2> <p> "Limits" in the context of this article means sizes or quantities that can not be exceeded. We are concerned with things like the maximum number of bytes in a BLOB or the maximum number of columns in a table. </p> <p> SQLite was originally designed with a policy of avoiding arbitrary limits. Of course, every program that runs on a machine with finite memory and disk space has limits of some kind. But in SQLite, those limits were not well defined. The policy was that if it would fit in memory and you could count it with a 32-bit integer, then it should work. </p> <p> Unfortunately, the no-limits policy has been shown to create problems. Because the upper bounds were not well defined, they were not tested, and bugs (including possible security exploits) were often found when pushing SQLite to extremes. For this reason, newer versions of SQLite have well-defined limits and those limits are tested as part of the test suite. </p> <p> This article defines what the limits of SQLite are and how they can be customized for specific applications. The default settings for limits are normally quite large and adequate for almost every application. Some applications may what to increase a limit here or there, but we expect such needs to be rare. More commonly, an application might want to recompile SQLite with much lower limits to avoid excess resource utilization in the event of bug in higher-level SQL statement generators or to help thwart attackers who inject malicious SQL statements. </p> } proc limititem {title text} { puts "<li><p><b>$title</b></p>\n$text</li>" } puts { <ol> } limititem {Maximum length of a string or BLOB} { <p> The maximum number of bytes in a string or BLOB in SQLite is defined by the preprocessor macro SQLITE_MAX_LENGTH. The default value of this macro is 1 billion (1 thousand million or 1,000,000,000). You can raise or lower this value at compile-time using a command-line option like this: </p> <blockquote>-DSQLITE_MAX_LENGTH=123456789</blockquote> <p> The current implementation will only support a string or BLOB length up to 2<small><sup>31</sup></small>-1 or 2147483647. And some built-in functions such as hex() might fail well before that point. In security-sensitive applications it is best not to try to increase the maximum string and blob length. In fact, you might do well to lower the maximum string and blob length to something more in the range of a few million if that is possible. </p> <p> During part of SQLite's INSERT and SELECT processing, the complete content of each row in the database is encoded as a single BLOB. So the SQLITE_MAX_LENGTH parameter also determines the maximum number of bytes in a row. </p> } limititem {Maximum Number Of Columns} { <p> The SQLITE_MAX_COLUMN compile-time parameter is used to set an upper bound on: </p> <ul> <li>The number of columns in a table</li> <li>The number of columns in an index</li> <li>The number of columns in a view</li> <li>The number of terms in the SET clause of an UPDATE statement</li> <li>The number of columns in the result set of a SELECT statement</li> <li>The number of terms in a GROUP BY or ORDER BY clause</li> <li>The number of values in an INSERT statement</li> </ul> <p> The default setting for SQLITE_MAX_COLUMN is 2000. You can change it at compile time to values as large as 32676. You might be able to redefine this value to be as large as billions, though nobody has ever tried doing that so we do not know if it will work. On the other hand, there are people who will argue that a well-normalized database design will never need a value larger than about 100. </p> <p> In most applications, the number of columns is small - a few dozen. There are places in the SQLite code generator that use algorithms that are O(N²) where N is the number of columns. So if you redefine SQLITE_MAX_COLUMN to be a really huge number and you generate SQL that uses a large number of columns, you may find that <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> runs slowly. } limititem {Maximum Length Of An SQL Statement} { <p> The maximum number of bytes in the text of an SQL statement is limited to SQLITE_MAX_SQL_LENGTH which defaults to 1000000. You can redefine this limit to be as large as the smaller of SQLITE_MAX_LENGTH and 1073741824. </p> <p> If an SQL statement is limited to be a million bytes in length, then obviously you will not be able to insert multi-million byte strings by embedding them as literals inside of INSERT statements. But you should not do that anyway. Use host parameters for your data. Prepare short SQL statements like this: </p> <blockquote> INSERT INTO tab1 VALUES(?,?,?); </blockquote> <p> Then use the <a href="capi3ref.html#sqlite3_bind_text">sqlite3_bind_XXXX()</a> functions to bind your large string values to the SQL statement. The use of binding obviates the need to escape quote characters in the string, reducing the risk of SQL injection attacks. It is also runs faster since the large string does not need to be parsed or copied as much. </p> } limititem {Maximum Number Of Tables In A Join} { <p> SQLite does not support joins containing more than 64 tables. This limit arises from the fact that the SQLite code generator uses bitmaps with one bit per join-table in the query optimizer. </p> } limititem {Maximum Depth Of An Expression Tree} { <p> SQLite parses expressions into a tree for processing. During code generation, SQLite walks this tree recursively. The depth of expression trees is therefore limited in order to avoid using too much stack space. </p> <p> The SQLITE_MAX_EXPR_DEPTH parameter determines the maximum expression tree depth. If the value is 0, then no limit is enforced. The current implementation has a default value of 1000. </p> } limititem {Maximum Number Of Arguments On A Function} { <p> The SQLITE_MAX_FUNCTION_ARG parameter determines the maximum number of parameters that can be passed to an SQL function. The default value of this limit is 100. We know of no technical reason why SQLite would not work with functions that have millions of parameters. However, we suspect that anybody who tries to invoke a function with millions of parameters is really trying to find security exploits in systems that use SQLite, not do useful work, and so for that reason we have set this parameter relatively low. } limititem {Maximum Number Of Terms In A Compound SELECT Statement} { <p> A compound SELECT statement is two or more SELECT statements connected by operators UNION, UNION ALL, EXCEPT, or INTERSECT. We call each individual SELECT statement within a compound SELECT a "term". </p> <p> The code generator in SQLite processes compound SELECT statements using a recursive algorithm. In order to limit the size of the stack, we therefore limit the number of terms in a compound SELECT. The maximum number of terms is SQLITE_MAX_COMPOUND_SELECT which defaults to 500. We think this is a generous allotment since in practice we almost never see the number of terms in a compound select exceed single digits. </p> } limititem {Maximum Length Of A LIKE Or GLOB Pattern} { <p> The pattern matching algorithm used in the default LIKE and GLOB implementation of SQLite can exhibit O(N²) performance (where N is the number of characters in the pattern) for certain pathological cases. To avoid denial-of-service attacks from miscreants who are able to specify their own LIKE or GLOB patterns, the length of the LIKE or GLOB pattern is limited to SQLITE_MAX_LIKE_PATTERN_LENGTH bytes. The default value of this limit is 50000. A modern workstation can evaluate even a pathological LIKE or GLOB pattern of 50000 bytes relatively quickly. The denial of service problem only comes into play when the pattern length gets into millions of bytes. Nevertheless, since most useful LIKE or GLOB patterns are at most a few dozen bytes in length, paranoid application developers may want to reduce this parameter to something in the range of a few hundred if they know that external users are able to generate arbitrary patterns. </p> } limititem {Maximum Number Of Host Parameters In A Single SQL Statement} { <p> A host parameter is a place-holder in an SQL statement that is filled in using one of the <a href="capi3ref.html#sqlite3_bind_blob">sqlite3_bind_XXXX()</a> interfaces. Many SQL programmers are familiar with using a question mark ("?") as a host parameter. SQLite also supports named host parameters prefaced by ":", "$", or "@" and numbered host parameters of the form "?123". </p> <p> Each host parameter in an SQLite statement is assigned a number. The numbers normally begin with 1 and increase by one with each new parameter. However, when the "?123" form is used, the host parameter number is the number that follows the question mark. </p> <p> The maximum value of a host parameter number is SQLITE_MAX_VARIABLE_NUMBER. This setting defaults to 999. </p> } limititem {Maximum Number Of Attached Databases} { <p> The <a href="lang_attach.html">ATTACH</a> statement is an SQLite extension that allows two or more databases to be associated to the same database connection and to operate as if they were a single database. The number of simulataneously attached databases is limited to SQLITE_MAX_ATTACHED which is set to 10 by default. The code generator in SQLite uses bitmaps to keep track of attached databases. That means that the number of attached databases cannot be increased above 30 on a 32-bit machine or 62 on a 64-bit machine. } limititem {Maximum Database Page Size} { <p> An SQLite database file is organized as pages. The size of each page is a power of 2 between 512 and SQLITE_MAX_PAGE_SIZE. The default value for SQLITE_MAX_PAGE_SIZE is 32768. The current implementation will not support a larger value. </p> <p> It used to be the case that SQLite would allocate some stack structures whose size was proportional to the maximum page size. For this reason, SQLite would sometimes be compiled with a smaller maximum page size on embedded devices with limited stack memory. But more recent versions of SQLite put these large structures on the heap, not on the stack, so reducing the maximum page size is no longer necessary on embedded devices. </p> } limititem {Maximum Number Of Pages In A Database File} { <p> SQLite is able to limit the size of a database file to prevent the database file from growing too large and consuming too much disk or flash space. The SQLITE_MAX_PAGE_COUNT parameter, which is normally set to 1073741823, is the maximum number of pages allowed in a single database file. An attempt to insert new data that would cause the database file to grow larger than this will return SQLITE_FULL. </p> <p> The <a href="pragma.html#pragma_max_page_count"> max_page_count PRAGMA</a> can be used to raise or lower this limit at run-time. </p> <p> Note that the transaction processing in SQLite requires two bits of heap memory for every page in the database file. For databases of a few megabytes in size, this amounts to only a few hundred bytes of heap memory. But for gigabyte-sized databases the amount of heap memory required is getting into the kilobyte range and for terabyte-sized databases, megabytes of heap memory must be allocated and zeroed at each transaction. SQLite will support very large databases in theory, but the current implementation is optimized for the common SQLite use cases of embedded devices and persistent stores for desktop applications. In other words, SQLite is designed for use with databases sized in kilobytes or megabytes not gigabytes. If you are building an application to work with databases that are hundreds of gigabytes or more in size, then you should perhaps consider using a different database engine that is explicitly designed for such large data sets. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 | <title>File Locking And Concurrency In SQLite Version 3</title> <tcl> proc HEADING {level title {label {}}} { global pnum incr pnum($level) foreach i [array names pnum] { if {$i>$level} {set pnum($i) 0} } set h [expr {$level+1}] if {$h>6} {set h 6} set n $pnum(1).$pnum(2) for {set i 3} {$i<=$level} {incr i} { append n .$pnum($i) } if {$label!=""} { puts "<a name=\"$label\"></a>" } puts "<h$h>$n $title</h$h>" } set pnum(1) 0 set pnum(2) 0 set pnum(3) 0 set pnum(4) 0 set pnum(5) 0 set pnum(6) 0 set pnum(7) 0 set pnum(8) 0 HEADING 1 {File Locking And Concurrency In SQLite Version 3} puts { <p>Version 3 of SQLite introduces a more complex locking and journaling mechanism designed to improve concurrency and reduce the writer starvation problem. The new mechanism also allows atomic commits of transactions involving multiple database files. This document describes the new locking mechanism. The intended audience is programmers who want to understand and/or modify the pager code and reviewers working to verify the design of SQLite version 3. </p> } HEADING 1 {Overview} overview puts { <p> Locking and concurrency control are handled by the the <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/pager.c"> pager module</a>. The pager module is responsible for making SQLite "ACID" (Atomic, Consistent, Isolated, and Durable). The pager module makes sure changes happen all at once, that either all changes occur or none of them do, that two or more processes do not try to access the database in incompatible ways at the same time, and that once changes have been written they persist until explicitly deleted. The pager also provides an memory cache of some of the contents of the disk file.</p> <p>The pager is unconcerned with the details of B-Trees, text encodings, indices, and so forth. From the point of view of the pager the database consists of a single file of uniform-sized blocks. Each block is called a "page" and is usually 1024 bytes in size. The pages are numbered beginning with 1. So the first 1024 bytes of the database are called "page 1" and the second 1024 bytes are call "page 2" and so forth. All other encoding details are handled by higher layers of the library. The pager communicates with the operating system using one of several modules (Examples: <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_unix.c"> os_unix.c</a>, <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/os_win.c"> os_win.c</a>) that provides a uniform abstraction for operating system services. </p> <p>The pager module effectively controls access for separate threads, or separate processes, or both. Throughout this document whenever the word "process" is written you may substitute the word "thread" without changing the truth of the statement.</p> } HEADING 1 {Locking} locking puts { <p> From the point of view of a single process, a database file can be in one of five locking states: </p> <p> <table cellpadding="20"> <tr><td valign="top">UNLOCKED</td> <td valign="top"> No locks are held on the database. The database may be neither read nor written. Any internally cached data is considered suspect and subject to verification against the database file before being used. Other processes can read or write the database as their own locking states permit. This is the default state. </td></tr> <tr><td valign="top">SHARED</td> <td valign="top"> The database may be read but not written. Any number of processes can hold SHARED locks at the same time, hence there can be many simultaneous readers. But no other thread or process is allowed to write to the database file while one or more SHARED locks are active. </td></tr> <tr><td valign="top">RESERVED</td> <td valign="top"> A RESERVED lock means that the process is planning on writing to the database file at some point in the future but that it is currently just reading from the file. Only a single RESERVED lock may be active at one time, though multiple SHARED locks can coexist with a single RESERVED lock. RESERVED differs from PENDING in that new SHARED locks can be acquired while there is a RESERVED lock. </td></tr> <tr><td valign="top">PENDING</td> <td valign="top"> A PENDING lock means that the process holding the lock wants to write to the database as soon as possible and is just waiting on all current SHARED locks to clear so that it can get an EXCLUSIVE lock. No new SHARED locks are permitted against the database if a PENDING lock is active, though existing SHARED locks are allowed to continue. </td></tr> <tr><td valign="top">EXCLUSIVE</td> <td valign="top"> An EXCLUSIVE lock is needed in order to write to the database file. Only one EXCLUSIVE lock is allowed on the file and no other locks of any kind are allowed to coexist with an EXCLUSIVE lock. In order to maximize concurrency, SQLite works to minimize the amount of time that EXCLUSIVE locks are held. </td></tr> </table> </p> <p> The operating system interface layer understands and tracks all five locking states described above. The pager module only tracks four of the five locking states. A PENDING lock is always just a temporary stepping stone on the path to an EXCLUSIVE lock and so the pager module does not track PENDING locks. </p> } HEADING 1 {The Rollback Journal} rollback puts { <p>Any time a process wants to make a changes to a database file, it first records enough information in the <em>rollback journal</em> to restore the database file back to its initial condition. Thus, before altering any page of the database, the original contents of that page must be written into the journal. The journal also records the initial size of the database so that if the database file grows it can be truncated back to its original size on a rollback.</p> <p>The rollback journal is a ordinary disk file that has the same name as the database file with the suffix "<tt>-journal</tt>" added.</p> <p>If SQLite is working with multiple databases at the same time (using the ATTACH command) then each database has its own journal. But there is also a separate aggregate journal called the <em>master journal</em>. The master journal does not contain page data used for rolling back changes. Instead the master journal contains the names of the individual file journals for each of the ATTACHed databases. Each of the individual file journals also contain the name of the master journal. If there are no ATTACHed databases (or if none of the ATTACHed database is participating in the current transaction) no master journal is created and the normal rollback journal contains an empty string in the place normally reserved for recording the name of the master journal.</p> <p>A individual file journal is said to be <em>hot</em> if it needs to be rolled back in order to restore the integrity of its database. A hot journal is created when a process is in the middle of a database update and a program or operating system crash or power failure prevents the update from completing. Hot journals are an exception condition. Hot journals exist to recover from crashes and power failures. If everything is working correctly (that is, if there are no crashes or power failures) you will never get a hot journal. </p> <p> If no master journal is involved, then a journal is hot if it exists and its corresponding database file does not have a RESERVED lock. If a master journal is named in the file journal, then the file journal is hot if its master journal exists and there is no RESERVED lock on the corresponding database file. It is important to understand when a journal is hot so the preceding rules will be repeated in bullets: </p> <ul> <li>A journal is hot if... <ul> <li>It exists, and</li> <li>It's master journal exists or the master journal name is an empty string, and</li> <li>There is no RESERVED lock on the corresponding database file.</li> </ul> </li> </ul> } HEADING 2 {Dealing with hot journals} hot_journals puts { <p> Before reading from a a database file, SQLite always checks to see if that database file has a hot journal. If the file does have a hot journal, then the journal is rolled back before the file is read. In this way, we ensure that the database file is in a consistent state before it is read. </p> <p>When a process wants to read from a database file, it followed the following sequence of steps: </p> <ol> <li>Open the database file and obtain a SHARED lock. If the SHARED lock cannot be obtained, fail immediately and return SQLITE_BUSY.</li> <li>Check to see if the database file has a hot journal. If the file does not have a hot journal, we are done. Return immediately. If there is a hot journal, that journal must be rolled back by the subsequent steps of this algorithm.</li> <li>Acquire a PENDING lock then an EXCLUSIVE lock on the database file. (Note: Do not acquire a RESERVED lock because that would make other processes think the journal was no longer hot.) If we fail to acquire these locks it means another process is already trying to do the rollback. In that case, drop all locks, close the database, and return SQLITE_BUSY. </li> <li>Read the journal file and roll back the changes.</li> <li>Wait for the rolled back changes to be written onto the surface of the disk. This protects the integrity of the database in case another power failure or crash occurs.</li> <li>Delete the journal file.</li> <li>Delete the master journal file if it is safe to do so. This step is optional. It is here only to prevent stale master journals from cluttering up the disk drive. See the discussion below for details.</li> <li>Drop the EXCLUSIVE and PENDING locks but retain the SHARED lock.</li> </ol> <p>After the algorithm above completes successfully, it is safe to read from the database file. Once all reading has completed, the SHARED lock is dropped.</p> } HEADING 2 {Deleting stale master journals} stale_master_journals puts { <p>A stale master journal is a master journal that is no longer being used for anything. There is no requirement that stale master journals be deleted. The only reason for doing so is to free up disk space.</p> <p>A master journal is stale if no individual file journals are pointing to it. To figure out if a master journal is stale, we first read the master journal to obtain the names of all of its file journals. Then we check each of those file journals. If any of the file journals named in the master journal exists and points back to the master journal, then the master journal is not stale. If all file journals are either missing or refer to other master journals or no master journal at all, then the master journal we are testing is stale and can be safely deleted.</p> } HEADING 1 {Writing to a database file} writing puts { <p>To write to a database, a process must first acquire a SHARED lock as described above (possibly rolling back incomplete changes if there is a hot journal). After a SHARED lock is obtained, a RESERVED lock must be acquired. The RESERVED lock signals that the process intends to write to the database at some point in the future. Only one process at a time can hold a RESERVED lock. But other processes can continue to read the database while the RESERVED lock is held. </p> <p>If the process that wants to write is unable to obtain a RESERVED lock, it must mean that another process already has a RESERVED lock. In that case, the write attempt fails and returns SQLITE_BUSY.</p> <p>After obtaining a RESERVED lock, the process that wants to write creates a rollback journal. The header of the journal is initialized with the original size of the database file. Space in the journal header is also reserved for a master journal name, though the master journal name is initially empty.</p> <p>Before making changes to any page of the database, the process writes the original content of that page into the rollback journal. Changes to pages are held in memory at first and are not written to the disk. The original database file remains unaltered, which means that other processes can continue to read the database.</p> <p>Eventually, the writing process will want to update the database file, either because its memory cache has filled up or because it is ready to commit its changes. Before this happens, the writer must make sure no other process is reading the database and that the rollback journal data is safely on the disk surface so that it can be used to rollback incomplete changes in the event of a power failure. The steps are as follows:</p> <ol> <li>Make sure all rollback journal data has actually been written to the surface of the disk (and is not just being held in the operating system's or disk controllers cache) so that if a power failure occurs the data will still be there after power is restored.</li> <li>Obtain a PENDING lock and then an EXCLUSIVE lock on the database file. If other processes are still have SHARED locks, the writer might have to wait until those SHARED locks clear before it is able to obtain an EXCLUSIVE lock.</li> <li>Write all page modifications currently held in memory out to the original database disk file.</li> </ol> <p> If the reason for writing to the database file is because the memory cache was full, then the writer will not commit right away. Instead, the writer might continue to make changes to other pages. Before subsequent changes are written to the database file, the rollback journal must be flushed to disk again. Note also that the EXCLUSIVE lock that the writer obtained in order to write to the database initially must be held until all changes are committed. That means that no other processes are able to access the database from the time the memory cache first spills to disk until the transaction commits. </p> <p> When a writer is ready to commit its changes, it executes the following steps: </p> <ol> <li value="4"> Obtain an EXCLUSIVE lock on the database file and make sure all memory changes have been written to the database file using the algorithm of steps 1-3 above.</li> <li>Flush all database file changes to the disk. Wait for those changes to actually be written onto the disk surface.</li> <li>Delete the journal file. This is the instant when the changes are committed. Prior to deleting the journal file, if a power failure or crash occurs, the next process to open the database will see that it has a hot journal and will roll the changes back. After the journal is deleted, there will no longer be a hot journal and the changes will persist. </li> <li>Drop the EXCLUSIVE and PENDING locks from the database file. </li> </ol> <p>As soon as PENDING lock is released from the database file, other processes can begin reading the database again. In the current implementation, the RESERVED lock is also released, but that is not essential. Future versions of SQLite might provide a "CHECKPOINT" SQL command that will commit all changes made so far within a transaction but retain the RESERVED lock so that additional changes can be made without given any other process an opportunity to write.</p> <p>If a transaction involves multiple databases, then a more complex commit sequence is used, as follows:</p> <ol> <li value="4"> Make sure all individual database files have an EXCLUSIVE lock and a valid journal. <li>Create a master-journal. The name of the master-journal is arbitrary. (The current implementation appends random suffixes to the name of the main database file until it finds a name that does not previously exist.) Fill the master journal with the names of all the individual journals and flush its contents to disk. <li>Write the name of the master journal into all individual journals (in space set aside for that purpose in the headers of the individual journals) and flush the contents of the individual journals to disk and wait for those changes to reach the disk surface. <li>Flush all database file changes to the disk. Wait for those changes to actually be written onto the disk surface.</li> <li>Delete the master journal file. This is the instant when the changes are committed. Prior to deleting the master journal file, if a power failure or crash occurs, the individual file journals will be considered hot and will be rolled back by the next process that attempts to read them. After the master journal has been deleted, the file journals will no longer be considered hot and the changes will persist. </li> <li>Delete all individual journal files. <li>Drop the EXCLUSIVE and PENDING locks from all database files. </li> </ol> } HEADING 2 {Writer starvation} writer_starvation puts { <p>In SQLite version 2, if many processes are reading from the database, it might be the case that there is never a time when there are no active readers. And if there is always at least one read lock on the database, no process would ever be able to make changes to the database because it would be impossible to acquire a write lock. This situation is called <em>writer starvation</em>.</p> <p>SQLite version 3 seeks to avoid writer starvation through the use of the PENDING lock. The PENDING lock allows existing readers to continue but prevents new readers from connecting to the database. So when a process wants to write a busy database, it can set a PENDING lock which will prevent new readers from coming in. Assuming existing readers do eventually complete, all SHARED locks will eventually clear and the writer will be given a chance to make its changes.</p> } HEADING 1 {How To Corrupt Your Database Files} how_to_corrupt puts { <p>The pager module is robust but it is not completely failsafe. It can be subverted. This section attempts to identify and explain the risks.</p> <p> Clearly, a hardware or operating system fault that introduces incorrect data into the middle of the database file or journal will cause problems. Likewise, if a rogue process opens a database file or journal and writes malformed data into the middle of it, then the database will become corrupt. There is not much that can be done about these kinds of problems so they are given no further attention. </p> <p> SQLite uses POSIX advisory locks to implement locking on Unix. On windows it uses the LockFile(), LockFileEx(), and UnlockFile() system calls. SQLite assumes that these system calls all work as advertised. If that is not the case, then database corruption can result. One should note that POSIX advisory locking is known to be buggy or even unimplemented on many NFS implementations (including recent versions of Mac OS X) and that there are reports of locking problems for network filesystems under windows. Your best defense is to not use SQLite for files on a network filesystem. </p> <p> SQLite uses the fsync() system call to flush data to the disk under Unix and it uses the FlushFileBuffers() to do the same under windows. Once again, SQLite assumes that these operating system services function as advertised. But it has been reported that fsync() and FlushFileBuffers() do not always work correctly, especially with inexpensive IDE disks. Apparently some manufactures of IDE disks have defective controller chips that report that data has reached the disk surface when in fact the data is still in volatile cache memory in the disk drive electronics. There are also reports that windows sometimes chooses to ignore FlushFileBuffers() for unspecified reasons. The author cannot verify any of these reports. But if they are true, it means that database corruption is a possibility following an unexpected power loss. These are hardware and/or operating system bugs that SQLite is unable to defend against. </p> <p> If a crash or power failure occurs and results in a hot journal but that journal is deleted, the next process to open the database will not know that it contains changes that need to be rolled back. The rollback will not occur and the database will be left in an inconsistent state. Rollback journals might be deleted for any number of reasons: </p> <ul> <li>An administrator might be cleaning up after an OS crash or power failure, see the journal file, think it is junk, and delete it.</li> <li>Someone (or some process) might rename the database file but fail to also rename its associated journal.</li> <li>If the database file has aliases (hard or soft links) and the file is opened by a different alias than the one used to create the journal, then the journal will not be found. To avoid this problem, you should not create links to SQLite database files.</li> <li>Filesystem corruption following a power failure might cause the journal to be renamed or deleted.</li> </ul> <p> The last (fourth) bullet above merits additional comment. When SQLite creates a journal file on Unix, it opens the directory that contains that file and calls fsync() on the directory, in an effort to push the directory information to disk. But suppose some other process is adding or removing unrelated files to the directory that contains the database and journal at the the moment of a power failure. The supposedly unrelated actions of this other process might result in the journal file being dropped from the directory and moved into "lost+found". This is an unlikely scenario, but it could happen. The best defenses are to use a journaling filesystem or to keep the database and journal in a directory by themselves. </p> <p> For a commit involving multiple databases and a master journal, if the various databases were on different disk volumes and a power failure occurs during the commit, then when the machine comes back up the disks might be remounted with different names. Or some disks might not be mounted at all. When this happens the individual file journals and the master journal might not be able to find each other. The worst outcome from this scenario is that the commit ceases to be atomic. Some databases might be rolled back and others might not. All databases will continue to be self-consistent. To defend against this problem, keep all databases on the same disk volume and/or remount disks using exactly the same names after a power failure. </p> } HEADING 1 {Transaction Control At The SQL Level} transaction_control puts { <p> The changes to locking and concurrency control in SQLite version 3 also introduce some subtle changes in the way transactions work at the SQL language level. By default, SQLite version 3 operates in <em>autocommit</em> mode. In autocommit mode, all changes to the database are committed as soon as all operations associated with the current database connection complete.</p> <p>The SQL command "BEGIN TRANSACTION" (the TRANSACTION keyword is optional) is used to take SQLite out of autocommit mode. Note that the BEGIN command does not acquire any locks on the database. After a BEGIN command, a SHARED lock will be acquired when the first SELECT statement is executed. A RESERVED lock will be acquired when the first INSERT, UPDATE, or DELETE statement is executed. No EXCLUSIVE lock is acquired until either the memory cache fills up and must be spilled to disk or until the transaction commits. In this way, the system delays blocking read access to the file file until the last possible moment. </p> <p>The SQL command "COMMIT" does not actually commit the changes to disk. It just turns autocommit back on. Then, at the conclusion of the command, the regular autocommit logic takes over and causes the actual commit to disk to occur. The SQL command "ROLLBACK" also operates by turning autocommit back on, but it also sets a flag that tells the autocommit logic to rollback rather than commit.</p> <p>If the SQL COMMIT command turns autocommit on and the autocommit logic then tries to commit change but fails because some other process is holding a SHARED lock, then autocommit is turned back off automatically. This allows the user to retry the COMMIT at a later time after the SHARED lock has had an opportunity to clear.</p> <p>If multiple commands are being executed against the same SQLite database connection at the same time, the autocommit is deferred until the very last command completes. For example, if a SELECT statement is being executed, the execution of the command will pause as each row of the result is returned. During this pause other INSERT, UPDATE, or DELETE commands can be executed against other tables in the database. But none of these changes will commit until the original SELECT statement finishes. </p> } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>Notes On How To Build MinGW As A Cross-Compiler</title> <h1 align=center> Notes On How To Build MinGW As A Cross-Compiler </h1> <p><a href="http://www.mingw.org/">MinGW</a> or <a href="http://www.mingw.org/">Minimalist GNU For Windows</a> is a version of the popular GCC compiler that builds Win95/Win98/WinNT binaries. See the website for details.</p> <p>This page describes how you can build MinGW from sources as a cross-compiler running under Linux. Doing so will allow you to construct WinNT binaries from the comfort and convenience of your Unix desktop.</p> <tcl> proc Link {path {file {}}} { if {$file!=""} { set path $path/$file } else { set file $path } puts "<a href=\"$path\">$file</a>" } </tcl> <p>Here are the steps:</p> <ol> <li> <p>Get a copy of source code. You will need the binutils, the compiler, and the MinGW runtime. Each are available separately. As of this writing, Mumit Khan has collected everything you need together in one FTP site: <tcl> set ftpsite \ ftp://ftp.nanotech.wisc.edu/pub/khan/gnu-win32/mingw32/snapshots/gcc-2.95.2-1 Link $ftpsite </tcl> The three files you will need are:</p> <ul> <li> <tcl> Link $ftpsite binutils-19990818-1-src.tar.gz puts </li><li> Link $ftpsite gcc-2.95.2-1-src.tar.gz puts </li><li> Link $ftpsite mingw-20000203.zip </tcl> </li> </ul> <p>Put all the downloads in a directory out of the way. The sequel will assume all downloads are in a directory named <b>~/mingw/download</b>.</p> </li> <li> <p> Create a directory in which to install the new compiler suite and make the new directory writable. Depending on what directory you choose, you might need to become root. The example shell commands that follow will assume the installation directory is <b>/opt/mingw</b> and that your user ID is <b>drh</b>.</p> <blockquote><pre> su mkdir /opt/mingw chown drh /opt/mingw exit </pre></blockquote> </li> <li> <p>Unpack the source tarballs into a separate directory.</p> <blockquote><pre> mkdir ~/mingw/src cd ~/mingw/src tar xzf ../download/binutils-*.tar.gz tar xzf ../download/gcc-*.tar.gz unzip ../download/mingw-*.zip </pre></blockquote> </li> <li> <p>Create a directory in which to put all the build products.</p> <blockquote><pre> mkdir ~/mingw/bld </pre></blockquote> </li> <li> <p>Configure and build binutils and add the results to your PATH.</p> <blockquote><pre> mkdir ~/mingw/bld/binutils cd ~/mingw/bld/binutils ../../src/binutils/configure --prefix=/opt/mingw --target=i386-mingw32 -v make 2>&1 | tee make.out make install 2>&1 | tee make-install.out export PATH=$PATH:/opt/mingw/bin </pre></blockquote> </li> <li> <p>Manually copy the runtime include files into the installation directory before trying to build the compiler.</p> <blockquote><pre> mkdir /opt/mingw/i386-mingw32/include cd ~/mingw/src/mingw-runtime*/mingw/include cp -r * /opt/mingw/i386-mingw32/include </pre></blockquote> </li> <li> <p>Configure and build the compiler</p> <blockquote><pre> mkdir ~/mingw/bld/gcc cd ~/mingw/bld/gcc ../../src/gcc-*/configure --prefix=/opt/mingw --target=i386-mingw32 -v cd gcc make installdirs cd .. make 2>&1 | tee make.out make install </pre></blockquote> </li> <li> <p>Configure and build the MinGW runtime</p> <blockquote><pre> mkdir ~/mingw/bld/runtime cd ~/mingw/bld/runtime ../../src/mingw-runtime*/configure --prefix=/opt/mingw --target=i386-mingw32 -v make install-target-w32api make install </pre></blockquote> </li> </ol> <p>And you are done...</p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 | <title>NULL Handling in SQLite</title> <h2>NULL Handling in SQLite Versus Other Database Engines</h2> <p> The goal is to make SQLite handle NULLs in a standards-compliant way. But the descriptions in the SQL standards on how to handle NULLs seem ambiguous. It is not clear from the standards documents exactly how NULLs should be handled in all circumstances. </p> <p> So instead of going by the standards documents, various popular SQL engines were tested to see how they handle NULLs. The idea was to make SQLite work like all the other engines. A SQL test script was developed and run by volunteers on various SQL RDBMSes and the results of those tests were used to deduce how each engine processed NULL values. The original tests were run in May of 2002. A copy of the test script is found at the end of this document. </p> <p> SQLite was originally coded in such a way that the answer to all questions in the chart below would be "Yes". But the experiments run on other SQL engines showed that none of them worked this way. So SQLite was modified to work the same as Oracle, PostgreSQL, and DB2. This involved making NULLs indistinct for the purposes of the SELECT DISTINCT statement and for the UNION operator in a SELECT. NULLs are still distinct in a UNIQUE column. This seems somewhat arbitrary, but the desire to be compatible with other engines outweighted that objection. </p> <p> It is possible to make SQLite treat NULLs as distinct for the purposes of the SELECT DISTINCT and UNION. To do so, one should change the value of the NULL_ALWAYS_DISTINCT #define in the <tt>sqliteInt.h</tt> source file and recompile. </p> <blockquote> <p> <i>Update 2003-07-13:</i> Since this document was originally written some of the database engines tested have been updated and users have been kind enough to send in corrections to the chart below. The original data showed a wide variety of behaviors, but over time the range of behaviors has converged toward the PostgreSQL/Oracle model. The only significant difference is that Informix and MS-SQL both threat NULLs as indistinct in a UNIQUE column. </p> <p> The fact that NULLs are distinct for UNIQUE columns but are indistinct for SELECT DISTINCT and UNION continues to be puzzling. It seems that NULLs should be either distinct everywhere or nowhere. And the SQL standards documents suggest that NULLs should be distinct everywhere. Yet as of this writing, no SQL engine tested treats NULLs as distinct in a SELECT DISTINCT statement or in a UNION. </p> </blockquote> <p> The following table shows the results of the NULL handling experiments. </p> <table border=1 cellpadding=3 width="100%"> <tr><th>  </th> <th>SQLite</th> <th>PostgreSQL</th> <th>Oracle</th> <th>Informix</th> <th>DB2</th> <th>MS-SQL</th> <th>OCELOT</th> </tr> <tr><td>Adding anything to null gives null</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>Multiplying null by zero gives null</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>nulls are distinct in a UNIQUE column</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>nulls are distinct in SELECT DISTINCT</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> </tr> <tr><td>nulls are distinct in a UNION</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> </tr> <tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>"null OR true" is true</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>"not (null AND false)" is true</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> </table> <table border=1 cellpadding=3 width="100%"> <tr><th>  </th> <th>MySQL<br>3.23.41</th> <th>MySQL<br>4.0.16</th> <th>Firebird</th> <th>SQL<br>Anywhere</th> <th>Borland<br>Interbase</th> </tr> <tr><td>Adding anything to null gives null</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>Multiplying null by zero gives null</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>nulls are distinct in a UNIQUE column</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td> <td valign="center" align="center" bgcolor="#aaaad2">(Note 4)</td> </tr> <tr><td>nulls are distinct in SELECT DISTINCT</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> </tr> <tr><td>nulls are distinct in a UNION</td> <td valign="center" align="center" bgcolor="#aaaad2">(Note 3)</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No (Note 1)</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> </tr> <tr><td>"CASE WHEN null THEN 1 ELSE 0 END" is 0?</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#aaaad2">(Note 5)</td> </tr> <tr><td>"null OR true" is true</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> <tr><td>"not (null AND false)" is true</td> <td valign="center" align="center" bgcolor="#c7a9a9">No</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> <td valign="center" align="center" bgcolor="#a9c7a9">Yes</td> </tr> </table> <table border=0 align="right" cellpadding=0 cellspacing=0> <tr> <td valign="top" rowspan=5>Notes: </td> <td>1. </td> <td>Older versions of firebird omits all NULLs from SELECT DISTINCT and from UNION.</td> </tr> <tr><td>2. </td> <td>Test data unavailable.</td> </tr> <tr><td>3. </td> <td>MySQL version 3.23.41 does not support UNION.</td> </tr> <tr><td>4. </td> <td>DB2, SQL Anywhere, and Borland Interbase do not allow NULLs in a UNIQUE column.</td> </tr> <tr><td>5. </td> <td>Borland Interbase does not support CASE expressions.</td> </tr> </table> <br clear="both"> <p> </p> <p> The following script was used to gather information for the table above. </p> <pre> -- I have about decided that SQL's treatment of NULLs is capricious and cannot be -- deduced by logic. It must be discovered by experiment. To that end, I have -- prepared the following script to test how various SQL databases deal with NULL. -- My aim is to use the information gather from this script to make SQLite as much -- like other databases as possible. -- -- If you could please run this script in your database engine and mail the results -- to me at drh@hwaci.com, that will be a big help. Please be sure to identify the -- database engine you use for this test. Thanks. -- -- If you have to change anything to get this script to run with your database -- engine, please send your revised script together with your results. -- -- Create a test table with data create table t1(a int, b int, c int); insert into t1 values(1,0,0); insert into t1 values(2,0,1); insert into t1 values(3,1,0); insert into t1 values(4,1,1); insert into t1 values(5,null,0); insert into t1 values(6,null,1); insert into t1 values(7,null,null); -- Check to see what CASE does with NULLs in its test expressions select a, case when b<>0 then 1 else 0 end from t1; select a+10, case when not b<>0 then 1 else 0 end from t1; select a+20, case when b<>0 and c<>0 then 1 else 0 end from t1; select a+30, case when not (b<>0 and c<>0) then 1 else 0 end from t1; select a+40, case when b<>0 or c<>0 then 1 else 0 end from t1; select a+50, case when not (b<>0 or c<>0) then 1 else 0 end from t1; select a+60, case b when c then 1 else 0 end from t1; select a+70, case c when b then 1 else 0 end from t1; -- What happens when you multiple a NULL by zero? select a+80, b*0 from t1; select a+90, b*c from t1; -- What happens to NULL for other operators? select a+100, b+c from t1; -- Test the treatment of aggregate operators select count(*), count(b), sum(b), avg(b), min(b), max(b) from t1; -- Check the behavior of NULLs in WHERE clauses select a+110 from t1 where b<10; select a+120 from t1 where not b>10; select a+130 from t1 where b<10 OR c=1; select a+140 from t1 where b<10 AND c=1; select a+150 from t1 where not (b<10 AND c=1); select a+160 from t1 where not (c=1 AND b<10); -- Check the behavior of NULLs in a DISTINCT query select distinct b from t1; -- Check the behavior of NULLs in a UNION query select b from t1 union select b from t1; -- Create a new table with a unique column. Check to see if NULLs are considered -- to be distinct. create table t2(a int, b int unique); insert into t2 values(1,1); insert into t2 values(2,null); insert into t2 values(3,null); select * from t2; drop table t1; drop table t2; </pre> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 | <title>SQLite Older News</title> <tcl> proc newsitem {date title text} { puts "<h3>$date - $title</h3>" regsub -all "\n( *\n)+" $text "</p>\n\n<p>" txt puts "<p>$txt</p>" puts "<hr width=\"50%\">" } newsitem {2007-Aug-13} {Version 3.4.2} { While stress-testing the <a href="capi3ref.html#sqlite3_soft_heap_limit">soft_heap_limit</a> feature, a bug that could lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption">database corruption</a> was <a href="http://www.sqlite.org/cvstrac/tktview?tn=2565"> discovered and fixed</a>. Though the consequences of this bug are severe, the chances of hitting it in a typical application are remote. Upgrading is recommended only if you use the <a href="capi3ref.html#sqlite3_soft_heap_limit">sqlite3_soft_heap_limit</a> interface. } newsitem {2007-Jly-20} {Version 3.4.1} { This release fixes a bug in <a href="lang_vacuum.html">VACUUM</a> that can lead to <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption"> database corruption</a>. The bug was introduced in version <a href="changes.html#version_3_3_14">3.3.14</a>. Upgrading is recommended for all users. Also included are a slew of other more routine <a href="changes.html#version_3_4_1">enhancements and bug fixes</a>. } newsitem {2007-Jun-18} {Version 3.4.0} { This release fixes two separate bugs either of which can lead to database corruption. Upgrading is strongly recommended. If you must continue using an older version of SQLite, please at least read about how to avoid these bugs at <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError"> CorruptionFollowingBusyError</a> and <a href="http://www.sqlite.org/cvstrac/tktview?tn=2418">ticket #2418</a> <p> This release also adds explicit <a href="limits.html">limits</a> on the sizes and quantities of things SQLite will handle. The new limits might causes compatibility problems for existing applications that use excessively large strings, BLOBs, tables, or SQL statements. The new limits can be increased at compile-time to work around any problems that arise. Nevertheless, the version number of this release is 3.4.0 instead of 3.3.18 in order to call attention to the possible incompatibility. </p> There are also new features, including <a href="capi3ref.html#sqlite3_blob_open">incremental BLOB I/O</a> and <a href="pragma.html#pragma_incremental_vacuum">incremental vacuum</a>. See the <a href="changes.html#version_3_4_0">change log</a> for additional information. } newsitem {2007-Apr-25} {Version 3.3.17} { This version fixes a bug in the forwards-compatibility logic of SQLite that was causing a database to become unreadable when it should have been read-only. Upgrade from 3.3.16 only if you plan to deploy into a product that might need to be upgraded in the future. For day to day use, it probably does not matter. } newsitem {2007-Apr-18} {Version 3.3.16} { Performance improvements added in 3.3.14 but mistakenly turned off in 3.3.15 have been reinstated. A bug has been fixed that prevented VACUUM from running if a NULL value was in a UNIQUE column. } newsitem {2007-Apr-09} {Version 3.3.15} { An annoying bug introduced in 3.3.14 has been fixed. There are also many enhancements to the test suite. } newsitem {2007-Apr-02} {Version 3.3.14} { This version focuses on performance improvements. If you recompile <a href="http://www.sqlite.org/cvstrac/wiki?p=TheAmalgamation"> the amalgamation</a> using GCC option -O3 (the precompiled binaries use -O2) you may see performance improvements of 35% or more over version 3.3.13 depending on your workload. This version also adds support for <a href="pragma.html#pragma_locking_mode"> exclusive access mode</a>. } newsitem {2007-Feb-13} {Version 3.3.13} { This version fixes a subtle bug in the ORDER BY optimizer that can occur when using joins. There are also a few minor enhancements. Upgrading is recommended. } newsitem {2007-Jan-27} {Version 3.3.12} { The first published build of the previous version used the wrong set of source files. Consequently, many people downloaded a build that was labeled as "3.3.11" but was really 3.3.10. Version 3.3.12 is released to clear up the ambiguity. A couple more bugs have also been fixed and <a href="pragma.html#pragma_integrity_check"> PRAGMA integrity_check</a> has been enhanced. } newsitem {2007-Jan-22} {Version 3.3.11} { Version 3.3.11 fixes for a few more problems in version 3.3.9 that version 3.3.10 failed to catch. Upgrading is recommended. } newsitem {2007-Jan-9} {Version 3.3.10} { Version 3.3.10 fixes several bugs that were introduced by the previous release. Upgrading is recommended. } newsitem {2007-Jan-4} {Version 3.3.9} { Version 3.3.9 fixes bugs that can lead to database corruption under obscure and difficult to reproduce circumstances. See <a href="http://www.sqlite.org/cvstrac/wiki?p=DatabaseCorruption"> DatabaseCorruption</a> in the <a href="http://www.sqlite.org/cvstrac/wiki">wiki</a> for details. This release also adds the new <a href="capi3ref.html#sqlite3_prepare_v2">sqlite3_prepare_v2()</a> API and includes important bug fixes in the command-line shell and enhancements to the query optimizer. Upgrading is recommended. } newsitem {2006-Oct-9} {Version 3.3.8} { Version 3.3.8 adds support for full-text search using the <a href="http://www.sqlite.org/cvstrac/wiki?p=FtsOne">FTS1 module.</a> There are also minor bug fixes. Upgrade only if you want to try out the new full-text search capabilities or if you are having problems with 3.3.7. } newsitem {2006-Aug-12} {Version 3.3.7} { Version 3.3.7 includes support for loadable extensions and virtual tables. But both features are still considered "beta" and their APIs are subject to change in a future release. This release is mostly to make available the minor bug fixes that have accumulated since 3.3.6. Upgrading is not necessary. Do so only if you encounter one of the obscure bugs that have been fixed or if you want to try out the new features. } newsitem {2006-Jun-19} {New Book About SQLite} { <a href="http://www.apress.com/book/bookDisplay.html?bID=10130"> <i>The Definitive Guide to SQLite</i></a>, a new book by <a href="http://www.mikesclutter.com">Mike Owens</a>. is now available from <a href="http://www.apress.com">Apress</a>. The books covers the latest SQLite internals as well as the native C interface and bindings for PHP, Python, Perl, Ruby, Tcl, and Java. Recommended. } newsitem {2006-Jun-6} {Version 3.3.6} { Changes include improved tolerance for windows virus scanners and faster :memory: databases. There are also fixes for several obscure bugs. Upgrade if you are having problems. } newsitem {2006-Apr-5} {Version 3.3.5} { This release fixes many minor bugs and documentation typos and provides some minor new features and performance enhancements. Upgrade only if you are having problems or need one of the new features. } newsitem {2006-Feb-11} {Version 3.3.4} { This release fixes several bugs, including a a blunder that might cause a deadlock on multithreaded systems. Anyone using SQLite in a multithreaded environment should probably upgrade. } newsitem {2006-Jan-31} {Version 3.3.3 stable} { There have been no major problems discovered in version 3.3.2, so we hereby declare the new APIs and language features to be stable and supported. } newsitem {2006-Jan-24} {Version 3.3.2 beta} { More bug fixes and performance improvements as we move closer to a production-ready version 3.3.x. } newsitem {2006-Jan-16} {Version 3.3.1 alpha} { Many bugs found in last week's alpha release have now been fixed and the library is running much faster again. Database connections can now be moved between threads as long as the connection holds no locks at the time it is moved. Thus the common paradigm of maintaining a pool of database connections and handing them off to transient worker threads is now supported. Please help test this new feature. See <a href="http://www.sqlite.org/cvstrac/wiki?p=MultiThreading"> the MultiThreading wiki page</a> for additional information. } newsitem {2006-Jan-10} {Version 3.3.0 alpha} { Version 3.3.0 adds support for CHECK constraints, DESC indices, separate REAL and INTEGER column affinities, a new OS interface layer design, and many other changes. The code passed a regression test but should still be considered alpha. Please report any problems. The file format for version 3.3.0 has changed slightly to support descending indices and a more efficient encoding of boolean values. SQLite 3.3.0 will read and write legacy databases created with any prior version of SQLite 3. But databases created by version 3.3.0 will not be readable or writable by earlier versions of the SQLite. The older file format can be specified at compile-time for those rare cases where it is needed. } newsitem {2005-Dec-19} {Versions 3.2.8 and 2.8.17} { These versions contain one-line changes to 3.2.7 and 2.8.16 to fix a bug that has been present since March of 2002 and version 2.4.0. That bug might possibly cause database corruption if a large INSERT or UPDATE statement within a multi-statement transaction fails due to a uniqueness constraint but the containing transaction commits. } newsitem {2005-Sep-24} {Version 3.2.7} { This version fixes several minor and obscure bugs. Upgrade only if you are having problems. } newsitem {2005-Sep-16} {Version 3.2.6 - Critical Bug Fix} { This version fixes a bug that can result in database corruption if a VACUUM of a 1 gibibyte or larger database fails (perhaps do to running out of disk space or an unexpected power loss) and is later rolled back. <p> Also in this release: The ORDER BY and GROUP BY processing was rewritten to use less memory. Support for COUNT(DISTINCT) was added. The LIKE operator can now be used by the optimizer on columns with COLLATE NOCASE. } newsitem {2005-Aug-27} {Version 3.2.5} { This release fixes a few more lingering bugs in the new code. We expect that this release will be stable and ready for production use. } newsitem {2005-Aug-24} {Version 3.2.4} { This release fixes a bug in the new optimizer that can lead to segfaults when parsing very complex WHERE clauses. } newsitem {2005-Aug-21} {Version 3.2.3} { This release adds the <a href="lang_analyze.html">ANALYZE</a> command, the <a href="lang_expr.html">CAST</a> operator, and many very substantial improvements to the query optimizer. See the <a href="changes.html#version_3_2_3">change log</a> for additional information. } newsitem {2005-Aug-2} {2005 Open Source Award for SQLite} { SQLite and its primary author D. Richard Hipp have been honored with a <a href="http://osdir.com/Article6677.phtml">2005 Open Source Award</a> from Google and O'Reilly.<br clear="right"> } newsitem {2005-Jun-13} {Version 3.2.2} { This release includes numerous minor bug fixes, speed improvements, and code size reductions. There is no reason to upgrade unless you are having problems or unless you just want to. } newsitem {2005-Mar-29} {Version 3.2.1} { This release fixes a memory allocation problem in the new <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a> command. } newsitem {2005-Mar-21} {Version 3.2.0} { The primary purpose for version 3.2.0 is to add support for <a href="lang_altertable.html">ALTER TABLE ADD COLUMN</a>. The new ADD COLUMN capability is made possible by AOL developers supporting and embracing great open-source software. Thanks, AOL! Version 3.2.0 also fixes an obscure but serious bug that was discovered just prior to release. If you have a multi-statement transaction and within that transaction an UPDATE or INSERT statement fails due to a constraint, then you try to rollback the whole transaction, the rollback might not work correctly. See <a href="http://www.sqlite.org/cvstrac/tktview?tn=1171">Ticket #1171</a> for details. Upgrading is recommended for all users. } newsitem {2005-Mar-16} {Version 3.1.6} { Version 3.1.6 fixes a critical bug that can cause database corruption when inserting rows into tables with around 125 columns. This bug was introduced in version 3.0.0. See <a href="http://www.sqlite.org/cvstrac/tktview?tn=1163">Ticket #1163</a> for additional information. } newsitem {2005-Mar-11} {Versions 3.1.4 and 3.1.5 Released} { Version 3.1.4 fixes a critical bug that could cause database corruption if the autovacuum mode of version 3.1.0 is turned on (it is off by default) and a CREATE UNIQUE INDEX is executed within a transaction but fails because the indexed columns are not unique. Anyone using the autovacuum feature and unique indices should upgrade. Version 3.1.5 adds the ability to disable the F_FULLFSYNC ioctl() in OS-X by setting "PRAGMA synchronous=on" instead of the default "PRAGMA synchronous=full". There was an attempt to add this capability in 3.1.4 but it did not work due to a spelling error. } newsitem {2005-Feb-19} {Version 3.1.3 Released} { Version 3.1.3 cleans up some minor issues discovered in version 3.1.2. } newsitem {2005-Feb-15} {Versions 2.8.16 and 3.1.2 Released} { A critical bug in the VACUUM command that can lead to database corruption has been fixed in both the 2.x branch and the main 3.x line. This bug has existed in all prior versions of SQLite. Even though it is unlikely you will ever encounter this bug, it is suggested that all users upgrade. See <a href="http://www.sqlite.org/cvstrac/tktview?tn=1116"> ticket #1116</a>. for additional information. Version 3.1.2 is also the first stable release of the 3.1 series. SQLite 3.1 features added support for correlated subqueries, autovacuum, autoincrement, ALTER TABLE, and other enhancements. See the <a href="http://www.sqlite.org/releasenotes310.html">release notes for version 3.1.0</a> for a detailed description of the changes available in the 3.1 series. } newsitem {2005-Feb-01} {Version 3.1.1 (beta) Released} { Version 3.1.1 (beta) is now available on the website. Verison 3.1.1 is fully backwards compatible with the 3.0 series and features many new features including Autovacuum and correlated subqueries. The <a href="http://www.sqlite.org/releasenotes310.html">release notes</a> From version 3.1.0 apply equally to this release beta. A stable release is expected within a couple of weeks. } newsitem {2005-Jan-21} {Version 3.1.0 (alpha) Released} { Version 3.1.0 (alpha) is now available on the website. Verison 3.1.0 is fully backwards compatible with the 3.0 series and features many new features including Autovacuum and correlated subqueries. See the <a href="http://www.sqlite.org/releasenotes310.html">release notes</a> for details. This is an alpha release. A beta release is expected in about a week with the first stable release to follow after two more weeks. } newsitem {2004-Nov-09} {SQLite at the 2004 International PHP Conference} { There was a talk on the architecture of SQLite and how to optimize SQLite queries at the 2004 International PHP Conference in Frankfurt, Germany. <a href="http://www.sqlite.org/php2004/page-001.html"> Slides</a> from that talk are available. } newsitem {2004-Oct-11} {Version 3.0.8} { Version 3.0.8 of SQLite contains several code optimizations and minor bug fixes and adds support for DEFERRED, IMMEDIATE, and EXCLUSIVE transactions. This is an incremental release. There is no reason to upgrade from version 3.0.7 if that version is working for you. } newsitem {2004-Oct-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 <a href="http://www.tcl.tk/community/tcl2004/"> http://www.tcl.tk/</a> for details. <a href="http://www.sqlite.org/tclconf2004/page-001.html"> Slides</a> from the talk are available. } newsitem {2004-Sep-18} {Version 3.0.7} { Version 3.0 has now been in use by multiple projects for several months with no major difficulties. We consider it stable and ready for production use. } newsitem {2004-Sep-02} {Version 3.0.6 (beta)} { Because of some important changes to sqlite3_step(), we have decided to do an additional beta release prior to the first "stable" release. If no serious problems are discovered in this version, we will release version 3.0 "stable" in about a week. } newsitem {2004-Aug-29} {Version 3.0.5 (beta)} { The fourth beta release of SQLite version 3.0 is now available. The next release is expected to be called "stable". } newsitem {2004-Aug-08} {Version 3.0.4 (beta)} { The third beta release of SQLite version 3.0 is now available. This new beta fixes several bugs including a database corruption problem that can occur when doing a DELETE while a SELECT is pending. Expect at least one more beta before version 3.0 goes final. } newsitem {2004-July-22} {Version 3.0.3 (beta)} { The second beta release of SQLite version 3.0 is now available. This new beta fixes many bugs and adds support for databases with varying page sizes. The next 3.0 release will probably be called a final or stable release. Version 3.0 adds support for internationalization and a new more compact file format. <a href="version3.html">Details.</a> The API and file format have been fixed since 3.0.2. All regression tests pass (over 100000 tests) and the test suite exercises over 95% of the code. SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software. } newsitem {2004-Jly-22} {Version 2.8.15} { SQLite version 2.8.15 is a maintenance release for the version 2.8 series. Version 2.8 continues to be maintained with bug fixes, but no new features will be added to version 2.8. All the changes in this release are minor. If you are not having problems, there is there is no reason to upgrade. } newsitem {2004-Jun-30} {Version 3.0.2 (beta) Released} { The first beta release of SQLite version 3.0 is now available. Version 3.0 adds support for internationalization and a new more compact file format. <a href="version3.html">Details.</a> As of this release, the API and file format are frozen. All regression tests pass (over 100000 tests) and the test suite exercises over 95% of the code. SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software. } newsitem {2004-Jun-25} {Website hacked} { The www.sqlite.org website was hacked sometime around 2004-Jun-22 because the lead SQLite developer failed to properly patch CVS. Evidence suggests that the attacker was unable to elevate privileges above user "cvs". Nevertheless, as a precaution the entire website has been reconstructed from scratch on a fresh machine. All services should be back to normal as of 2004-Jun-28. } newsitem {2004-Jun-18} {Version 3.0.0 (alpha) Released} { The first alpha release of SQLite version 3.0 is available for public review and comment. Version 3.0 enhances internationalization support through the use of UTF-16 and user-defined text collating sequences. BLOBs can now be stored directly, without encoding. A new file format results in databases that are 25% smaller (depending on content). The code is also a little faster. In spite of the many new features, the library footprint is still less than 240KB (x86, gcc -O1). <a href="version3.html">Additional information</a>. Our intent is to freeze the file format and API on 2004-Jul-01. Users are encouraged to review and evaluate this alpha release carefully and submit any feedback prior to that date. The 2.8 series of SQLite will continue to be supported with bug fixes for the foreseeable future. } newsitem {2004-Jun-09} {Version 2.8.14 Released} { SQLite version 2.8.14 is a patch release to the stable 2.8 series. There is no reason to upgrade if 2.8.13 is working ok for you. This is only a bug-fix release. Most development effort is going into version 3.0.0 which is due out soon. } newsitem {2004-May-31} {CVS Access Temporarily Disabled} { Anonymous access to the CVS repository will be suspended for 2 weeks beginning on 2004-June-04. Everyone will still be able to download prepackaged source bundles, create or modify trouble tickets, or view change logs during the CVS service interruption. Full open access to the CVS repository will be restored on 2004-June-18. } newsitem {2004-Apr-23} {Work Begins On SQLite Version 3} { Work has begun on version 3 of SQLite. Version 3 is a major changes to both the C-language API and the underlying file format that will enable SQLite to better support internationalization. The first beta is schedule for release on 2004-July-01. Plans are to continue to support SQLite version 2.8 with bug fixes. But all new development will occur in version 3.0. } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 | <title>SQL Features That SQLite Does Not Implement</title> <h2>SQL Features That SQLite Does Not Implement</h2> <p> Rather than try to list all the features of SQL92 that SQLite does support, it is much easier to list those that it does not. Unsupported features of SQL92 are shown below.</p> <p> The order of this list gives some hint as to when a feature might be added to SQLite. Those features near the top of the list are likely to be added in the near future. There are no immediate plans to add features near the bottom of the list. </p> <table cellpadding="10"> <tcl> proc feature {name desc} { puts "<tr><td valign=\"top\"><b><nobr>$name</nobr></b></td>" puts "<td width=\"10\"> </th>" puts "<td valign=\"top\">$desc</td></tr>" } feature {FOREIGN KEY constraints} { FOREIGN KEY constraints are parsed but are not enforced. } feature {Complete trigger support} { There is some support for triggers but it is not complete. Missing subfeatures include FOR EACH STATEMENT triggers (currently all triggers must be FOR EACH ROW), INSTEAD OF triggers on tables (currently INSTEAD OF triggers are only allowed on views), and recursive triggers - triggers that trigger themselves. } feature {Complete ALTER TABLE support} { Only the RENAME TABLE and ADD COLUMN variants of the ALTER TABLE command are supported. Other kinds of ALTER TABLE operations such as DROP COLUMN, ALTER COLUMN, ADD CONSTRAINT, and so forth are omitted. } feature {Nested transactions} { The current implementation only allows a single active transaction. } feature {RIGHT and FULL OUTER JOIN} { LEFT OUTER JOIN is implemented, but not RIGHT OUTER JOIN or FULL OUTER JOIN. } feature {Writing to VIEWs} { VIEWs in SQLite are read-only. You may not execute a DELETE, INSERT, or UPDATE statement on a view. But you can create a trigger that fires on an attempt to DELETE, INSERT, or UPDATE a view and do what you need in the body of the trigger. } feature {GRANT and REVOKE} { Since SQLite reads and writes an ordinary disk file, the only access permissions that can be applied are the normal file access permissions of the underlying operating system. The GRANT and REVOKE commands commonly found on client/server RDBMSes are not implemented because they would be meaningless for an embedded database engine. } </tcl> </table> <p> If you find other SQL92 features that SQLite does not support, please add them to the Wiki page at <a href="http://www.sqlite.org/cvstrac/wiki?p=UnsupportedSql"> http://www.sqlite.org/cvstrac/wiki?p=Unsupported</a> </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 | <title>SQLite Virtual Machine Opcodes</title> <h2>SQLite Virtual Machine Opcodes</h2> <tcl> set fd [open $::SRC/src/vdbe.c r] set file [read $fd] close $fd set current_op {} foreach line [split $file \n] { set line [string trim $line] if {[string index $line 1]!="*"} { set current_op {} continue } if {[regexp {^/\* Opcode: } $line]} { set current_op [lindex $line 2] set txt [lrange $line 3 end] regsub -all {>} $txt {\>} txt regsub -all {<} $txt {\<} txt set Opcode($current_op:args) $txt lappend OpcodeList $current_op continue } if {$current_op==""} continue if {[regexp {^\*/} $line]} { set current_op {} continue } set line [string trim [string range $line 3 end]] if {$line==""} { append Opcode($current_op:text) \n<p> } else { regsub -all {>} $line {\>} line regsub -all {<} $line {\<} line append Opcode($current_op:text) \n$line } } unset file </tcl> <h3>Introduction</h3> <p>In order to execute an SQL statement, the SQLite library first parses the SQL, analyzes the statement, then generates a short program to execute the statement. The program is generated for a "virtual machine" implemented by the SQLite library. This document describes the operation of that virtual machine.</p> <p>This document is intended as a reference, not a tutorial. A separate <a href="vdbe.html">Virtual Machine Tutorial</a> is available. If you are looking for a narrative description of how the virtual machine works, you should read the tutorial and not this document. Once you have a basic idea of what the virtual machine does, you can refer back to this document for the details on a particular opcode. Unfortunately, the virtual machine tutorial was written for SQLite version 1.0. There are substantial changes in the virtual machine for version 2.0 and the document has not been updated. </p> <p>The source code to the virtual machine is in the <b>vdbe.c</b> source file. All of the opcode definitions further down in this document are contained in comments in the source file. In fact, the opcode table in this document was generated by scanning the <b>vdbe.c</b> source file and extracting the necessary information from comments. So the source code comments are really the canonical source of information about the virtual machine. When in doubt, refer to the source code.</p> <p>Each instruction in the virtual machine consists of an opcode and up to three operands named P1, P2 and P3. P1 may be an arbitrary integer. P2 must be a non-negative integer. P2 is always the jump destination in any operation that might cause a jump. P3 is a null-terminated string or NULL. Some operators use all three operands. Some use one or two. Some operators use none of the operands.<p> <p>The virtual machine begins execution on instruction number 0. Execution continues until (1) a Halt instruction is seen, or (2) the program counter becomes one greater than the address of last instruction, or (3) there is an execution error. When the virtual machine halts, all memory that it allocated is released and all database cursors it may have had open are closed. If the execution stopped due to an error, any pending transactions are terminated and changes made to the database are rolled back.</p> <p>The virtual machine also contains an operand stack of unlimited depth. Many of the opcodes use operands from the stack. See the individual opcode descriptions for details.</p> <p>The virtual machine can have zero or more cursors. Each cursor is a pointer into a single table or index within the database. There can be multiple cursors pointing at the same index or table. All cursors operate independently, even cursors pointing to the same indices or tables. The only way for the virtual machine to interact with a database file is through a cursor. Instructions in the virtual machine can create a new cursor (Open), read data from a cursor (Column), advance the cursor to the next entry in the table (Next) or index (NextIdx), and many other operations. All cursors are automatically closed when the virtual machine terminates.</p> <p>The virtual machine contains an arbitrary number of fixed memory locations with addresses beginning at zero and growing upward. Each memory location can hold an arbitrary string. The memory cells are typically used to hold the result of a scalar SELECT that is part of a larger expression.</p> <p>The virtual machine contains a single sorter. The sorter is able to accumulate records, sort those records, then play the records back in sorted order. The sorter is used to implement the ORDER BY clause of a SELECT statement.</p> <p>The virtual machine contains a single "List". The list stores a list of integers. The list is used to hold the rowids for records of a database table that needs to be modified. The WHERE clause of an UPDATE or DELETE statement scans through the table and writes the rowid of every record to be modified into the list. Then the list is played back and the table is modified in a separate step.</p> <p>The virtual machine can contain an arbitrary number of "Sets". Each set holds an arbitrary number of strings. Sets are used to implement the IN operator with a constant right-hand side.</p> <p>The virtual machine can open a single external file for reading. This external read file is used to implement the COPY command.</p> <p>Finally, the virtual machine can have a single set of aggregators. An aggregator is a device used to implement the GROUP BY clause of a SELECT. An aggregator has one or more slots that can hold values being extracted by the select. The number of slots is the same for all aggregators and is defined by the AggReset operation. At any point in time a single aggregator is current or "has focus". There are operations to read or write to memory slots of the aggregator in focus. There are also operations to change the focus aggregator and to scan through all aggregators.</p> <h3>Viewing Programs Generated By SQLite</h3> <p>Every SQL statement that SQLite interprets results in a program for the virtual machine. But if you precede the SQL statement with the keyword "EXPLAIN" the virtual machine will not execute the program. Instead, the instructions of the program will be returned like a query result. This feature is useful for debugging and for learning how the virtual machine operates.</p> <p>You can use the <b>sqlite</b> command-line tool to see the instructions generated by an SQL statement. The following is an example:</p> <tcl> proc Code {body} { puts {<blockquote><tt>} regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body regsub -all {\(\(\(} $body {<b>} body regsub -all {\)\)\)} $body {</b>} body regsub -all { } $body {\ } body regsub -all \n $body <br>\n body puts $body puts {</tt></blockquote>} } Code { $ (((sqlite ex1))) sqlite> (((.explain))) sqlite> (((explain delete from tbl1 where two<20;))) addr opcode p1 p2 p3 ---- ------------ ----- ----- ---------------------------------------- 0 Transaction 0 0 1 VerifyCookie 219 0 2 ListOpen 0 0 3 Open 0 3 tbl1 4 Rewind 0 0 5 Next 0 12 6 Column 0 1 7 Integer 20 0 8 Ge 0 5 9 Recno 0 0 10 ListWrite 0 0 11 Goto 0 5 12 Close 0 0 13 ListRewind 0 0 14 OpenWrite 0 3 15 ListRead 0 19 16 MoveTo 0 0 17 Delete 0 0 18 Goto 0 15 19 ListClose 0 0 20 Commit 0 0 } </tcl> <p>All you have to do is add the "EXPLAIN" keyword to the front of the SQL statement. But if you use the ".explain" command to <b>sqlite</b> first, it will set up the output mode to make the program more easily viewable.</p> <p>If <b>sqlite</b> has been compiled without the "-DNDEBUG=1" option (that is, with the NDEBUG preprocessor macro not defined) then you can put the SQLite virtual machine in a mode where it will trace its execution by writing messages to standard output. The non-standard SQL "PRAGMA" comments can be used to turn tracing on and off. To turn tracing on, enter: </p> <blockquote><pre> PRAGMA vdbe_trace=on; </pre></blockquote> <p> You can turn tracing back off by entering a similar statement but changing the value "on" to "off".</p> <h3>The Opcodes</h3> <p>There are currently <tcl>puts [llength $OpcodeList]</tcl> opcodes defined by the virtual machine. All currently defined opcodes are described in the table below. This table was generated automatically by scanning the source code from the file <b>vdbe.c</b>.</p> <p><table cellspacing="1" border="1" cellpadding="10"> <tr><th>Opcode Name</th><th>Description</th></tr> <tcl> foreach op [lsort -dictionary $OpcodeList] { puts {<tr><td valign="top" align="center">} puts "<a name=\"$op\"></a>$op" puts "<td>[string trim $Opcode($op:text)]</td></tr>" } </tcl> </table></p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 | <title>The SQLite Query Optimizer Overview</title> <tcl> proc CODE {text} { puts "<blockquote><pre>" puts $text puts "</pre></blockquote>" } proc SYNTAX {text} { puts "<blockquote><pre>" set t2 [string map {& & < < > >} $text] regsub -all "/(\[^\n/\]+)/" $t2 {</b><i>\1</i><b>} t3 puts "<b>$t3</b>" puts "</pre></blockquote>" } proc IMAGE {name {caption {}}} { puts "<center><img src=\"$name\">" if {$caption!=""} { puts "<br>$caption" } puts "</center>" } proc PARAGRAPH {text} { # regsub -all "/(\[a-zA-Z0-9\]+)/" $text {<i>\1</i>} t2 regsub -all "\\*(\[^\n*\]+)\\*" $text {<tt><b><big>\1</big></b></tt>} t3 puts "<p>$t3</p>\n" } set level(0) 0 set level(1) 0 proc HEADING {n name {tag {}}} { if {$tag!=""} { puts "<a name=\"$tag\"></a>" } global level incr level($n) for {set i [expr {$n+1}]} {$i<10} {incr i} { set level($i) 0 } if {$n==0} { set num {} } elseif {$n==1} { set num $level(1).0 } else { set num $level(1) for {set i 2} {$i<=$n} {incr i} { append num .$level($i) } } incr n 1 puts "<h$n>$num $name</h$n>" } HEADING 0 {The SQLite Query Optimizer Overview} PARAGRAPH { This document provides a terse overview of how the query optimizer for SQLite works. This is not a tutorial. The reader is likely to need some prior knowledge of how database engines operate in order to fully understand this text. } HEADING 1 {WHERE clause analysis} where_clause PARAGRAPH { The WHERE clause on a query is broken up into "terms" where each term is separated from the others by an AND operator. } PARAGRAPH { All terms of the WHERE clause are analyzed to see if they can be satisfied using indices. Terms that cannot be satisfied through the use of indices become tests that are evaluated against each row of the relevant input tables. No tests are done for terms that are completely satisfied by indices. Sometimes one or more terms will provide hints to indices but still must be evaluated against each row of the input tables. } PARAGRAPH { The analysis of a term might cause new "virtual" terms to be added to the WHERE clause. Virtual terms can be used with indices to restrict a search. But virtual terms never generate code that is tested against input rows. } PARAGRAPH { To be usable by an index a term must be of one of the following forms: } SYNTAX { /column/ = /expression/ /column/ > /expression/ /column/ >= /expression/ /column/ < /expression/ /column/ <= /expression/ /expression/ = /column/ /expression/ > /column/ /expression/ >= /column/ /expression/ < /column/ /expression/ <= /column/ /column/ IN (/expression-list/) /column/ IN (/subquery/) } PARAGRAPH { If an index is created using a statement like this: } CODE { CREATE INDEX idx_ex1 ON ex1(a,b,c,d,e,...,y,z); } PARAGRAPH { Then the index might be used if the initial columns of the index (columns a, b, and so forth) appear in WHERE clause terms. All index columns must be used with the *=* or *IN* operators except for the right-most column which can use inequalities. For the right-most column of an index that is used, there can be up to two inequalities that must sandwich the allowed values of the column between two extremes. } PARAGRAPH { It is not necessary for every column of an index to appear in a WHERE clause term in order for that index to be used. But there can not be gaps in the columns of the index that are used. Thus for the example index above, if there is no WHERE clause term that constraints column c, then terms that constraint columns a and b can be used with the index but not terms that constraint columns d through z. Similarly, no index column will be used (for indexing purposes) that is to the right of a column that is constrained only by inequalities. For the index above and WHERE clause like this: } CODE { ... WHERE a=5 AND b IN (1,2,3) AND c>12 AND d='hello' } PARAGRAPH { Only columns a, b, and c of the index would be usable. The d column would not be usable because it occurs to the right of c and c is constrained only by inequalities. } HEADING 1 {The BETWEEN optimization} between_opt PARAGRAPH { If a term of the WHERE clause is of the following form: } SYNTAX { /expr1/ BETWEEN /expr2/ AND /expr3/ } PARAGRAPH { Then two virtual terms are added as follows: } SYNTAX { /expr1/ >= /expr2/ AND /expr1/ <= /expr3/ } PARAGRAPH { If both virtual terms end up being used as constraints on an index, then the original BETWEEN term is omitted and the corresponding test is not performed on input rows. Thus if the BETWEEN term ends up being used as an index constraint no tests are ever performed on that term. On the other hand, the virtual terms themselves never causes tests to be performed on input rows. Thus if the BETWEEN term is not used as an index constraint and instead must be used to test input rows, the <i>expr1</i> expression is only evaluated once. } HEADING 1 {The OR optimization} or_opt PARAGRAPH { If a term consists of multiple subterms containing a common column name and separated by OR, like this: } SYNTAX { /column/ = /expr1/ OR /column/ = /expr2/ OR /column/ = /expr3/ OR ... } PARAGRAPH { Then the term is rewritten as follows: } SYNTAX { /column/ IN (/expr1/,/expr2/,/expr3/,/expr4/,...) } PARAGRAPH { The rewritten term then might go on to constraint an index using the normal rules for *IN* operators. Note that <i>column</i> must be the same column in every OR-connected subterm, although the column can occur on either the left or the right side of the *=* operator. } HEADING 1 {The LIKE optimization} like_opt PARAGRAPH { Terms that are composed of the LIKE or GLOB operator can sometimes be used to constrain indices. There are many conditions on this use: } PARAGRAPH { <ol> <li>The left-hand side of the LIKE or GLOB operator must be the name of an indexed column.</li> <li>The right-hand side of the LIKE or GLOB must be a string literal that does not begin with a wildcard character.</li> <li>The ESCAPE clause cannot appear on the LIKE operator.</li> <li>The build-in functions used to implement LIKE and GLOB must not have been overloaded using the sqlite3_create_function() API.</li> <li>For the GLOB operator, the column must use the default BINARY collating sequence.</li> <li>For the LIKE operator, if case_sensitive_like mode is enabled then the column must use the default BINARY collating sequence, or if case_sensitive_like mode is disabled then the column must use the built-in NOCASE collating sequence.</li> </ol> } PARAGRAPH { The LIKE operator has two modes that can be set by a pragma. The default mode is for LIKE comparisons to be insensitive to differences of case for latin1 characters. Thus, by default, the following expression is true: } CODE { 'a' LIKE 'A' } PARAGRAPH { By turned on the case_sensitive_like pragma as follows: } CODE { PRAGMA case_sensitive_like=ON; } PARAGRAPH { Then the LIKE operator pays attention to case and the example above would evaluate to false. Note that case insensitivity only applies to latin1 characters - basically the upper and lower case letters of English in the lower 127 byte codes of ASCII. International character sets are case sensitive in SQLite unless a user-supplied collating sequence is used. But if you employ a user-supplied collating sequence, the LIKE optimization describe here will never be taken. } PARAGRAPH { The LIKE operator is case insensitive by default because this is what the SQL standard requires. You can change the default behavior at compile time by using the -DSQLITE_CASE_SENSITIVE_LIKE command-line option to the compiler. } PARAGRAPH { The LIKE optimization might occur if the column named on the left of the operator uses the BINARY collating sequence (which is the default) and case_sensitive_like is turned on. Or the optimization might occur if the column uses the built-in NOCASE collating sequence and the case_sensitive_like mode is off. These are the only two combinations under which LIKE operators will be optimized. If the column on the right-hand side of the LIKE operator uses any collating sequence other than the built-in BINARY and NOCASE collating sequences, then no optimizations will ever be attempted on the LIKE operator. } PARAGRAPH { The GLOB operator is always case sensitive. The column on the left side of the GLOB operator must always use the built-in BINARY collating sequence or no attempt will be made to optimize that operator with indices. } PARAGRAPH { The right-hand side of the GLOB or LIKE operator must be a literal string value that does not begin with a wildcard. If the right-hand side is a parameter that is bound to a string, then no optimization is attempted. If the right-hand side begins with a wildcard character then no optimization is attempted. } PARAGRAPH { Suppose the initial sequence of non-wildcard characters on the right-hand side of the LIKE or GLOB operator is <i>x</i>. We are using a single character to denote this non-wildcard prefix but the reader should understand that the prefix can consist of more than 1 character. Let <i>y</i> the smallest string that is the same length as /x/ but which compares greater than <i>x</i>. For example, if <i>x</i> is *hello* then <i>y</i> would be *hellp*. The LIKE and GLOB optimizations consist of adding two virtual terms like this: } SYNTAX { /column/ >= /x/ AND /column/ < /y/ } PARAGRAPH { Under most circumstances, the original LIKE or GLOB operator is still tested against each input row even if the virtual terms are used to constrain an index. This is because we do not know what additional constraints may be imposed by characters to the right of the <i>x</i> prefix. However, if there is only a single global wildcard to the right of <i>x</i>, then the original LIKE or GLOB test is disabled. In other words, if the pattern is like this: } SYNTAX { /column/ LIKE /x/% /column/ GLOB /x/* } PARAGRAPH { Then the original LIKE or GLOB tests are disabled when the virtual terms constrain an index because in that case we know that all of the rows selected by the index will pass the LIKE or GLOB test. } HEADING 1 {Joins} joins PARAGRAPH { The current implementation of SQLite uses only loop joins. That is to say, joins are implemented as nested loops. } PARAGRAPH { The default order of the nested loops in a join is for the left-most table in the FROM clause to form the outer loop and the right-most table to form the inner loop. However, SQLite will nest the loops in a different order if doing so will help it to select better indices. } PARAGRAPH { Inner joins can be freely reordered. However a left outer join is neither commutative nor associative and hence will not be reordered. Inner joins to the left and right of the outer join might be reordered if the optimizer thinks that is advantageous but the outer joins are always evaluated in the order in which they occur. } PARAGRAPH { When selecting the order of tables in a join, SQLite uses a greedy algorithm that runs in polynomial time. } PARAGRAPH { The ON and USING clauses of a join are converted into additional terms of the WHERE clause prior to WHERE clause analysis described above in paragraph 1.0. Thus with SQLite, there is no advantage to use the newer SQL92 join syntax over the older SQL89 comma-join syntax. They both end up accomplishing exactly the same thing. } PARAGRAPH { Join reordering is automatic and usually works well enough that programmer do not have to think about it. But occasionally some hints from the programmer are needed. For a description of when hints might be necessary and how to provide those hints, see the <a href="http://www.sqlite.org/cvstrac/wiki?p=QueryPlans">QueryPlans</a> page in the Wiki. } HEADING 1 {Choosing between multiple indices} multi_index PARAGRAPH { Each table in the FROM clause of a query can use at most one index, and SQLite strives to use at least one index on each table. Sometimes, two or more indices might be candidates for use on a single table. For example: } CODE { CREATE TABLE ex2(x,y,z); CREATE INDEX ex2i1 ON ex2(x); CREATE INDEX ex2i2 ON ex2(y); SELECT z FROM ex2 WHERE x=5 AND y=6; } PARAGRAPH { For the SELECT statement above, the optimizer can use the ex2i1 index to lookup rows of ex2 that contain x=5 and then test each row against the y=6 term. Or it can use the ex2i2 index to lookup rows of ex2 that contain y=6 then test each of those rows against the x=5 term. } PARAGRAPH { When faced with a choice of two or more indices, SQLite tries to estimate the total amount of work needed to perform the query using each option. It then selects the option that gives the least estimated work. } PARAGRAPH { To help the optimizer get a more accurate estimate of the work involved in using various indices, the user may optional run the ANALYZE command. The ANALYZE command scans all indices of database where there might be a choice between two or more indices and gathers statistics on the selectiveness of those indices. The results of this scan are stored in the sqlite_stat1 table. The contents of the sqlite_stat1 table are not updated as the database changes so after making significant changes it might be prudent to rerun ANALYZE. The results of an ANALYZE command are only available to database connections that are opened after the ANALYZE command completes. } PARAGRAPH { Once created, the sqlite_stat1 table cannot be dropped. But its content can be viewed, modified, or erased. Erasing the entire content of the sqlite_stat1 table has the effect of undoing the ANALYZE command. Changing the content of the sqlite_stat1 table can get the optimizer deeply confused and cause it to make silly index choices. Making updates to the sqlite_stat1 table (except by running ANALYZE) is not recommended. } PARAGRAPH { Terms of the WHERE clause can be manually disqualified for use with indices by prepending a unary *+* operator to the column name. The unary *+* is a no-op and will not slow down the evaluation of the test specified by the term. But it will prevent the term from constraining an index. So, in the example above, if the query were rewritten as: } CODE { SELECT z FROM ex2 WHERE +x=5 AND y=6; } PARAGRAPH { The *+* operator on the *x* column would prevent that term from constraining an index. This would force the use of the ex2i2 index. } HEADING 1 {Avoidance of table lookups} index_only PARAGRAPH { When doing an indexed lookup of a row, the usual procedure is to do a binary search on the index to find the index entry, then extract the rowid from the index and use that rowid to do a binary search on the original table. Thus a typical indexed lookup involves two binary searches. If, however, all columns that were to be fetched from the table are already available in the index itself, SQLite will use the values contained in the index and will never look up the original table row. This saves one binary search for each row and can make many queries run twice as fast. } HEADING 1 {ORDER BY optimizations} order_by PARAGRAPH { SQLite attempts to use an index to satisfy the ORDER BY clause of a query when possible. When faced with the choice of using an index to satisfy WHERE clause constraints or satisfying an ORDER BY clause, SQLite does the same work analysis described in section 6.0 and chooses the index that it believes will result in the fastest answer. } HEADING 1 {Subquery flattening} flattening PARAGRAPH { When a subquery occurs in the FROM clause of a SELECT, the default behavior is to evaluate the subquery into a transient table, then run the outer SELECT against the transient table. This is problematic since the transient table will not have any indices and the outer query (which is likely a join) will be forced to do a full table scan on the transient table. } PARAGRAPH { To overcome this problem, SQLite attempts to flatten subqueries in the FROM clause of a SELECT. This involves inserting the FROM clause of the subquery into the FROM clause of the outer query and rewriting expressions in the outer query that refer to the result set of the subquery. For example: } CODE { SELECT a FROM (SELECT x+y AS a FROM t1 WHERE z<100) WHERE a>5 } PARAGRAPH { Would be rewritten using query flattening as: } CODE { SELECT x+y AS a FROM t1 WHERE z<100 AND a>5 } PARAGRAPH { There is a long list of conditions that must all be met in order for query flattening to occur. } PARAGRAPH { <ol> <li> The subquery and the outer query do not both use aggregates.</li> <li> The subquery is not an aggregate or the outer query is not a join. </li> <li> The subquery is not the right operand of a left outer join, or the subquery is not itself a join. </li> <li> The subquery is not DISTINCT or the outer query is not a join. </li> <li> The subquery is not DISTINCT or the outer query does not use aggregates. </li> <li> The subquery does not use aggregates or the outer query is not DISTINCT. </li> <li> The subquery has a FROM clause. </li> <li> The subquery does not use LIMIT or the outer query is not a join. </li> <li> The subquery does not use LIMIT or the outer query does not use aggregates. </li> <li> The subquery does not use aggregates or the outer query does not use LIMIT. </li> <li> The subquery and the outer query do not both have ORDER BY clauses.</li> <li> The subquery is not the right term of a LEFT OUTER JOIN or the subquery has no WHERE clause. </li> </ol> } PARAGRAPH { The proof that query flattening may safely occur if all of the the above conditions are met is left as an exercise to the reader. } PARAGRAPH { Query flattening is an important optimization when views are used as each use of a view is translated into a subquery. } HEADING 1 {The MIN/MAX optimization} minmax PARAGRAPH { Queries of the following forms will be optimized to run in logarithmic time assuming appropriate indices exist: } CODE { SELECT MIN(x) FROM table; SELECT MAX(x) FROM table; } PARAGRAPH { In order for these optimizations to occur, they must appear in exactly the form shown above - changing only the name of the table and column. It is not permissible to add a WHERE clause or do any arithmetic on the result. The result set must contain a single column. The column in the MIN or MAX function must be an indexed column. } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 | <title>Pragma statements supported by SQLite</title> <tcl> proc Section {name {label {}}} { puts "\n<hr />" if {$label!=""} { puts "<a name=\"$label\"></a>" } puts "<h1>$name</h1>\n" } </tcl> <p>The <a href="#syntax">PRAGMA command</a> is a special command used to modify the operation of the SQLite library or to query the library for internal (non-table) data. The PRAGMA command is issued using the same interface as other SQLite commands (e.g. SELECT, INSERT) but is different in the following important respects: </p> <ul> <li>Specific pragma statements may be removed and others added in future releases of SQLite. Use with caution! <li>No error messages are generated if an unknown pragma is issued. Unknown pragmas are simply ignored. This means if there is a typo in a pragma statement the library does not inform the user of the fact. <li>Some pragmas take effect during the SQL compilation stage, not the execution stage. This means if using the C-language sqlite3_prepare(), sqlite3_step(), sqlite3_finalize() API (or similar in a wrapper interface), the pragma may be applied to the library during the sqlite3_prepare() call. <li>The pragma command is unlikely to be compatible with any other SQL engine. </ul> <p>The available pragmas fall into four basic categories:</p> <ul> <li>Pragmas used to <a href="#modify">modify the operation</a> of the SQLite library in some manner, or to query for the current mode of operation. <li>Pragmas used to <a href="#schema">query the schema</a> of the current database. <li>Pragmas used to <a href="#version">query or modify the databases two version values</a>, the schema-version and the user-version. <li>Pragmas used to <a href="#debug">debug the library</a> and verify that database files are not corrupted. </ul> <tcl> Section {PRAGMA command syntax} syntax Syntax {sql-statement} { PRAGMA <name> [= <value>] | PRAGMA <function>(<arg>) } </tcl> <p>The pragmas that take an integer <b><i>value</i></b> also accept symbolic names. The strings "<b>on</b>", "<b>true</b>", and "<b>yes</b>" are equivalent to <b>1</b>. The strings "<b>off</b>", "<b>false</b>", and "<b>no</b>" are equivalent to <b>0</b>. These strings are case- insensitive, and do not require quotes. An unrecognized string will be treated as <b>1</b>, and will not generate an error. When the <i>value</i> is returned it is as an integer.</p> <tcl>Section {Pragmas to modify library operation} modify</tcl> <ul> <a name="pragma_auto_vacuum"></a> <li><p><b>PRAGMA auto_vacuum;<br> PRAGMA auto_vacuum = </b> <i>0 | none | 1 | full | 2 | incremental</i><b>;</b></p> <p>Query or set the auto-vacuum flag in the database.</p> <p>Normally, (that is to say when auto_vacuum is 0 or "none") when a transaction that deletes data from a database is committed, the database file remains the same size. Unused database file pages are added to a "freelist" are reused for subsequent inserts. The database file does not shrink. In this mode the <a href="lang_vacuum.html">VACUUM</a> command can be used to reclaim unused space.</p> <p>When the auto-vacuum flag is 1 (full), the freelist pages are moved to the end of the file and the file is truncated to remove the freelist pages at every commit. Note, however, that auto-vacuum only truncates the freelist pages from the file. Auto-vacuum does not defragment the database nor repack individual database pages the way that the <a href="lang_vacuum.html">VACUUM</a> command does. In fact, because it moves pages around within the file, auto-vacuum can actually make fragmentation worse.</p> <p>Auto-vacuuming is only possible if the database stores some additional information that allows each database page to be traced backwards to its referer. Therefore, auto-vacuuming must be turned on before any tables are created. It is not possible to enable or disable auto-vacuum after a table has been created.</p> <p>When the value of auto-vacuum is 2 (incremental) then the additional information needed to do autovacuuming is stored in the database file but autovacuuming does not occur automatically at each commit as it does with auto_vacuum==full. In incremental mode, the separate <a href="#pragma_incremental_vacuum">incremental_vacuum</a> pragma must be invoked to cause the vacuum to occur.</p> <p>The database connection can be changed between full and incremental autovacuum mode at will. However, the connection cannot be changed in and out of the "none" mode after any table has been created in the database. </p></li> <a name="pragma_cache_size"></a> <li><p><b>PRAGMA cache_size; <br>PRAGMA cache_size = </b><i>Number-of-pages</i><b>;</b></p> <p>Query or change the maximum number of database disk pages that SQLite will hold in memory at once. Each page uses about 1.5K of memory. The default cache size is 2000. If you are doing UPDATEs or DELETEs that change many rows of a database and you do not mind if SQLite uses more memory, you can increase the cache size for a possible speed improvement.</p> <p>When you change the cache size using the cache_size pragma, the change only endures for the current session. The cache size reverts to the default value when the database is closed and reopened. Use the <a href="#pragma_default_cache_size"><b>default_cache_size</b></a> pragma to check the cache size permanently.</p></li> <a name="pragma_case_sensitive_like"></a> <li><p><b>PRAGMA case_sensitive_like; <br>PRAGMA case_sensitive_like = </b><i>0 | 1</i><b>;</b></p> <p>The default behavior of the LIKE operator is to ignore case for latin1 characters. Hence, by default <b>'a' LIKE 'A'</b> is true. The case_sensitive_like pragma can be turned on to change this behavior. When case_sensitive_like is enabled, <b>'a' LIKE 'A'</b> is false but <b>'a' LIKE 'a'</b> is still true.</p> </li> <a name="pragma_count_changes"></a> <li><p><b>PRAGMA count_changes; <br>PRAGMA count_changes = </b><i>0 | 1</i><b>;</b></p> <p>Query or change the count-changes flag. Normally, when the count-changes flag is not set, INSERT, UPDATE and DELETE statements return no data. When count-changes is set, each of these commands returns a single row of data consisting of one integer value - the number of rows inserted, modified or deleted by the command. The returned change count does not include any insertions, modifications or deletions performed by triggers.</p> <a name="pragma_default_cache_size"></a> <li><p><b>PRAGMA default_cache_size; <br>PRAGMA default_cache_size = </b><i>Number-of-pages</i><b>;</b></p> <p>Query or change the maximum number of database disk pages that SQLite will hold in memory at once. Each page uses 1K on disk and about 1.5K in memory. This pragma works like the <a href="#pragma_cache_size"><b>cache_size</b></a> pragma with the additional feature that it changes the cache size persistently. With this pragma, you can set the cache size once and that setting is retained and reused every time you reopen the database.</p></li> <a name="pragma_default_synchronous"></a> <li><p><b>PRAGMA default_synchronous;</b></p> <p>This pragma was available in version 2.8 but was removed in version 3.0. It is a dangerous pragma whose use is discouraged. To help dissuide users of version 2.8 from employing this pragma, the documentation will not tell you what it does.</p></li> <a name="pragma_empty_result_callbacks"></a> <li><p><b>PRAGMA empty_result_callbacks; <br>PRAGMA empty_result_callbacks = </b><i>0 | 1</i><b>;</b></p> <p>Query or change the empty-result-callbacks flag.</p> <p>The empty-result-callbacks flag affects the sqlite3_exec API only. Normally, when the empty-result-callbacks flag is cleared, the callback function supplied to the sqlite3_exec() call is not invoked for commands that return zero rows of data. When empty-result-callbacks is set in this situation, the callback function is invoked exactly once, with the third parameter set to 0 (NULL). This is to enable programs that use the sqlite3_exec() API to retrieve column-names even when a query returns no data. </p> <a name="pragma_encoding"></a> <li><p><b>PRAGMA encoding; <br>PRAGMA encoding = "UTF-8"; <br>PRAGMA encoding = "UTF-16"; <br>PRAGMA encoding = "UTF-16le"; <br>PRAGMA encoding = "UTF-16be";</b></p> <p>In first form, if the main database has already been created, then this pragma returns the text encoding used by the main database, one of "UTF-8", "UTF-16le" (little-endian UTF-16 encoding) or "UTF-16be" (big-endian UTF-16 encoding). If the main database has not already been created, then the value returned is the text encoding that will be used to create the main database, if it is created by this session.</p> <p>The second and subsequent forms of this pragma are only useful if the main database has not already been created. In this case the pragma sets the encoding that the main database will be created with if it is created by this session. The string "UTF-16" is interpreted as "UTF-16 encoding using native machine byte-ordering". If the second and subsequent forms are used after the database file has already been created, they have no effect and are silently ignored.</p> <p>Once an encoding has been set for a database, it cannot be changed.</p> <p>Databases created by the ATTACH command always use the same encoding as the main database.</p> </li> <a name="pragma_full_column_names"></a> <li><p><b>PRAGMA full_column_names; <br>PRAGMA full_column_names = </b><i>0 | 1</i><b>;</b></p> <p>Query or change the full-column-names flag. This flag affects the way SQLite names columns of data returned by SELECT statements when the expression for the column is a table-column name or the wildcard "*". Normally, such result columns are named <table-name/alias><column-name> if the SELECT statement joins two or more tables together, or simply <column-name> if the SELECT statement queries a single table. When the full-column-names flag is set, such columns are always named <table-name/alias> <column-name> regardless of whether or not a join is performed. </p> <p>If both the short-column-names and full-column-names are set, then the behaviour associated with the full-column-names flag is exhibited. </p> </li> <a name="pragma_fullfsync"></a> <li><p><b>PRAGMA fullfsync <br>PRAGMA fullfsync = </b><i>0 | 1</i><b>;</b></p> <p>Query or change the fullfsync flag. This flag affects determines whether or not the F_FULLFSYNC syncing method is used on systems that support it. The default value is off. As of this writing (2006-02-10) only Mac OS X supports F_FULLFSYNC. </p> </li> <a name="pragma_incremental_vacuum"></a> <li><p><b>PRAGMA incremental_vacuum</b><i>(N)</i><b>;</b></p> <p>The incremental_vacuum pragma causes up to <i>N</i> pages to be removed from the freelist. The database file is truncated by the same amount. The incremental_vacuum pragma has no effect if the database is not in <a href="#pragma_auto_vacuum">auto_vacuum==incremental</a> mode or if there are no pages on the freelist. If there are fewer than <i>N</i> pages on the freelist, then the entire freelist is cleared.</p> <p>As of version 3.4.0 (the first version that supports incremental_vacuum) this feature is still experimental. Possible future changes include enhancing incremental vacuum to do defragmentation and node repacking just as the full-blown <a href="lang_vacuum.html">VACUUM</a> command does. And incremental vacuum may be promoted from a pragma to a separate SQL command, or perhaps some variation on the VACUUM command. Programmers are cautioned to not become enamored with the current syntax or functionality as it is likely to change.</p> </li> <a name="pragma_legacy_file_format"></a> <li><p><b>PRAGMA legacy_file_format; <br>PRAGMA legacy_file_format = <i>ON | OFF</i></b></p> <p>This pragma sets or queries the value of the legacy_file_format flag. When this flag is on, new SQLite databases are created in a file format that is readable and writable by all versions of SQLite going back to 3.0.0. When the flag is off, new databases are created using the latest file format which might not be readable or writable by older versions of SQLite.</p> <p>This flag only affects newly created databases. It has no effect on databases that already exist.</p> </li> <a name="pragma_locking_mode"></a> <li><p><b>PRAGMA locking_mode; <br>PRAGMA locking_mode = <i>NORMAL | EXCLUSIVE</i></b></p> <p>This pragma sets or queries the database connection locking-mode. The locking-mode is either NORMAL or EXCLUSIVE. <p>In NORMAL locking-mode (the default), a database connection unlocks the database file at the conclusion of each read or write transaction. When the locking-mode is set to EXCLUSIVE, the database connection never releases file-locks. The first time the database is read in EXCLUSIVE mode, a shared lock is obtained and held. The first time the database is written, an exclusive lock is obtained and held.</p> <p>Database locks obtained by a connection in EXCLUSIVE mode may be released either by closing the database connection, or by setting the locking-mode back to NORMAL using this pragma and then accessing the database file (for read or write). Simply setting the locking-mode to NORMAL is not enough - locks are not be released until the next time the database file is accessed.</p> <p>There are two reasons to set the locking-mode to EXCLUSIVE. One is if the application actually wants to prevent other processes from accessing the database file. The other is that a small number of filesystem operations are saved by optimizations enabled in this mode. This may be significant in embedded environments.</p> <p>When the locking_mode pragma specifies a particular database, for example:</p> <blockquote> PRAGMA <b>main.</b>locking_mode=EXCLUSIVE; </blockquote> <p>Then the locking mode applies only to the named database. If no database name qualifier preceeds the "locking_mode" keyword then the locking mode is applied to all databases, including any new databases added by subsequent <a href="lang_attach.html">ATTACH</a> commands.</p> <p>The "temp" database (in which TEMP tables and indices are stored) always uses exclusive locking mode. The locking mode of temp cannot be changed. All other databases use the normal locking mode by default and are affected by this pragma.</p> </li> <a name="pragma_page_size"></a> <li><p><b>PRAGMA page_size; <br>PRAGMA page_size = </b><i>bytes</i><b>;</b></p> <p>Query or set the page-size of the database. The page-size may only be set if the database has not yet been created. The page size must be a power of two greater than or equal to 512 and less than or equal to 8192. The upper limit may be modified by setting the value of macro SQLITE_MAX_PAGE_SIZE during compilation. The maximum upper bound is 32768. </p> </li> <a name="pragma_max_page_count"></a> <li><p><b>PRAGMA max_page_count; <br>PRAGMA max_page_count = </b><i>N</i><b>;</b></p> <p>Query or set the maximum number of pages in the database file. Both forms of the pragma return the maximum page count. The second form attempts to modify the maximum page count. The maximum page count cannot be reduced below the current database size. </p> </li> <a name="pragma_read_uncommitted"></a> <li><p><b>PRAGMA read_uncommitted; <br>PRAGMA read_uncommitted = </b><i>0 | 1</i><b>;</b></p> <p>Query, set, or clear READ UNCOMMITTED isolation. The default isolation level for SQLite is SERIALIZABLE. Any process or thread can select READ UNCOMMITTED isolation, but SERIALIZABLE will still be used except between connections that share a common page and schema cache. Cache sharing is enabled using the <a href="capi3ref.html#sqlite3_enable_shared_cache"> sqlite3_enable_shared_cache()</a> API and is only available between connections running the same thread. Cache sharing is off by default. </p> </li> <a name="pragma_short_column_names"></a> <li><p><b>PRAGMA short_column_names; <br>PRAGMA short_column_names = </b><i>0 | 1</i><b>;</b></p> <p>Query or change the short-column-names flag. This flag affects the way SQLite names columns of data returned by SELECT statements when the expression for the column is a table-column name or the wildcard "*". Normally, such result columns are named <table-name/alias>lt;column-name> if the SELECT statement joins two or more tables together, or simply <column-name> if the SELECT statement queries a single table. When the short-column-names flag is set, such columns are always named <column-name> regardless of whether or not a join is performed. </p> <p>If both the short-column-names and full-column-names are set, then the behaviour associated with the full-column-names flag is exhibited. </p> </li> <a name="pragma_synchronous"></a> <li><p><b>PRAGMA synchronous; <br>PRAGMA synchronous = FULL; </b>(2)<b> <br>PRAGMA synchronous = NORMAL; </b>(1)<b> <br>PRAGMA synchronous = OFF; </b>(0)</p> <p>Query or change the setting of the "synchronous" flag. The first (query) form will return the setting as an integer. When synchronous is FULL (2), the SQLite database engine will pause at critical moments to make sure that data has actually been written to the disk surface before continuing. This ensures that if the operating system crashes or if there is a power failure, the database will be uncorrupted after rebooting. FULL synchronous is very safe, but it is also slow. When synchronous is NORMAL, the SQLite database engine will still pause at the most critical moments, but less often than in FULL mode. There is a very small (though non-zero) chance that a power failure at just the wrong time could corrupt the database in NORMAL mode. But in practice, you are more likely to suffer a catastrophic disk failure or some other unrecoverable hardware fault. With synchronous OFF (0), SQLite continues without pausing as soon as it has handed data off to the operating system. If the application running SQLite crashes, the data will be safe, but the database might become corrupted if the operating system crashes or the computer loses power before that data has been written to the disk surface. On the other hand, some operations are as much as 50 or more times faster with synchronous OFF. </p> <p>In SQLite version 2, the default value is NORMAL. For version 3, the default was changed to FULL. </p> </li> <a name="pragma_temp_store"></a> <li><p><b>PRAGMA temp_store; <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 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 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> <p>It is possible for the library compile-time C preprocessor symbol TEMP_STORE to override this pragma setting. The following table summarizes the interaction of the TEMP_STORE preprocessor macro and the temp_store pragma:</p> <blockquote> <table cellpadding="2" border="1"> <tr><th valign="bottom">TEMP_STORE</th> <th valign="bottom">PRAGMA<br>temp_store</th> <th>Storage used for<br>TEMP tables and indices</th></tr> <tr><td align="center">0</td> <td align="center"><em>any</em></td> <td align="center">file</td></tr> <tr><td align="center">1</td> <td align="center">0</td> <td align="center">file</td></tr> <tr><td align="center">1</td> <td align="center">1</td> <td align="center">file</td></tr> <tr><td align="center">1</td> <td align="center">2</td> <td align="center">memory</td></tr> <tr><td align="center">2</td> <td align="center">0</td> <td align="center">memory</td></tr> <tr><td align="center">2</td> <td align="center">1</td> <td align="center">file</td></tr> <tr><td align="center">2</td> <td align="center">2</td> <td align="center">memory</td></tr> <tr><td align="center">3</td> <td align="center"><em>any</em></td> <td align="center">memory</td></tr> </table> </blockquote> </li> <br> <a name="pragma_temp_store_directory"></a> <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/OSX, 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 NT, the default directory is determined by Windows, 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 normally visible through <i>ls</i> or <i>dir</i> commands.</p> </li> </ul> <tcl>Section {Pragmas to query the database schema} schema</tcl> <ul> <a name="pragma_database_list"></a> <li><p><b>PRAGMA database_list;</b></p> <p>For each open database, invoke the callback function once with information about that database. Arguments include the index and the name the database was attached with. The first row will be for the main database. The second row will be for the database used to store temporary tables.</p></li> <a name="pragma_foreign_key_list"></a> <li><p><b>PRAGMA foreign_key_list(</b><i>table-name</i><b>);</b></p> <p>For each foreign key that references a column in the argument table, invoke the callback function with information about that foreign key. The callback function will be invoked once for each column in each foreign key.</p></li> <a name="pragma_freelist_count"></a> <li><p><b>PRAGMA [database].freelist_count;</b></p> <p>Return the number of unused pages in the database file. Running a <a href="#pragma_incremental_vacuum">"PRAGMA incremental_vaccum(N);"</a> command with a large value of N will shrink the database file by this number of pages. </p></li> <a name="pragma_index_info"></a> <li><p><b>PRAGMA index_info(</b><i>index-name</i><b>);</b></p> <p>For each column that the named index references, invoke the callback function once with information about that column, including the column name, and the column number.</p></li> <a name="pragma_index_list"></a> <li><p><b>PRAGMA index_list(</b><i>table-name</i><b>);</b></p> <p>For each index on the named table, invoke the callback function once with information about that index. Arguments include the index name and a flag to indicate whether or not the index must be unique.</p></li> <a name="pragma_table_info"></a> <li><p><b>PRAGMA table_info(</b><i>table-name</i><b>);</b></p> <p>For each column in the named table, invoke the callback function once with information about that column, including the column name, data type, whether or not the column can be NULL, and the default value for the column.</p></li> </ul> <tcl>Section {Pragmas to query/modify version values} version</tcl> <ul> <a name="pragma_schema_version"></a> <a name="pragma_user_version"></a> <li><p><b>PRAGMA [database.]schema_version; <br>PRAGMA [database.]schema_version = </b><i>integer </i><b>; <br>PRAGMA [database.]user_version; <br>PRAGMA [database.]user_version = </b><i>integer </i><b>;</b> <p> The pragmas schema_version and user_version are used to set or get the value of the schema-version and user-version, respectively. Both the schema-version and the user-version are 32-bit signed integers stored in the database header.</p> <p> The schema-version is usually only manipulated internally by SQLite. It is incremented by SQLite whenever the database schema is modified (by creating or dropping a table or index). The schema version is used by SQLite each time a query is executed to ensure that the internal cache of the schema used when compiling the SQL query matches the schema of the database against which the compiled query is actually executed. Subverting this mechanism by using "PRAGMA schema_version" to modify the schema-version is potentially dangerous and may lead to program crashes or database corruption. Use with caution!</p> <p> The user-version is not used internally by SQLite. It may be used by applications for any purpose.</p> </li> </ul> <tcl>Section {Pragmas to debug the library} debug</tcl> <ul> <a name="pragma_integrity_check"></a> <li><p><b>PRAGMA integrity_check; <br>PRAGMA integrity_check(</b><i>integer</i><b>)</b></p> <p>The command does an integrity check of the entire database. It looks for out-of-order records, missing pages, malformed records, and corrupt indices. If any problems are found, then strings are returned (as multiple rows with a single column per row) which describe the problems. At most <i>integer</i> errors will be reported before the analysis quits. The default value for <i>integer</i> is 100. If no errors are found, a single row with the value "ok" is returned.</p></li> <a name="pragma_parser_trace"></a> <li><p><b>PRAGMA parser_trace = ON; </b>(1)<b> <br>PRAGMA parser_trace = OFF;</b> (0)</p> <p>Turn tracing of the SQL parser inside of the SQLite library on and off. This is used for debugging. This only works if the library is compiled without the NDEBUG macro. </p></li> <a name="pragma_vdbe_trace"></a> <li><p><b>PRAGMA vdbe_trace = ON; </b>(1)<b> <br>PRAGMA vdbe_trace = OFF;</b> (0)</p> <p>Turn tracing of the virtual database engine inside of the SQLite library on and off. This is used for debugging. See the <a href="vdbe.html#trace">VDBE documentation</a> for more information.</p></li> <a name="pragma_vdbe_listing"></a> <li><p><b>PRAGMA vdbe_listing = ON; </b>(1)<b> <br>PRAGMA vdbe_listing = OFF;</b> (0)</p> <p>Turn listings of virtual machine programs on and off. With listing is on, the entire content of a program is printed just prior to beginning execution. This is like automatically executing an EXPLAIN prior to each statement. The statement executes normally after the listing is printed. This is used for debugging. See the <a href="vdbe.html#trace">VDBE documentation</a> for more information.</p></li> </ul> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 | <title>SQLite In 5 Minutes Or Less</title> <p>Here is what you do to start experimenting with SQLite without having to do a lot of tedious reading and configuration:</p> <h2>Download The Code</h2> <ul> <li><p>Get a copy of the prebuilt binaries for your machine, or get a copy of the sources and compile them yourself. Visit the <a href="download.html">download</a> page for more information.</p></li> </ul> <h2>Create A New Database</h2> <ul> <li><p>At a shell or DOS prompt, enter: "<b>sqlite3 test.db</b>". This will create a new database named "test.db". (You can use a different name if you like.)</p></li> <li><p>Enter SQL commands at the prompt to create and populate the new database.</p></li> <li><p>Additional documentation is available <a href="sqlite.html">here</a></li> </ul> <h2>Write Programs That Use SQLite</h2> <ul> <li><p>Below is a simple 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 TCL command named "<b>db</b>" to access that database, the invocation of the <b>db</b> command on line 8 to execute SQL commands against the database, and the closing of the database connection on the last line of the script.</p> <blockquote><pre> #!/usr/bin/tclsh if {$argc!=2} { puts stderr "Usage: %s DATABASE SQL-STATEMENT" exit 1 } load /usr/lib/tclsqlite3.so Sqlite3 <b>sqlite3</b> db [lindex $argv 0] <b>db</b> eval [lindex $argv 1] x { foreach v $x(*) { puts "$v = $x($v)" } puts "" } <b>db</b> close </pre></blockquote> </li> <li><p>Below is a simple C program that demonstrates how to use the C/C++ interface to SQLite. The name of a database is given by the first argument and the second argument is one or more SQL statements to execute against the database. The function calls to pay attention to here are the call to <b>sqlite3_open()</b> on line 22 which opens the database, <b>sqlite3_exec()</b> on line 27 that executes SQL commands against the database, and <b>sqlite3_close()</b> on line 31 that closes the database connection.</p> <blockquote><pre> #include <stdio.h> #include <sqlite3.h> static int callback(void *NotUsed, int argc, char **argv, char **azColName){ int i; for(i=0; i<argc; i++){ printf("%s = %s\n", azColName[i], argv[i] ? argv[i] : "NULL"); } printf("\n"); return 0; } int main(int argc, char **argv){ sqlite3 *db; char *zErrMsg = 0; int rc; if( argc!=3 ){ fprintf(stderr, "Usage: %s DATABASE SQL-STATEMENT\n", argv[0]); exit(1); } rc = <b>sqlite3_open</b>(argv[1], &db); if( rc ){ fprintf(stderr, "Can't open database: %s\n", sqlite3_errmsg(db)); sqlite3_close(db); exit(1); } rc = <b>sqlite3_exec</b>(db, argv[2], callback, 0, &zErrMsg); if( rc!=SQLITE_OK ){ fprintf(stderr, "SQL error: %s\n", zErrMsg); sqlite3_free(zErrMsg); } <b>sqlite3_close</b>(db); return 0; } </pre></blockquote> </li> </ul> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | <title>SQLite Shared-Cache Mode</title> <tcl> proc HEADING {level title} { global pnum incr pnum($level) foreach i [array names pnum] { if {$i>$level} {set pnum($i) 0} } set h [expr {$level+1}] if {$h>6} {set h 6} set n $pnum(1).$pnum(2) for {set i 3} {$i<=$level} {incr i} { append n .$pnum($i) } puts "<h$h>$n $title</h$h>" } set pnum(1) 0 set pnum(2) 0 set pnum(3) 0 set pnum(4) 0 set pnum(5) 0 set pnum(6) 0 set pnum(7) 0 set pnum(8) 0 </tcl> <tcl>HEADING 1 {SQLite Shared-Cache Mode}</tcl> <p>Starting with version 3.3.0, SQLite includes a special "shared-cache" mode (disabled by default) intended for use in embedded servers. If shared-cache mode is enabled and a thread establishes multiple connections to the same database, the connections share a single data and schema cache. This can significantly reduce the quantity of memory and IO required by the system.</p> <p>Using shared-cache mode imposes some extra restrictions on passing database handles between threads and changes the semantics of the locking model in some cases. These details are described in full by this document. A basic understanding of the normal SQLite locking model (see <a href="lockingv3.html">File Locking And Concurrency In SQLite Version 3</a> for details) is assumed.</p> <tcl>HEADING 1 {Shared-Cache Locking Model}</tcl> <p>Externally, from the point of view of another process or thread, two or more database connections using a shared-cache appear as a single connection. The locking protocol used to arbitrate between multiple shared-caches or regular database users is described elsewhere. </p> <table style="margin:auto"> <tr><td> <img src="shared.gif"> <!-- <pre> +--------------+ +--------------+ | Connection 2 | | Connection 3 | +--------------+ +--------------+ | | V V +--------------+ +--------------+ | Connection 1 | | Shared cache | +--------------+ +--------------+ | | V V +----------------+ | Database | +----------------+ </pre> --> </table> <p style="font-style:italic;text-align:center">Figure 1</p> <p>Figure 1 depicts an example runtime configuration where three database connections have been established. Connection 1 is a normal SQLite database connection. Connections 2 and 3 share a cache (and so must have been established by the same process thread). The normal locking protocol is used to serialize database access between connection 1 and the shared cache. The internal protocol used to serialize (or not, see "Read-Uncommitted Isolation Mode" below) access to the shared-cache by connections 2 and 3 is described in the remainder of this section. </p> <p>There are three levels to the shared-cache locking model, transaction level locking, table level locking and schema level locking. They are described in the following three sub-sections.</p> <tcl>HEADING 2 {Transaction Level Locking}</tcl> <p>SQLite connections can open two kinds of transactions, read and write transactions. This is not done explicitly, a transaction is implicitly a read-transaction until it first writes to a database table, at which point it becomes a write-transaction. </p> <p>At most one connection to a single shared cache may open a write transaction at any one time. This may co-exist with any number of read transactions. </p> <tcl>HEADING 2 {Table Level Locking}</tcl> <p>When two or more connections use a shared-cache, locks are used to serialize concurrent access attempts on a per-table basis. Tables support two types of locks, "read-locks" and "write-locks". Locks are granted to connections - at any one time, each database connection has either a read-lock, write-lock or no lock on each database table. </p> <p>At any one time, a single table may have any number of active read-locks or a single active write lock. To read data a table, a connection must first obtain a read-lock. To write to a table, a connection must obtain a write-lock on that table. If a required table lock cannot be obtained, the query fails and SQLITE_LOCKED is returned to the caller. </p> <p>Once a connection obtains a table lock, it is not released until the current transaction (read or write) is concluded. </p> <tcl>HEADING 3 {Read-Uncommitted Isolation Mode}</tcl> <p>The behaviour described above may be modified slightly by using the <i>read_uncommitted</i> pragma to change the isolation level from serialized (the default), to read-uncommitted.</p> <p> A database connection in read-uncommitted mode does not attempt to obtain read-locks before reading from database tables as described above. This can lead to inconsistent query results if another database connection modifies a table while it is being read, but it also means that a read-transaction opened by a connection in read-uncommitted mode can neither block nor be blocked by any other connection.</p> <p>Read-uncommitted mode has no effect on the locks required to write to database tables (i.e. read-uncommitted connections must still obtain write-locks and hence database writes may still block or be blocked). Also, read-uncommitted mode has no effect on the <i>sqlite_master</i> locks required by the rules enumerated below (see section "Schema (sqlite_master) Level Locking"). </p> <pre> /* Set the value of the read-uncommitted flag: ** ** True -> Set the connection to read-uncommitted mode. ** False -> Set the connectino to serialized (the default) mode. */ PRAGMA read_uncommitted = <boolean>; /* Retrieve the current value of the read-uncommitted flag */ PRAGMA read_uncommitted; </pre> <tcl>HEADING 2 {Schema (sqlite_master) Level Locking}</tcl> <p>The <i>sqlite_master</i> table supports shared-cache read and write locks in the same way as all other database tables (see description above). The following special rules also apply: </p> <ul> <li>A connection must obtain a read-lock on <i>sqlite_master</i> before accessing any database tables or obtaining any other read or write locks.</li> <li>Before executing a statement that modifies the database schema (i.e. a CREATE or DROP TABLE statement), a connection must obtain a write-lock on <i>sqlite_master</i>. </li> <li>A connection may not compile an SQL statement if any other connection is holding a write-lock on the <i>sqlite_master</i> table of any attached database (including the default database, "main"). </li> </ul> <tcl>HEADING 1 {Thread Related Issues}</tcl> <p>When shared-cache mode is enabled, a database connection may only be used by the thread that called sqlite3_open() to create it. If another thread attempts to use the database connection, in most cases an SQLITE_MISUSE error is returned. However this is not guaranteed and programs should not depend on this behaviour, in some cases a segfault may result. </p> <tcl>HEADING 1 {Enabling Shared-Cache Mode}</tcl> <p>Shared-cache mode is enabled on a thread-wide basis. Using the C interface, the following API can be used to enable or disable shared-cache mode for the calling thread: </p> <pre> int sqlite3_enable_shared_cache(int); </pre> <p>It is illegal to call sqlite3_enable_shared_cache() if one or more open database connections were opened by the calling thread. If the argument is non-zero, shared-cache mode is enabled. If the argument is zero, shared-cache mode is disabled. The return value is either SQLITE_OK (if the operation was successful), SQLITE_NOMEM (if a malloc() failed), or SQLITE_MISUSE (if the thread has open database connections). </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 | <title>SQLite Database Speed Comparison</title> <h2>Database Speed Comparison</h2> <font color="red"><b> Note: This document is old. It describes a speed comparison between an older version of SQLite against archaic versions of MySQL and PostgreSQL. Readers are invited to contribute more up-to-date speed comparisons on the <a href="http://www.sqlite.org/cvstrac/wiki">SQLite Wiki</a>. <p> The numbers here are old enough to be nearly meaningless. Until it is updated, use this document only as proof that SQLite is not a sluggard. </b></font> <h3>Executive Summary</h3> <p>A series of tests were run to measure the relative performance of SQLite 2.7.6, PostgreSQL 7.1.3, and MySQL 3.23.41. The following are general conclusions drawn from these experiments: </p> <ul> <li><p> SQLite 2.7.6 is significantly faster (sometimes as much as 10 or 20 times faster) than the default PostgreSQL 7.1.3 installation on RedHat 7.2 for most common operations. </p></li> <li><p> SQLite 2.7.6 is often faster (sometimes more than twice as fast) than MySQL 3.23.41 for most common operations. </p></li> <li><p> SQLite does not execute CREATE INDEX or DROP TABLE as fast as the other databases. But this is not seen as a problem because those are infrequent operations. </p></li> <li><p> SQLite works best if you group multiple operations together into a single transaction. </p></li> </ul> <p> The results presented here come with the following caveats: </p> <ul> <li><p> These tests did not attempt to measure multi-user performance or optimization of complex queries involving multiple joins and subqueries. </p></li> <li><p> These tests are on a relatively small (approximately 14 megabyte) database. They do not measure how well the database engines scale to larger problems. </p></li> </ul> <h3>Test Environment</h3> <p> The platform used for these tests is a 1.6GHz Athlon with 1GB or memory and an IDE disk drive. The operating system is RedHat Linux 7.2 with a stock kernel. </p> <p> The PostgreSQL and MySQL servers used were as delivered by default on RedHat 7.2. (PostgreSQL version 7.1.3 and MySQL version 3.23.41.) No effort was made to tune these engines. Note in particular the the default MySQL configuration on RedHat 7.2 does not support transactions. Not having to support transactions gives MySQL a big speed advantage, but SQLite is still able to hold its own on most tests. </p> <p> I am told that the default PostgreSQL configuration in RedHat 7.3 is unnecessarily conservative (it is designed to work on a machine with 8MB of RAM) and that PostgreSQL could be made to run a lot faster with some knowledgeable configuration tuning. Matt Sergeant reports that he has tuned his PostgreSQL installation and rerun the tests shown below. His results show that PostgreSQL and MySQL run at about the same speed. For Matt's results, visit </p> <blockquote> <a href="http://www.sergeant.org/sqlite_vs_pgsync.html"> http://www.sergeant.org/sqlite_vs_pgsync.html</a> </blockquote> <p> SQLite was tested in the same configuration that it appears on the website. It was compiled with -O6 optimization and with the -DNDEBUG=1 switch which disables the many "assert()" statements in the SQLite code. The -DNDEBUG=1 compiler option roughly doubles the speed of SQLite. </p> <p> All tests are conducted on an otherwise quiescent machine. A simple Tcl script was used to generate and run all the tests. A copy of this Tcl script can be found in the SQLite source tree in the file <b>tools/speedtest.tcl</b>. </p> <p> The times reported on all tests represent wall-clock time in seconds. Two separate time values are reported for SQLite. The first value is for SQLite in its default configuration with full disk synchronization turned on. With synchronization turned on, SQLite executes an <b>fsync()</b> system call (or the equivalent) at key points to make certain that critical data has actually been written to the disk drive surface. Synchronization is necessary to guarantee the integrity of the database if the operating system crashes or the computer powers down unexpectedly in the middle of a database update. The second time reported for SQLite is when synchronization is turned off. With synchronization off, SQLite is sometimes much faster, but there is a risk that an operating system crash or an unexpected power failure could damage the database. Generally speaking, the synchronous SQLite times are for comparison against PostgreSQL (which is also synchronous) and the asynchronous SQLite times are for comparison against the asynchronous MySQL engine. </p> <h3>Test 1: 1000 INSERTs</h3> <blockquote> CREATE TABLE t1(a INTEGER, b INTEGER, c VARCHAR(100));<br> INSERT INTO t1 VALUES(1,13153,'thirteen thousand one hundred fifty three');<br> INSERT INTO t1 VALUES(2,75560,'seventy five thousand five hundred sixty');<br> <i>... 995 lines omitted</i><br> INSERT INTO t1 VALUES(998,66289,'sixty six thousand two hundred eighty nine');<br> INSERT INTO t1 VALUES(999,24322,'twenty four thousand three hundred twenty two');<br> INSERT INTO t1 VALUES(1000,94142,'ninety four thousand one hundred forty two');<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 4.373</td></tr> <tr><td>MySQL:</td><td align="right"> 0.114</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 13.061</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.223</td></tr> </table> <p> Because it does not have a central server to coordinate access, SQLite must close and reopen the database file, and thus invalidate its cache, for each transaction. In this test, each SQL statement is a separate transaction so the database file must be opened and closed and the cache must be flushed 1000 times. In spite of this, the asynchronous version of SQLite is still nearly as fast as MySQL. Notice how much slower the synchronous version is, however. SQLite calls <b>fsync()</b> after each synchronous transaction to make sure that all data is safely on the disk surface before continuing. For most of the 13 seconds in the synchronous test, SQLite was sitting idle waiting on disk I/O to complete.</p> <h3>Test 2: 25000 INSERTs in a transaction</h3> <blockquote> BEGIN;<br> CREATE TABLE t2(a INTEGER, b INTEGER, c VARCHAR(100));<br> INSERT INTO t2 VALUES(1,59672,'fifty nine thousand six hundred seventy two');<br> <i>... 24997 lines omitted</i><br> INSERT INTO t2 VALUES(24999,89569,'eighty nine thousand five hundred sixty nine');<br> INSERT INTO t2 VALUES(25000,94666,'ninety four thousand six hundred sixty six');<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 4.900</td></tr> <tr><td>MySQL:</td><td align="right"> 2.184</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 0.914</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.757</td></tr> </table> <p> When all the INSERTs are put in a transaction, SQLite no longer has to close and reopen the database or invalidate its cache between each statement. It also does not have to do any fsync()s until the very end. When unshackled in this way, SQLite is much faster than either PostgreSQL and MySQL. </p> <h3>Test 3: 25000 INSERTs into an indexed table</h3> <blockquote> BEGIN;<br> CREATE TABLE t3(a INTEGER, b INTEGER, c VARCHAR(100));<br> CREATE INDEX i3 ON t3(c);<br> <i>... 24998 lines omitted</i><br> INSERT INTO t3 VALUES(24999,88509,'eighty eight thousand five hundred nine');<br> INSERT INTO t3 VALUES(25000,84791,'eighty four thousand seven hundred ninety one');<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 8.175</td></tr> <tr><td>MySQL:</td><td align="right"> 3.197</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 1.555</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.402</td></tr> </table> <p> There were reports that SQLite did not perform as well on an indexed table. This test was recently added to disprove those rumors. It is true that SQLite is not as fast at creating new index entries as the other engines (see Test 6 below) but its overall speed is still better. </p> <h3>Test 4: 100 SELECTs without an index</h3> <blockquote> BEGIN;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<1000;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<1100;<br> <i>... 96 lines omitted</i><br> SELECT count(*), avg(b) FROM t2 WHERE b>=9800 AND b<10800;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=9900 AND b<10900;<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 3.629</td></tr> <tr><td>MySQL:</td><td align="right"> 2.760</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 2.494</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 2.526</td></tr> </table> <p> This test does 100 queries on a 25000 entry table without an index, thus requiring a full table scan. Prior versions of SQLite used to be slower than PostgreSQL and MySQL on this test, but recent performance enhancements have increased its speed so that it is now the fastest of the group. </p> <h3>Test 5: 100 SELECTs on a string comparison</h3> <blockquote> BEGIN;<br> SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one%';<br> SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%two%';<br> <i>... 96 lines omitted</i><br> SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%ninety nine%';<br> SELECT count(*), avg(b) FROM t2 WHERE c LIKE '%one hundred%';<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 13.409</td></tr> <tr><td>MySQL:</td><td align="right"> 4.640</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 3.362</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.372</td></tr> </table> <p> This test still does 100 full table scans but it uses uses string comparisons instead of numerical comparisons. SQLite is over three times faster than PostgreSQL here and about 30% faster than MySQL. </p> <h3>Test 6: Creating an index</h3> <blockquote> CREATE INDEX i2a ON t2(a);<br>CREATE INDEX i2b ON t2(b); </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 0.381</td></tr> <tr><td>MySQL:</td><td align="right"> 0.318</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 0.777</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.659</td></tr> </table> <p> SQLite is slower at creating new indices. This is not a huge problem (since new indices are not created very often) but it is something that is being worked on. Hopefully, future versions of SQLite will do better here. </p> <h3>Test 7: 5000 SELECTs with an index</h3> <blockquote> SELECT count(*), avg(b) FROM t2 WHERE b>=0 AND b<100;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=100 AND b<200;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=200 AND b<300;<br> <i>... 4994 lines omitted</i><br> SELECT count(*), avg(b) FROM t2 WHERE b>=499700 AND b<499800;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=499800 AND b<499900;<br> SELECT count(*), avg(b) FROM t2 WHERE b>=499900 AND b<500000;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 4.614</td></tr> <tr><td>MySQL:</td><td align="right"> 1.270</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 1.121</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.162</td></tr> </table> <p> All three database engines run faster when they have indices to work with. But SQLite is still the fastest. </p> <h3>Test 8: 1000 UPDATEs without an index</h3> <blockquote> BEGIN;<br> UPDATE t1 SET b=b*2 WHERE a>=0 AND a<10;<br> UPDATE t1 SET b=b*2 WHERE a>=10 AND a<20;<br> <i>... 996 lines omitted</i><br> UPDATE t1 SET b=b*2 WHERE a>=9980 AND a<9990;<br> UPDATE t1 SET b=b*2 WHERE a>=9990 AND a<10000;<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 1.739</td></tr> <tr><td>MySQL:</td><td align="right"> 8.410</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 0.637</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.638</td></tr> </table> <p> For this particular UPDATE test, MySQL is consistently five or ten times slower than PostgreSQL and SQLite. I do not know why. MySQL is normally a very fast engine. Perhaps this problem has been addressed in later versions of MySQL. </p> <h3>Test 9: 25000 UPDATEs with an index</h3> <blockquote> BEGIN;<br> UPDATE t2 SET b=468026 WHERE a=1;<br> UPDATE t2 SET b=121928 WHERE a=2;<br> <i>... 24996 lines omitted</i><br> UPDATE t2 SET b=35065 WHERE a=24999;<br> UPDATE t2 SET b=347393 WHERE a=25000;<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 18.797</td></tr> <tr><td>MySQL:</td><td align="right"> 8.134</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 3.520</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 3.104</td></tr> </table> <p> As recently as version 2.7.0, SQLite ran at about the same speed as MySQL on this test. But recent optimizations to SQLite have more than doubled speed of UPDATEs. </p> <h3>Test 10: 25000 text UPDATEs with an index</h3> <blockquote> BEGIN;<br> UPDATE t2 SET c='one hundred forty eight thousand three hundred eighty two' WHERE a=1;<br> UPDATE t2 SET c='three hundred sixty six thousand five hundred two' WHERE a=2;<br> <i>... 24996 lines omitted</i><br> UPDATE t2 SET c='three hundred eighty three thousand ninety nine' WHERE a=24999;<br> UPDATE t2 SET c='two hundred fifty six thousand eight hundred thirty' WHERE a=25000;<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 48.133</td></tr> <tr><td>MySQL:</td><td align="right"> 6.982</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 2.408</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.725</td></tr> </table> <p> Here again, version 2.7.0 of SQLite used to run at about the same speed as MySQL. But now version 2.7.6 is over two times faster than MySQL and over twenty times faster than PostgreSQL. </p> <p> In fairness to PostgreSQL, it started thrashing on this test. A knowledgeable administrator might be able to get PostgreSQL to run a lot faster here by tweaking and tuning the server a little. </p> <h3>Test 11: INSERTs from a SELECT</h3> <blockquote> BEGIN;<br>INSERT INTO t1 SELECT b,a,c FROM t2;<br>INSERT INTO t2 SELECT b,a,c FROM t1;<br>COMMIT; </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 61.364</td></tr> <tr><td>MySQL:</td><td align="right"> 1.537</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 2.787</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.599</td></tr> </table> <p> The asynchronous SQLite is just a shade slower than MySQL on this test. (MySQL seems to be especially adept at INSERT...SELECT statements.) The PostgreSQL engine is still thrashing - most of the 61 seconds it used were spent waiting on disk I/O. </p> <h3>Test 12: DELETE without an index</h3> <blockquote> DELETE FROM t2 WHERE c LIKE '%fifty%'; </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 1.509</td></tr> <tr><td>MySQL:</td><td align="right"> 0.975</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 4.004</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.560</td></tr> </table> <p> The synchronous version of SQLite is the slowest of the group in this test, but the asynchronous version is the fastest. The difference is the extra time needed to execute fsync(). </p> <h3>Test 13: DELETE with an index</h3> <blockquote> DELETE FROM t2 WHERE a>10 AND a<20000; </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 1.316</td></tr> <tr><td>MySQL:</td><td align="right"> 2.262</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 2.068</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.752</td></tr> </table> <p> This test is significant because it is one of the few where PostgreSQL is faster than MySQL. The asynchronous SQLite is, however, faster then both the other two. </p> <h3>Test 14: A big INSERT after a big DELETE</h3> <blockquote> INSERT INTO t2 SELECT * FROM t1; </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 13.168</td></tr> <tr><td>MySQL:</td><td align="right"> 1.815</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 3.210</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 1.485</td></tr> </table> <p> Some older versions of SQLite (prior to version 2.4.0) would show decreasing performance after a sequence of DELETEs followed by new INSERTs. As this test shows, the problem has now been resolved. </p> <h3>Test 15: A big DELETE followed by many small INSERTs</h3> <blockquote> BEGIN;<br> DELETE FROM t1;<br> INSERT INTO t1 VALUES(1,10719,'ten thousand seven hundred nineteen');<br> <i>... 11997 lines omitted</i><br> INSERT INTO t1 VALUES(11999,72836,'seventy two thousand eight hundred thirty six');<br> INSERT INTO t1 VALUES(12000,64231,'sixty four thousand two hundred thirty one');<br> COMMIT;<br> </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 4.556</td></tr> <tr><td>MySQL:</td><td align="right"> 1.704</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 0.618</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.406</td></tr> </table> <p> SQLite is very good at doing INSERTs within a transaction, which probably explains why it is so much faster than the other databases at this test. </p> <h3>Test 16: DROP TABLE</h3> <blockquote> DROP TABLE t1;<br>DROP TABLE t2;<br>DROP TABLE t3; </blockquote><table border=0 cellpadding=0 cellspacing=0> <tr><td>PostgreSQL:</td><td align="right"> 0.135</td></tr> <tr><td>MySQL:</td><td align="right"> 0.015</td></tr> <tr><td>SQLite 2.7.6:</td><td align="right"> 0.939</td></tr> <tr><td>SQLite 2.7.6 (nosync):</td><td align="right"> 0.254</td></tr> </table> <p> SQLite is slower than the other databases when it comes to dropping tables. This probably is because when SQLite drops a table, it has to go through and erase the records in the database file that deal with that table. MySQL and PostgreSQL, on the other hand, use separate files to represent each table so they can drop a table simply by deleting a file, which is much faster. </p> <p> On the other hand, dropping tables is not a very common operation so if SQLite takes a little longer, that is not seen as a big problem. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 | <title>sqlite3: A command-line access program for SQLite databases</title> <h2>sqlite3: A command-line access program for SQLite databases</h2> <p>The SQLite library includes a simple command-line utility named <b>sqlite3</b> that allows the user to manually enter and execute SQL commands against an SQLite database. This document provides a brief introduction on how to use <b>sqlite3</b>. <h3>Getting Started</h3> <p>To start the <b>sqlite3</b> program, just type "sqlite3" followed by the name the file that holds the SQLite database. If the file does not exist, a new one is created automatically. The <b>sqlite3</b> program will then prompt you to enter SQL. Type in SQL statements (terminated by a semicolon), press "Enter" and the SQL will be executed.</p> <p>For example, to create a new SQLite database named "ex1" with a single table named "tbl1", you might do this:</p> <tcl> proc Code {body} { puts {<blockquote><tt>} regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body regsub -all {\(\(\(} $body {<b>} body regsub -all {\)\)\)} $body {</b>} body regsub -all { } $body {\ } body regsub -all \n $body <br>\n body puts $body puts {</tt></blockquote>} } Code { $ (((sqlite3 ex1))) SQLite version 3.3.10 Enter ".help" for instructions sqlite> (((create table tbl1(one varchar(10), two smallint);))) sqlite> (((insert into tbl1 values('hello!',10);))) sqlite> (((insert into tbl1 values('goodbye', 20);))) sqlite> (((select * from tbl1;))) hello!|10 goodbye|20 sqlite> } </tcl> <p>You can terminate the sqlite3 program by typing your systems End-Of-File character (usually a Control-D) or the interrupt character (usually a Control-C).</p> <p>Make sure you type a semicolon at the end of each SQL command! The sqlite3 program looks for a semicolon to know when your SQL command is complete. If you omit the semicolon, sqlite3 will give you a continuation prompt and wait for you to enter more text to be added to the current SQL command. This feature allows you to enter SQL commands that span multiple lines. For example:</p> <tcl>Code { sqlite> (((CREATE TABLE tbl2 ())) ...> ((( f1 varchar(30) primary key,))) ...> ((( f2 text,))) ...> ((( f3 real))) ...> ((();))) sqlite> }</tcl> <h3>Aside: Querying the SQLITE_MASTER table</h3> <p>The database schema in an SQLite database is stored in a special table named "sqlite_master". You can execute "SELECT" statements against the special sqlite_master table just like any other table in an SQLite database. For example:</p> <tcl>Code { $ (((sqlite3 ex1))) SQlite vresion 3.3.10 Enter ".help" for instructions sqlite> (((select * from sqlite_master;))) type = table name = tbl1 tbl_name = tbl1 rootpage = 3 sql = create table tbl1(one varchar(10), two smallint) sqlite> }</tcl> <p> But you cannot execute DROP TABLE, UPDATE, INSERT or DELETE against the sqlite_master table. The sqlite_master table is updated automatically as you create or drop tables and indices from the database. You can not make manual changes to the sqlite_master table. </p> <p> The schema for TEMPORARY tables is not stored in the "sqlite_master" table since TEMPORARY tables are not visible to applications other than the application that created the table. The schema for TEMPORARY tables is stored in another special table named "sqlite_temp_master". The "sqlite_temp_master" table is temporary itself. </p> <h3>Special commands to sqlite3</h3> <p> Most of the time, sqlite3 just reads lines of input and passes them on to the SQLite library for execution. But if an input line begins with a dot ("."), then that line is intercepted and interpreted by the sqlite3 program itself. These "dot commands" are typically used to change the output format of queries, or to execute certain prepackaged query statements. </p> <p> For a listing of the available dot commands, you can enter ".help" at any time. For example: </p> <tcl>Code { sqlite> (((.help))) .bail ON|OFF Stop after hitting an error. Default OFF .databases List names and files of attached databases .dump ?TABLE? ... Dump the database in an SQL text format .echo ON|OFF Turn command echo on or off .exit Exit this program .explain ON|OFF Turn output mode suitable for EXPLAIN on or off. .header(s) ON|OFF Turn display of headers on or off .help Show this message .import FILE TABLE Import data from FILE into TABLE .indices TABLE Show names of all indices on TABLE .load FILE ?ENTRY? Load an extension library .mode MODE ?TABLE? Set output mode where MODE is one of: csv Comma-separated values column Left-aligned columns. (See .width) html HTML <table> code insert SQL insert statements for TABLE line One value per line list Values delimited by .separator string tabs Tab-separated values tcl TCL list elements .nullvalue STRING Print STRING in place of NULL values .output FILENAME Send output to FILENAME .output stdout Send output to the screen .prompt MAIN CONTINUE Replace the standard prompts .quit Exit this program .read FILENAME Execute SQL in FILENAME .schema ?TABLE? Show the CREATE statements .separator STRING Change separator used by output mode and .import .show Show the current values for various settings .tables ?PATTERN? List names of tables matching a LIKE pattern .timeout MS Try opening locked tables for MS milliseconds .width NUM NUM ... Set column widths for "column" mode sqlite> }</tcl> <h3>Changing Output Formats</h3> <p>The sqlite3 program is able to show the results of a query in eight different formats: "csv", "column", "html", "insert", "line", "tabs", and "tcl". You can use the ".mode" dot command to switch between these output formats.</p> <p>The default output mode is "list". In list mode, each record of a query result is written on one line of output and each column within that record is separated by a specific separator string. The default separator is a pipe symbol ("|"). List mode is especially useful when you are going to send the output of a query to another program (such as AWK) for additional processing.</p> <tcl>Code { sqlite> (((.mode list))) sqlite> (((select * from tbl1;))) hello|10 goodbye|20 sqlite> }</tcl> <p>You can use the ".separator" dot command to change the separator for list mode. For example, to change the separator to a comma and a space, you could do this:</p> <tcl>Code { sqlite> (((.separator ", "))) sqlite> (((select * from tbl1;))) hello, 10 goodbye, 20 sqlite> }</tcl> <p>In "line" mode, each column in a row of the database is shown on a line by itself. Each line consists of the column name, an equal sign and the column data. Successive records are separated by a blank line. Here is an example of line mode output:</p> <tcl>Code { sqlite> (((.mode line))) sqlite> (((select * from tbl1;))) one = hello two = 10 one = goodbye two = 20 sqlite> }</tcl> <p>In column mode, each record is shown on a separate line with the data aligned in columns. For example:</p> <tcl>Code { sqlite> (((.mode column))) sqlite> (((select * from tbl1;))) one two ---------- ---------- hello 10 goodbye 20 sqlite> }</tcl> <p>By default, each column is at least 10 characters wide. Data that is too wide to fit in a column is truncated. You can adjust the column widths using the ".width" command. Like this:</p> <tcl>Code { sqlite> (((.width 12 6))) sqlite> (((select * from tbl1;))) one two ------------ ------ hello 10 goodbye 20 sqlite> }</tcl> <p>The ".width" command in the example above sets the width of the first column to 12 and the width of the second column to 6. All other column widths were unaltered. You can gives as many arguments to ".width" as necessary to specify the widths of as many columns as are in your query results.</p> <p>If you specify a column a width of 0, then the column width is automatically adjusted to be the maximum of three numbers: 10, the width of the header, and the width of the first row of data. This makes the column width self-adjusting. The default width setting for every column is this auto-adjusting 0 value.</p> <p>The column labels that appear on the first two lines of output can be turned on and off using the ".header" dot command. In the examples above, the column labels are on. To turn them off you could do this:</p> <tcl>Code { sqlite> (((.header off))) sqlite> (((select * from tbl1;))) hello 10 goodbye 20 sqlite> }</tcl> <p>Another useful output mode is "insert". In insert mode, the output is formatted to look like SQL INSERT statements. You can use insert mode to generate text that can later be used to input data into a different database.</p> <p>When specifying insert mode, you have to give an extra argument which is the name of the table to be inserted into. For example:</p> <tcl>Code { sqlite> (((.mode insert new_table))) sqlite> (((select * from tbl1;))) INSERT INTO 'new_table' VALUES('hello',10); INSERT INTO 'new_table' VALUES('goodbye',20); sqlite> }</tcl> <p>The last output mode is "html". In this mode, sqlite3 writes the results of the query as an XHTML table. The beginning <TABLE> and the ending </TABLE> are not written, but all of the intervening <TR>s, <TH>s, and <TD>s are. The html output mode is envisioned as being useful for CGI.</p> <h3>Writing results to a file</h3> <p>By default, sqlite3 sends query results to standard output. You can change this using the ".output" command. Just put the name of an output file as an argument to the .output command and all subsequent query results will be written to that file. Use ".output stdout" to begin writing to standard output again. For example:</p> <tcl>Code { sqlite> (((.mode list))) sqlite> (((.separator |))) sqlite> (((.output test_file_1.txt))) sqlite> (((select * from tbl1;))) sqlite> (((.exit))) $ (((cat test_file_1.txt))) hello|10 goodbye|20 $ }</tcl> <h3>Querying the database schema</h3> <p>The sqlite3 program provides several convenience commands that are useful for looking at the schema of the database. There is nothing that these commands do that cannot be done by some other means. These commands are provided purely as a shortcut.</p> <p>For example, to see a list of the tables in the database, you can enter ".tables".</p> <tcl>Code { sqlite> (((.tables))) tbl1 tbl2 sqlite> }</tcl> <p>The ".tables" command is similar to setting list mode then executing the following query:</p> <blockquote><pre> SELECT name FROM sqlite_master WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%' UNION ALL SELECT name FROM sqlite_temp_master WHERE type IN ('table','view') ORDER BY 1 </pre></blockquote> <p>In fact, if you look at the source code to the sqlite3 program (found in the source tree in the file src/shell.c) you'll find exactly the above query.</p> <p>The ".indices" command works in a similar way to list all of the indices for a particular table. The ".indices" command takes a single argument which is the name of the table for which the indices are desired. Last, but not least, is the ".schema" command. With no arguments, the ".schema" command shows the original CREATE TABLE and CREATE INDEX statements that were used to build the current database. If you give the name of a table to ".schema", it shows the original CREATE statement used to make that table and all if its indices. We have:</p> <tcl>Code { sqlite> (((.schema))) create table tbl1(one varchar(10), two smallint) CREATE TABLE tbl2 ( f1 varchar(30) primary key, f2 text, f3 real ) sqlite> (((.schema tbl2))) CREATE TABLE tbl2 ( f1 varchar(30) primary key, f2 text, f3 real ) sqlite> }</tcl> <p>The ".schema" command accomplishes the same thing as setting list mode, then entering the following query:</p> <blockquote><pre> SELECT sql FROM (SELECT * FROM sqlite_master UNION ALL SELECT * FROM sqlite_temp_master) WHERE type!='meta' ORDER BY tbl_name, type DESC, name </pre></blockquote> <p>Or, if you give an argument to ".schema" because you only want the schema for a single table, the query looks like this:</p> <blockquote><pre> SELECT sql FROM (SELECT * FROM sqlite_master UNION ALL SELECT * FROM sqlite_temp_master) WHERE type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY substr(type,2,1), name </pre></blockquote> <p> You can supply an argument to the .schema command. If you do, the query looks like this: </p> <blockquote><pre> SELECT sql FROM (SELECT * FROM sqlite_master UNION ALL SELECT * FROM sqlite_temp_master) WHERE tbl_name LIKE '%s' AND type!='meta' AND sql NOT NULL AND name NOT LIKE 'sqlite_%' ORDER BY substr(type,2,1), name </pre></blockquote> <p>The "%s" in the query is replace by your argument. This allows you to view the schema for some subset of the database.</p> <tcl>Code { sqlite> (((.schema %abc%))) }</tcl> <p> Along these same lines, the ".table" command also accepts a pattern as its first argument. If you give an argument to the .table command, a "%" is both appended and prepended and a LIKE clause is added to the query. This allows you to list only those tables that match a particular pattern.</p> <p>The ".databases" command shows a list of all databases open in the current connection. There will always be at least 2. The first one is "main", the original database opened. The second is "temp", the database used for temporary tables. There may be additional databases listed for databases attached using the ATTACH statement. The first output column is the name the database is attached with, and the second column is the filename of the external file.</p> <tcl>Code { sqlite> (((.databases))) }</tcl> <h3>Converting An Entire Database To An ASCII Text File</h3> <p>Use the ".dump" command to convert the entire contents of a database into a single ASCII text file. This file can be converted back into a database by piping it back into <b>sqlite3</b>.</p> <p>A good way to make an archival copy of a database is this:</p> <tcl>Code { $ (((echo '.dump' | sqlite3 ex1 | gzip -c >ex1.dump.gz))) }</tcl> <p>This generates a file named <b>ex1.dump.gz</b> that contains everything you need to reconstruct the database at a later time, or on another machine. To reconstruct the database, just type:</p> <tcl>Code { $ (((zcat ex1.dump.gz | sqlite3 ex2))) }</tcl> <p>The text format is pure SQL so you can also use the .dump command to export an SQLite database into other popular SQL database engines. Like this:</p> <tcl>Code { $ (((createdb ex2))) $ (((sqlite3 ex1 .dump | psql ex2))) }</tcl> <h3>Other Dot Commands</h3> <p>The ".explain" dot command can be used to set the output mode to "column" and to set the column widths to values that are reasonable for looking at the output of an EXPLAIN command. The EXPLAIN command is an SQLite-specific SQL extension that is useful for debugging. If any regular SQL is prefaced by EXPLAIN, then the SQL command is parsed and analyzed but is not executed. Instead, the sequence of virtual machine instructions that would have been used to execute the SQL command are returned like a query result. For example:</p> <tcl>Code { sqlite> (((.explain))) sqlite> (((explain delete from tbl1 where two<20;))) addr opcode p1 p2 p3 ---- ------------ ----- ----- ------------------------------------- 0 ListOpen 0 0 1 Open 0 1 tbl1 2 Next 0 9 3 Field 0 1 4 Integer 20 0 5 Ge 0 2 6 Key 0 0 7 ListWrite 0 0 8 Goto 0 2 9 Noop 0 0 10 ListRewind 0 0 11 ListRead 0 14 12 Delete 0 0 13 Goto 0 11 14 ListClose 0 0 }</tcl> <p>The ".timeout" command sets the amount of time that the <b>sqlite3</b> program will wait for locks to clear on files it is trying to access before returning an error. The default value of the timeout is zero so that an error is returned immediately if any needed database table or index is locked.</p> <p>And finally, we mention the ".exit" command which causes the sqlite3 program to exit.</p> <h3>Using sqlite3 in a shell script</h3> <p> One way to use sqlite3 in a shell script is to use "echo" or "cat" to generate a sequence of commands in a file, then invoke sqlite3 while redirecting input from the generated command file. This works fine and is appropriate in many circumstances. But as an added convenience, sqlite3 allows a single SQL command to be entered on the command line as a second argument after the database name. When the sqlite3 program is launched with two arguments, the second argument is passed to the SQLite library for processing, the query results are printed on standard output in list mode, and the program exits. This mechanism is designed to make sqlite3 easy to use in conjunction with programs like "awk". For example:</p> <tcl>Code { $ (((sqlite3 ex1 'select * from tbl1' |))) > ((( awk '{printf "<tr><td>%s<td>%s\n",$1,$2 }'))) <tr><td>hello<td>10 <tr><td>goodbye<td>20 $ }</tcl> <h3>Ending shell commands</h3> <p> SQLite commands are normally terminated by a semicolon. In the shell you can also use the word "GO" (case-insensitive) or a slash character "/" on a line by itself to end a command. These are used by SQL Server and Oracle, respectively. These won't work in <b>sqlite3_exec()</b>, because the shell translates these into a semicolon before passing them to that function.</p> <h3>Compiling the sqlite3 program from sources</h3> <p> The sqlite3 program is built automatically when you compile the SQLite library. Just get a copy of the source tree, run "configure" and then "make".</p> footer $rcsid |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 | <title>SQLite Support Options</title> <h2>SQLite Support Options</h2> <h3>Mailing List</h3> <p> A mailing list has been set up for asking questions and for open discussion of problems and issues by the SQLite user community. To subscribe to the mailing list, send an email to <a href="mailto:sqlite-users-subscribe@sqlite.org"> sqlite-users-subscribe@sqlite.org</a>. If you would prefer to get digests rather than individual emails, send a message to to <a href="mailto:sqlite-users-digest-subscribe@sqlite.org"> sqlite-users-digest-subscribe@sqlite.org</a>. For additional information about operating and using this mailing list, send a message to <a href="mailto:sqlite-users-help@sqlite.org"> sqlite-users-help@sqlite.org</a> and instructions will be sent by to you by return email. </p> <p> There are multiple archives of the mailing list: </p> <blockquote> <a href="http://www.mail-archive.com/sqlite-users%40sqlite.org/"> http://www.mail-archive.com/sqlite-users%40sqlite.org</a><br> <a href="http://marc.info/?l=sqlite-users&r=1&w=2"> http://marc.info/?l=sqlite-users&r=1&w=2</a><br> <a href="http://news.gmane.org/gmane.comp.db.sqlite.general"> http://news.gmane.org/gmane.comp.db.sqlite.general</a> </blockquote> </p> <a name="directemail"></a> <h3>Direct E-Mail To The Author</h3> <p> Use the mailing list. Please do <b>not</b> send email directly to the author of SQLite unless: <ul> <li>You have or intend to acquire a professional support contract as described below, or</li> <li>You are working on an open source project.</li> </ul> You are welcomed to use SQLite in closed source, proprietary, and/or commerical projects and to ask questions about such use on the public mailing list. But please do not ask to receive free direct technical support. The software is free; direct technical support is not. </p> <h3>Professional Support</h3> <p> If you would like professional support for SQLite or if you want custom modifications to SQLite performed by the original author, these services are available for a modest fee. For additional information visit <a href="http://www.hwaci.com/sw/sqlite/prosupport.html"> http://www.hwaci.com/sw/sqlite/prosupport.html</a> or contact:</p> <blockquote> D. Richard Hipp <br /> Hwaci - Applied Software Research <br /> 704.948.4565 <br /> <a href="mailto:drh@hwaci.com">drh@hwaci.com</a> </blockquote> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 | <title>The Tcl interface to the SQLite library</title> <tcl> proc METHOD {name text} { puts "<a name=\"$name\"></a>\n<h3>The \"$name\" method</h3>\n" puts $text } puts { <h2>The Tcl interface to the SQLite library</h2> <p>The SQLite library is designed to be very easy to use from a Tcl or Tcl/Tk script. This document gives an overview of the Tcl programming interface.</p> <h3>The API</h3> <p>The interface to the SQLite library consists of single tcl command named <b>sqlite3</b> Because there is only this one command, the interface is not placed in a separate namespace.</p> <p>The <b>sqlite3</b> command is used as follows:</p> <blockquote> <b>sqlite3</b> <i>dbcmd database-name</i> </blockquote> <p> The <b>sqlite3</b> command opens the database named in the second argument. If the database does not already exist, it is automatically created. The <b>sqlite3</b> command also creates a new Tcl 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 an empty string or the special name ":memory:" then a new database is created in memory. </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> <p> <ul> } foreach m [lsort { authorizer busy cache changes close collate collation_needed commit_hook complete copy enable_load_extension errorcode eval exists function last_insert_rowid nullvalue onecolumn profile progress rollback_hook timeout total_changes trace transaction update_hook version }] { puts "<li><a href=\"#$m\">$m</a></li>" } puts { </ul> </p> <p>The use of each of these methods will be explained in the sequel, though not in the order shown above.</p> } ############################################################################## METHOD eval { <p> The most useful <i>dbcmd</i> method is "eval". The eval method is used to execute SQL on the database. The syntax of the eval method looks like this:</p> <blockquote> <i>dbcmd</i> <b>eval</b> <i>sql</i> ?<i>array-name </i>? ?<i>script</i>? </blockquote> <p> The job of the eval method is to execute the SQL statement or statements given in the second argument. For example, to create a new table in a database, you can do this:</p> <blockquote> <b>sqlite3 db1 ./testdb<br> db1 eval {CREATE TABLE t1(a int, b text)}</b> </blockquote> <p>The above code creates a new table named <b>t1</b> with columns <b>a</b> and <b>b</b>. What could be simpler?</p> <p>Query results are returned as a list of column values. If a query requests 2 columns and there are 3 rows matching the query, then the returned list will contain 6 elements. For example:</p> <blockquote> <b>db1 eval {INSERT INTO t1 VALUES(1,'hello')}<br> db1 eval {INSERT INTO t1 VALUES(2,'goodbye')}<br> db1 eval {INSERT INTO t1 VALUES(3,'howdy!')}<br> set x [db1 eval {SELECT * FROM t1 ORDER BY a}]</b> </blockquote> <p>The variable <b>$x</b> is set by the above code to</p> <blockquote> <b>1 hello 2 goodbye 3 howdy!</b> </blockquote> <p>You can also process the results of a query one row at a time by specifying the name of an array variable and a script following the SQL code. For each row of the query result, the values of all columns will be inserted into the array variable and the script will be executed. For instance:</p> <blockquote> <b>db1 eval {SELECT * FROM t1 ORDER BY a} values {<br> parray values<br> puts ""<br> }</b> </blockquote> <p>This last code will give the following output:</p> <blockquote><b> values(*) = a b<br> values(a) = 1<br> values(b) = hello<p> values(*) = a b<br> values(a) = 2<br> values(b) = goodbye<p> values(*) = a b<br> values(a) = 3<br> values(b) = howdy!</b> </blockquote> <p> For each column in a row of the result, the name of that column is used as an index in to array. The value of the column is stored in the corresponding array entry. The special array index * is used to store a list of column names in the order that they appear. </p> <p> If the array variable name is omitted or is the empty string, then the value of each column is stored in a variable with the same name as the column itself. For example: </p> <blockquote> <b>db1 eval {SELECT * FROM t1 ORDER BY a} {<br> puts "a=$a b=$b"<br> }</b> </blockquote> <p> From this we get the following output </p> <blockquote><b> a=1 b=hello<br> a=2 b=goodbye<br> a=3 b=howdy!</b> </blockquote> <p> Tcl variable names can appear in the SQL statement of the second argument in any position where it is legal to put a string or number literal. The value of the variable is substituted for the variable name. If the variable does not exist a NULL values is used. For example: </p> <blockquote><b> db1 eval {INSERT INTO t1 VALUES(5,$bigstring)} </b></blockquote> <p> Note that it is not necessary to quote the $bigstring value. That happens automatically. If $bigstring is a large string or binary object, this technique is not only easier to write, it is also much more efficient since it avoids making a copy of the content of $bigstring. </p> <p> If the $bigstring variable has both a string and a "bytearray" representation, then TCL inserts the value as a string. If it has only a "bytearray" representation, then the value is inserted as a BLOB. To force a value to be inserted as a BLOB even if it also has a text representation, us a "@" character to in place of the "$". Like this: </p> <blockquote><b> db1 eval {INSERT INTO t1 VALUES(5,@bigstring)} </b></blockquote> <p> If the variable does not have a bytearray representation, then "@" works just like "$". </p> } ############################################################################## METHOD close { <p> As its name suggests, the "close" method to an SQLite database just closes the database. This has the side-effect of deleting the <i>dbcmd</i> Tcl command. Here is an example of opening and then immediately closing a database: </p> <blockquote> <b>sqlite3 db1 ./testdb<br> db1 close</b> </blockquote> <p> If you delete the <i>dbcmd</i> directly, that has the same effect as invoking the "close" method. So the following code is equivalent to the previous:</p> <blockquote> <b>sqlite3 db1 ./testdb<br> rename db1 {}</b> </blockquote> } ############################################################################## METHOD transaction { <p> The "transaction" method is used to execute a TCL script inside an SQLite database transaction. The transaction is committed when the script completes, or it rolls back if the script fails. If the transaction occurs within another transaction (even one that is started manually using BEGIN) it is a no-op. </p> <p> The transaction command can be used to group together several SQLite commands in a safe way. You can always start transactions manually using BEGIN, of course. But if an error occurs so that the COMMIT or ROLLBACK are never run, then the database will remain locked indefinitely. Also, BEGIN does not nest, so you have to make sure no other transactions are active before starting a new one. The "transaction" method takes care of all of these details automatically. </p> <p> The syntax looks like this: </p> <blockquote> <i>dbcmd</i> <b>transaction</b> <i>?transaction-type?</i> <i>SCRIPT,</i> </blockquote> <p> The <i>transaction-type</i> can be one of <b>deferred</b>, <b>exclusive</b> or <b>immediate</b>. The default is deferred. </p> } ############################################################################## METHOD cache { <p> The "eval" method described <a href="#eval">above</a> keeps a cache of <a href="capi3ref.html#sqlite3_prepare">prepared statements</a> for recently evaluated SQL commands. The "cache" method is used to control this cache. The first form of this command is:</p> <blockquote> <i>dbcmd</i> <b>cache size</b> <i>N</i> </blockquote> <p>This sets the maximum number of statements that can be cached. The upper limit is 100. The default is 10. If you set the cache size to 0, no caching is done.</p> <p>The second form of the command is this:</p> <blockquote> <i>dbcmd</i> <b>cache flush</b> </blockquote> <p>The cache-flush method <a href="capi3ref.html#sqlite3_finalize">finalizes</a> all prepared statements currently in the cache.</p> } ############################################################################## METHOD complete { <p> The "complete" method takes a string of supposed SQL as its only argument. It returns TRUE if the string is a complete statement of SQL and FALSE if there is more to be entered.</p> <p>The "complete" method is useful when building interactive applications in order to know when the user has finished entering a line of SQL code. This is really just an interface to the <a href="capi3ref.html#sqlite3_complete"><b>sqlite3_complete()</b></a> C function. } ############################################################################## METHOD copy { <p> The "copy" method copies data from a file into a table. It returns the number of rows processed successfully from the file. The syntax of the copy method looks like this:</p> <blockquote> <i>dbcmd</i> <b>copy</b> <i>conflict-algorithm</i> <i>table-name </i> <i>file-name </i> ?<i>column-separator </i>? ?<i>null-indicator</i>? </blockquote> <p>Conflict-alogrithm must be one of the SQLite conflict algorithms for the INSERT statement: <i>rollback</i>, <i>abort</i>, <i>fail</i>,<i>ignore</i>, or <i>replace</i>. See the SQLite Language section for <a href="lang.html#conflict">ON CONFLICT</a> for more information. The conflict-algorithm must be specified in lower case. </p> <p>Table-name must already exists as a table. File-name must exist, and each row must contain the same number of columns as defined in the table. If a line in the file contains more or less than the number of columns defined, the copy method rollbacks any inserts, and returns an error.</p> <p>Column-separator is an optional column separator string. The default is the ASCII tab character \t. </p> <p>Null-indicator is an optional string that indicates a column value is null. The default is an empty string. Note that column-separator and null-indicator are optional positional arguments; if null-indicator is specified, a column-separator argument must be specifed and precede the null-indicator argument.</p> <p>The copy method implements similar functionality to the <b>.import</b> SQLite shell command. The SQLite 2.x <a href="lang.html#copy"><b>COPY</b></a> statement (using the PostgreSQL COPY file format) can be implemented with this method as:</p> <blockquote> dbcmd copy $conflictalgo $tablename $filename \t \\N </blockquote> } ############################################################################## METHOD timeout { <p>The "timeout" method is used to control how long the SQLite library will wait for locks to clear before giving up on a database transaction. The default timeout is 0 millisecond. (In other words, the default behavior is not to wait at all.)</p> <p>The SQLite database allows multiple simultaneous readers or a single writer but not both. If any process is writing to the database no other process is allows to read or write. If any process is reading the database other processes are allowed to read but not write. The entire database shared a single lock.</p> <p>When SQLite tries to open a database and finds that it is locked, it can optionally delay for a short while and try to open the file again. This process repeats until the query times out and SQLite returns a failure. The timeout is adjustable. It is set to 0 by default so that if the database is locked, the SQL statement fails immediately. But you can use the "timeout" method to change the timeout value to a positive number. For example:</p> <blockquote><b>db1 timeout 2000</b></blockquote> <p>The argument to the timeout method is the maximum number of milliseconds to wait for the lock to clear. So in the example above, the maximum delay would be 2 seconds.</p> } ############################################################################## METHOD busy { <p>The "busy" method, like "timeout", only comes into play when the database is locked. But the "busy" method gives the programmer much more control over what action to take. The "busy" method specifies a callback Tcl procedure that is invoked whenever SQLite tries to open a locked database. This callback can do whatever is desired. Presumably, the callback will do some other useful work for a short while (such as service GUI events) then return so that the lock can be tried again. The callback procedure should return "0" if it wants SQLite to try again to open the database and should return "1" if it wants SQLite to abandon the current operation. } ############################################################################## METHOD exists { <p>The "exists" method is similar to "onecolumn" and "eval" in that it executes SQL statements. The difference is that the "exists" method always returns a boolean value which is TRUE if a query in the SQL statement it executes returns one or more rows and FALSE if the SQL returns an empty set.</p> <p>The "exists" method is often used to test for the existance of rows in a table. For example:</p> <blockquote><b> if {[db exists {SELECT 1 FROM table1 WHERE user=$user}]} {<br> # Processing if $user exists<br> } else {<br> # Processing if $user does not exist<br> } </b></blockquote> } ############################################################################## METHOD last_insert_rowid { <p>The "last_insert_rowid" method returns an integer which is the ROWID of the most recently inserted database row.</p> } ############################################################################## METHOD function { <p>The "function" method registers new SQL functions with the SQLite engine. The arguments are the name of the new SQL function and a TCL command that implements that function. Arguments to the function are appended to the TCL command before it is invoked.</p> <p> The following example creates a new SQL function named "hex" that converts its numeric argument in to a hexadecimal encoded string: </p> <blockquote><b> db function hex {format 0x%X} </b></blockquote> } ############################################################################## METHOD nullvalue { <p> The "nullvalue" method changes the representation for NULL returned as result of the "eval" method.</p> <blockquote><b> db1 nullvalue NULL </b></blockquote> <p>The "nullvalue" method is useful to differ between NULL and empty column values as Tcl lacks a NULL representation. The default representation for NULL values is an empty string.</p> } ############################################################################## METHOD onecolumn { <p>The "onecolumn" method works like "<a href="#eval">eval</a>" in that it evaluates the SQL query statement given as its argument. The difference is that "onecolumn" returns a single element which is the first column of the first row of the query result.</p> <p>This is a convenience method. It saves the user from having to do a "<tt>[lindex ... 0]</tt>" on the results of an "eval" in order to extract a single column result.</p> } ############################################################################## METHOD changes { <p>The "changes" method returns an integer which is the number of rows in the database that were inserted, deleted, and/or modified by the most recent "eval" method.</p> } ############################################################################## METHOD total_changes { <p>The "total_changes" method returns an integer which is the number of rows in the database that were inserted, deleted, and/or modified since the current database connection was first opened.</p> } ############################################################################## METHOD authorizer { <p>The "authorizer" method provides access to the <a href="capi3ref.html#sqlite3_set_authorizer">sqlite3_set_authorizer</a> C/C++ interface. The argument to authorizer is the name of a procedure that is called when SQL statements are being compiled in order to authorize certain operations. The callback procedure takes 5 arguments which describe the operation being coded. If the callback returns the text string "SQLITE_OK", then the operation is allowed. If it returns "SQLITE_IGNORE", then the operation is silently disabled. If the return is "SQLITE_DENY" then the compilation fails with an error. </p> <p>If the argument is an empty string then the authorizer is disabled. If the argument is omitted, then the current authorizer is returned.</p> } ############################################################################## METHOD progress { <p>This method registers a callback that is invoked periodically during query processing. There are two arguments: the number of SQLite virtual machine opcodes between invocations, and the TCL command to invoke. Setting the progress callback to an empty string disables it.</p> <p>The progress callback can be used to display the status of a lengthy query or to process GUI events during a lengthy query.</p> } ############################################################################## METHOD collate { <p>This method registers new text collating sequences. There are two arguments: the name of the collating sequence and the name of a TCL procedure that implements a comparison function for the collating sequence. </p> <p>For example, the following code implements a collating sequence called "NOCASE" that sorts in text order without regard to case: </p> <blockquote><b> proc nocase_compare {a b} {<br> return [string compare [string tolower $a] [string tolower $b]]<br> }<br> db collate NOCASE nocase_compare<br> </b></blockquote> } ############################################################################## METHOD collation_needed { <p>This method registers a callback routine that is invoked when the SQLite engine needs a particular collating sequence but does not have that collating sequence registered. The callback can register the collating sequence. The callback is invoked with a single parameter which is the name of the needed collating sequence.</p> } ############################################################################## METHOD commit_hook { <p>This method registers a callback routine that is invoked just before SQLite tries to commit changes to a database. If the callback throws an exception or returns a non-zero result, then the transaction rolls back rather than commit.</p> } ############################################################################## METHOD rollback_hook { <p>This method registers a callback routine that is invoked just before SQLite tries to do a rollback. The script argument is run without change.</p> } ############################################################################## METHOD update_hook { <p>This method registers a callback routine that is invoked just before each row is modified by an UPDATE, INSERT, or DELETE statement. Four arguments are appended to the callback before it is invoked:</p> <ul> <li>The keyword "INSERT", "UPDATE", or "DELETE", as appropriate</li> <li>The name of the database which is being changed</li> <li>The table that is being changed</li> <li>The rowid of the row in the table being changed</li> </ul> } ############################################################################## METHOD incrblob { <p>This method opens a TCL channel that can be used to read or write into a preexisting BLOB in the database. The syntax is like this:</p> <blockquote> <i>dbcmd</i> <b>incrblob</b> <b>?-readonly??</b> <i>?DB? TABLE COLUMN ROWID</i> </blockquote> <p> The command returns a new TCL channel for reading or writing to the BLOB. The channel is opened using the underlying <a href="/capi3ref.html#sqlite3_blob_open">sqlite3_blob_open()</a> C-langauge interface. Close the channel using the <b>close</b> command of TCL. </p> } ############################################################################## METHOD errorcode { <p>This method returns the numeric error code that resulted from the most recent SQLite operation.</p> } ############################################################################## METHOD trace { <p>The "trace" method registers a callback that is invoked as each SQL statement is compiled. The text of the SQL is appended as a single string to the command before it is invoked. This can be used (for example) to keep a log of all SQL operations that an application performs. </p> } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 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 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 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 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 | <title>The Virtual Database Engine of SQLite</title> <tcl> puts { <h2>The Virtual Database Engine of SQLite</h2> <blockquote><b> This document describes the virtual machine used in SQLite version 2.8.0. The virtual machine in SQLite version 3.0 and 3.1 is very similar in concept but many of the opcodes have changed and the algorithms are somewhat different. Use this document as a rough guide to the idea behind the virtual machine in SQLite version 3, not as a reference on how the virtual machine works. </b></blockquote> } puts { <p>If you want to know how the SQLite library works internally, you need to begin with a solid understanding of the Virtual Database Engine or VDBE. The VDBE occurs right in the middle of the processing stream (see the <a href="arch.html">architecture diagram</a>) and so it seems to touch most parts of the library. Even parts of the code that do not directly interact with the VDBE are usually in a supporting role. The VDBE really is the heart of SQLite.</p> <p>This article is a brief introduction to how the VDBE works and in particular how the various VDBE instructions (documented <a href="opcode.html">here</a>) work together to do useful things with the database. The style is tutorial, beginning with simple tasks and working toward solving more complex problems. Along the way we will visit most submodules in the SQLite library. After completeing this tutorial, you should have a pretty good understanding of how SQLite works and will be ready to begin studying the actual source code.</p> <h2>Preliminaries</h2> <p>The VDBE implements a virtual computer that runs a program in its virtual machine language. The goal of each program is to interrogate or change the database. Toward this end, the machine language that the VDBE implements is specifically designed to search, read, and modify databases.</p> <p>Each instruction of the VDBE language contains an opcode and three operands labeled P1, P2, and P3. Operand P1 is an arbitrary integer. P2 is a non-negative integer. P3 is a pointer to a data structure or null-terminated string, possibly null. Only a few VDBE instructions use all three operands. Many instructions use only one or two operands. A significant number of instructions use no operands at all but instead take their data and store their results on the execution stack. The details of what each instruction does and which operands it uses are described in the separate <a href="opcode.html">opcode description</a> document.</p> <p>A VDBE program begins execution on instruction 0 and continues with successive instructions until it either (1) encounters a fatal error, (2) executes a Halt instruction, or (3) advances the program counter past the last instruction of the program. When the VDBE completes execution, all open database cursors are closed, all memory is freed, and everything is popped from the stack. So there are never any worries about memory leaks or undeallocated resources.</p> <p>If you have done any assembly language programming or have worked with any kind of abstract machine before, all of these details should be familiar to you. So let's jump right in and start looking as some code.</p> <a name="insert1"></a> <h2>Inserting Records Into The Database</h2> <p>We begin with a problem that can be solved using a VDBE program that is only a few instructions long. Suppose we have an SQL table that was created like this:</p> <blockquote><pre> CREATE TABLE examp(one text, two int); </pre></blockquote> <p>In words, we have a database table named "examp" that has two columns of data named "one" and "two". Now suppose we want to insert a single record into this table. Like this:</p> <blockquote><pre> INSERT INTO examp VALUES('Hello, World!',99); </pre></blockquote> <p>We can see the VDBE program that SQLite uses to implement this INSERT using the <b>sqlite</b> command-line utility. First start up <b>sqlite</b> on a new, empty database, then create the table. Next change the output format of <b>sqlite</b> to a form that is designed to work with VDBE program dumps by entering the ".explain" command. Finally, enter the INSERT statement shown above, but precede the INSERT with the special keyword "EXPLAIN". The EXPLAIN keyword will cause <b>sqlite</b> to print the VDBE program rather than execute it. We have:</p> } proc Code {body} { puts {<blockquote><tt>} regsub -all {&} [string trim $body] {\&} body regsub -all {>} $body {\>} body regsub -all {<} $body {\<} body regsub -all {\(\(\(} $body {<b>} body regsub -all {\)\)\)} $body {</b>} body regsub -all { } $body {\ } body regsub -all \n $body <br>\n body puts $body puts {</tt></blockquote>} } Code { $ (((sqlite test_database_1))) sqlite> (((CREATE TABLE examp(one text, two int);))) sqlite> (((.explain))) sqlite> (((EXPLAIN INSERT INTO examp VALUES('Hello, World!',99);))) addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 Transaction 0 0 1 VerifyCookie 0 81 2 Transaction 1 0 3 Integer 0 0 4 OpenWrite 0 3 examp 5 NewRecno 0 0 6 String 0 0 Hello, World! 7 Integer 99 0 99 8 MakeRecord 2 0 9 PutIntKey 0 1 10 Close 0 0 11 Commit 0 0 12 Halt 0 0 } puts {<p>As you can see above, our simple insert statement is implemented in 12 instructions. The first 3 and last 2 instructions are a standard prologue and epilogue, so the real work is done in the middle 7 instructions. There are no jumps, so the program executes once through from top to bottom. Let's now look at each instruction in detail.<p> } Code { 0 Transaction 0 0 1 VerifyCookie 0 81 2 Transaction 1 0 } puts { <p>The instruction <a href="opcode.html#Transaction">Transaction</a> begins a transaction. The transaction ends when a Commit or Rollback opcode is encountered. P1 is the index of the database file on which the transaction is started. Index 0 is the main database file. A write lock is obtained on the database file when a transaction is started. No other process can read or write the file while the transaction is underway. Starting a transaction also creates a rollback journal. A transaction must be started before any changes can be made to the database.</p> <p>The instruction <a href="opcode.html#VerifyCookie">VerifyCookie</a> checks cookie 0 (the database schema version) to make sure it is equal to P2 (the value obtained when the database schema was last read). P1 is the database number (0 for the main database). This is done to make sure the database schema hasn't been changed by another thread, in which case it has to be reread.</p> <p> The second <a href="opcode.html#Transaction">Transaction</a> instruction begins a transaction and starts a rollback journal for database 1, the database used for temporary tables.</p> } proc stack args { puts "<blockquote><table border=2>" foreach elem $args { puts "<tr><td align=left>$elem</td></tr>" } puts "</table></blockquote>" } Code { 3 Integer 0 0 4 OpenWrite 0 3 examp } puts { <p> The instruction <a href="opcode.html#Integer">Integer</a> pushes the integer value P1 (0) onto the stack. Here 0 is the number of the database to use in the following OpenWrite instruction. If P3 is not NULL then it is a string representation of the same integer. Afterwards the stack looks like this:</p> } stack {(integer) 0} puts { <p> The instruction <a href="opcode.html#OpenWrite">OpenWrite</a> opens a new read/write cursor with handle P1 (0 in this case) on table "examp", whose root page is P2 (3, in this database file). Cursor handles can be any non-negative integer. But the VDBE allocates cursors in an array with the size of the array being one more than the largest cursor. So to conserve memory, it is best to use handles beginning with zero and working upward consecutively. Here P3 ("examp") is the name of the table being opened, but this is unused, and only generated to make the code easier to read. This instruction pops the database number to use (0, the main database) from the top of the stack, so afterwards the stack is empty again.</p> } Code { 5 NewRecno 0 0 } puts { <p> The instruction <a href="opcode.html#NewRecno">NewRecno</a> creates a new integer record number for the table pointed to by cursor P1. The record number is one not currently used as a key in the table. The new record number is pushed onto the stack. Afterwards the stack looks like this:</p> } stack {(integer) new record key} Code { 6 String 0 0 Hello, World! } puts { <p> The instruction <a href="opcode.html#String">String</a> pushes its P3 operand onto the stack. Afterwards the stack looks like this:</p> } stack {(string) "Hello, World!"} \ {(integer) new record key} Code { 7 Integer 99 0 99 } puts { <p> The instruction <a href="opcode.html#Integer">Integer</a> pushes its P1 operand (99) onto the stack. Afterwards the stack looks like this:</p> } stack {(integer) 99} \ {(string) "Hello, World!"} \ {(integer) new record key} Code { 8 MakeRecord 2 0 } puts { <p> The instruction <a href="opcode.html#MakeRecord">MakeRecord</a> pops the top P1 elements off the stack (2 in this case) and converts them into the binary format used for storing records in a database file. (See the <a href="fileformat.html">file format</a> description for details.) The new record generated by the MakeRecord instruction is pushed back onto the stack. Afterwards the stack looks like this:</p> </ul> } stack {(record) "Hello, World!", 99} \ {(integer) new record key} Code { 9 PutIntKey 0 1 } puts { <p> The instruction <a href="opcode.html#PutIntKey">PutIntKey</a> uses the top 2 stack entries to write an entry into the table pointed to by cursor P1. A new entry is created if it doesn't already exist or the data for an existing entry is overwritten. The record data is the top stack entry, and the key is the next entry down. The stack is popped twice by this instruction. Because operand P2 is 1 the row change count is incremented and the rowid is stored for subsequent return by the sqlite_last_insert_rowid() function. If P2 is 0 the row change count is unmodified. This instruction is where the insert actually occurs.</p> } Code { 10 Close 0 0 } puts { <p> The instruction <a href="opcode.html#Close">Close</a> closes a cursor previously opened as P1 (0, the only open cursor). If P1 is not currently open, this instruction is a no-op.</p> } Code { 11 Commit 0 0 } puts { <p> The instruction <a href="opcode.html#Commit">Commit</a> causes all modifications to the database that have been made since the last Transaction to actually take effect. No additional modifications are allowed until another transaction is started. The Commit instruction deletes the journal file and releases the write lock on the database. A read lock continues to be held if there are still cursors open.</p> } Code { 12 Halt 0 0 } puts { <p> The instruction <a href="opcode.html#Halt">Halt</a> causes the VDBE engine to exit immediately. All open cursors, Lists, Sorts, etc are closed automatically. P1 is the result code returned by sqlite_exec(). For a normal halt, this should be SQLITE_OK (0). For errors, it can be some other value. The operand P2 is only used when there is an error. There is an implied "Halt 0 0 0" instruction at the end of every program, which the VDBE appends when it prepares a program to run.</p> <a name="trace"></a> <h2>Tracing VDBE Program Execution</h2> <p>If the SQLite library is compiled without the NDEBUG preprocessor macro, then the PRAGMA <a href="pragma.html#pragma_vdbe_trace">vdbe_trace </a> causes the VDBE to trace the execution of programs. Though this feature was originally intended for testing and debugging, it can also be useful in learning about how the VDBE operates. Use "<tt>PRAGMA vdbe_trace=ON;</tt>" to turn tracing on and "<tt>PRAGMA vdbe_trace=OFF</tt>" to turn tracing back off. Like this:</p> } Code { sqlite> (((PRAGMA vdbe_trace=ON;))) 0 Halt 0 0 sqlite> (((INSERT INTO examp VALUES('Hello, World!',99);))) 0 Transaction 0 0 1 VerifyCookie 0 81 2 Transaction 1 0 3 Integer 0 0 Stack: i:0 4 OpenWrite 0 3 examp 5 NewRecno 0 0 Stack: i:2 6 String 0 0 Hello, World! Stack: t[Hello,.World!] i:2 7 Integer 99 0 99 Stack: si:99 t[Hello,.World!] i:2 8 MakeRecord 2 0 Stack: s[...Hello,.World!.99] i:2 9 PutIntKey 0 1 10 Close 0 0 11 Commit 0 0 12 Halt 0 0 } puts { <p>With tracing mode on, the VDBE prints each instruction prior to executing it. After the instruction is executed, the top few entries in the stack are displayed. The stack display is omitted if the stack is empty.</p> <p>On the stack display, most entries are shown with a prefix that tells the datatype of that stack entry. Integers begin with "<tt>i:</tt>". Floating point values begin with "<tt>r:</tt>". (The "r" stands for "real-number".) Strings begin with either "<tt>s:</tt>", "<tt>t:</tt>", "<tt>e:</tt>" or "<tt>z:</tt>". The difference among the string prefixes is caused by how their memory is allocated. The z: strings are stored in memory obtained from <b>malloc()</b>. The t: strings are statically allocated. The e: strings are ephemeral. All other strings have the s: prefix. This doesn't make any difference to you, the observer, but it is vitally important to the VDBE since the z: strings need to be passed to <b>free()</b> when they are popped to avoid a memory leak. Note that only the first 10 characters of string values are displayed and that binary values (such as the result of the MakeRecord instruction) are treated as strings. The only other datatype that can be stored on the VDBE stack is a NULL, which is display without prefix as simply "<tt>NULL</tt>". If an integer has been placed on the stack as both an integer and a string, its prefix is "<tt>si:</tt>". <a name="query1"></a> <h2>Simple Queries</h2> <p>At this point, you should understand the basics of how the VDBE writes to a database. Now let's look at how it does queries. We will use the following simple SELECT statement as our example:</p> <blockquote><pre> SELECT * FROM examp; </pre></blockquote> <p>The VDBE program generated for this SQL statement is as follows:</p> } Code { sqlite> (((EXPLAIN SELECT * FROM examp;))) addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 one 1 ColumnName 1 0 two 2 Integer 0 0 3 OpenRead 0 3 examp 4 VerifyCookie 0 81 5 Rewind 0 10 6 Column 0 0 7 Column 0 1 8 Callback 2 0 9 Next 0 6 10 Close 0 0 11 Halt 0 0 } puts { <p>Before we begin looking at this problem, let's briefly review how queries work in SQLite so that we will know what we are trying to accomplish. For each row in the result of a query, SQLite will invoke a callback function with the following prototype:</p> <blockquote><pre> int Callback(void *pUserData, int nColumn, char *azData[], char *azColumnName[]); </pre></blockquote> <p>The SQLite library supplies the VDBE with a pointer to the callback function and the <b>pUserData</b> pointer. (Both the callback and the user data were originally passed in as arguments to the <b>sqlite_exec()</b> API function.) The job of the VDBE is to come up with values for <b>nColumn</b>, <b>azData[]</b>, and <b>azColumnName[]</b>. <b>nColumn</b> is the number of columns in the results, of course. <b>azColumnName[]</b> is an array of strings where each string is the name of one of the result columns. <b>azData[]</b> is an array of strings holding the actual data.</p> } Code { 0 ColumnName 0 0 one 1 ColumnName 1 0 two } puts { <p>The first two instructions in the VDBE program for our query are concerned with setting up values for <b>azColumn</b>. The <a href="opcode.html#ColumnName">ColumnName</a> instructions tell the VDBE what values to fill in for each element of the <b>azColumnName[]</b> array. Every query will begin with one ColumnName instruction for each column in the result, and there will be a matching Column instruction for each one later in the query. </p> } Code { 2 Integer 0 0 3 OpenRead 0 3 examp 4 VerifyCookie 0 81 } puts { <p>Instructions 2 and 3 open a read cursor on the database table that is to be queried. This works the same as the OpenWrite instruction in the INSERT example except that the cursor is opened for reading this time instead of for writing. Instruction 4 verifies the database schema as in the INSERT example.</p> } Code { 5 Rewind 0 10 } puts { <p> The <a href="opcode.html#Rewind">Rewind</a> instruction initializes a loop that iterates over the "examp" table. It rewinds the cursor P1 to the first entry in its table. This is required by the the Column and Next instructions, which use the cursor to iterate through the table. If the table is empty, then jump to P2 (10), which is the instruction just past the loop. If the table is not empty, fall through to the following instruction at 6, which is the beginning of the loop body.</p> } Code { 6 Column 0 0 7 Column 0 1 8 Callback 2 0 } puts { <p> The instructions 6 through 8 form the body of the loop that will execute once for each record in the database file. The <a href="opcode.html#Column">Column</a> instructions at addresses 6 and 7 each take the P2-th column from the P1-th cursor and push it onto the stack. In this example, the first Column instruction is pushing the value for the column "one" onto the stack and the second Column instruction is pushing the value for column "two". The <a href="opcode.html#Callback">Callback</a> instruction at address 8 invokes the callback() function. The P1 operand to Callback becomes the value for <b>nColumn</b>. The Callback instruction pops P1 values from the stack and uses them to fill the <b>azData[]</b> array.</p> } Code { 9 Next 0 6 } puts { <p>The instruction at address 9 implements the branching part of the loop. Together with the Rewind at address 5 it forms the loop logic. This is a key concept that you should pay close attention to. The <a href="opcode.html#Next">Next</a> instruction advances the cursor P1 to the next record. If the cursor advance was successful, then jump immediately to P2 (6, the beginning of the loop body). If the cursor was at the end, then fall through to the following instruction, which ends the loop.</p> } Code { 10 Close 0 0 11 Halt 0 0 } puts { <p>The Close instruction at the end of the program closes the cursor that points into the table "examp". It is not really necessary to call Close here since all cursors will be automatically closed by the VDBE when the program halts. But we needed an instruction for the Rewind to jump to so we might as well go ahead and have that instruction do something useful. The Halt instruction ends the VDBE program.</p> <p>Note that the program for this SELECT query didn't contain the Transaction and Commit instructions used in the INSERT example. Because the SELECT is a read operation that doesn't alter the database, it doesn't require a transaction.</p> } puts { <a name="query2"></a> <h2>A Slightly More Complex Query</h2> <p>The key points of the previous example were the use of the Callback instruction to invoke the callback function, and the use of the Next instruction to implement a loop over all records of the database file. This example attempts to drive home those ideas by demonstrating a slightly more complex query that involves more columns of output, some of which are computed values, and a WHERE clause that limits which records actually make it to the callback function. Consider this query:</p> <blockquote><pre> SELECT one, two, one || two AS 'both' FROM examp WHERE one LIKE 'H%' </pre></blockquote> <p>This query is perhaps a bit contrived, but it does serve to illustrate our points. The result will have three column with names "one", "two", and "both". The first two columns are direct copies of the two columns in the table and the third result column is a string formed by concatenating the first and second columns of the table. Finally, the WHERE clause says that we will only chose rows for the results where the "one" column begins with an "H". Here is what the VDBE program looks like for this query:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 one 1 ColumnName 1 0 two 2 ColumnName 2 0 both 3 Integer 0 0 4 OpenRead 0 3 examp 5 VerifyCookie 0 81 6 Rewind 0 18 7 String 0 0 H% 8 Column 0 0 9 Function 2 0 ptr(0x7f1ac0) 10 IfNot 1 17 11 Column 0 0 12 Column 0 1 13 Column 0 0 14 Column 0 1 15 Concat 2 0 16 Callback 3 0 17 Next 0 7 18 Close 0 0 19 Halt 0 0 } puts { <p>Except for the WHERE clause, the structure of the program for this example is very much like the prior example, just with an extra column. There are now 3 columns, instead of 2 as before, and there are three ColumnName instructions. A cursor is opened using the OpenRead instruction, just like in the prior example. The Rewind instruction at address 6 and the Next at address 17 form a loop over all records of the table. The Close instruction at the end is there to give the Rewind instruction something to jump to when it is done. All of this is just like in the first query demonstration.</p> <p>The Callback instruction in this example has to generate data for three result columns instead of two, but is otherwise the same as in the first query. When the Callback instruction is invoked, the left-most column of the result should be the lowest in the stack and the right-most result column should be the top of the stack. We can see the stack being set up this way at addresses 11 through 15. The Column instructions at 11 and 12 push the values for the first two columns in the result. The two Column instructions at 13 and 14 pull in the values needed to compute the third result column and the Concat instruction at 15 joins them together into a single entry on the stack.</p> <p>The only thing that is really new about the current example is the WHERE clause which is implemented by instructions at addresses 7 through 10. Instructions at address 7 and 8 push onto the stack the value of the "one" column from the table and the literal string "H%". The <a href="opcode.html#Function">Function</a> instruction at address 9 pops these two values from the stack and pushes the result of the LIKE() function back onto the stack. The <a href="opcode.html#IfNot">IfNot</a> instruction pops the top stack value and causes an immediate jump forward to the Next instruction if the top value was false (<em>not</em> not like the literal string "H%"). Taking this jump effectively skips the callback, which is the whole point of the WHERE clause. If the result of the comparison is true, the jump is not taken and control falls through to the Callback instruction below.</p> <p>Notice how the LIKE operator is implemented. It is a user-defined function in SQLite, so the address of its function definition is specified in P3. The operand P1 is the number of function arguments for it to take from the stack. In this case the LIKE() function takes 2 arguments. The arguments are taken off the stack in reverse order (right-to-left), so the pattern to match is the top stack element, and the next element is the data to compare. The return value is pushed onto the stack.</p> <a name="pattern1"></a> <h2>A Template For SELECT Programs</h2> <p>The first two query examples illustrate a kind of template that every SELECT program will follow. Basically, we have:</p> <p> <ol> <li>Initialize the <b>azColumnName[]</b> array for the callback.</li> <li>Open a cursor into the table to be queried.</li> <li>For each record in the table, do: <ol type="a"> <li>If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.</li> <li>Compute all columns for the current row of the result.</li> <li>Invoke the callback function for the current row of the result.</li> </ol> <li>Close the cursor.</li> </ol> </p> <p>This template will be expanded considerably as we consider additional complications such as joins, compound selects, using indices to speed the search, sorting, and aggregate functions with and without GROUP BY and HAVING clauses. But the same basic ideas will continue to apply.</p> <h2>UPDATE And DELETE Statements</h2> <p>The UPDATE and DELETE statements are coded using a template that is very similar to the SELECT statement template. The main difference, of course, is that the end action is to modify the database rather than invoke a callback function. Because it modifies the database it will also use transactions. Let's begin by looking at a DELETE statement:</p> <blockquote><pre> DELETE FROM examp WHERE two<50; </pre></blockquote> <p>This DELETE statement will remove every record from the "examp" table where the "two" column is less than 50. The code generated to do this is as follows:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 Transaction 1 0 1 Transaction 0 0 2 VerifyCookie 0 178 3 Integer 0 0 4 OpenRead 0 3 examp 5 Rewind 0 12 6 Column 0 1 7 Integer 50 0 50 8 Ge 1 11 9 Recno 0 0 10 ListWrite 0 0 11 Next 0 6 12 Close 0 0 13 ListRewind 0 0 14 Integer 0 0 15 OpenWrite 0 3 16 ListRead 0 20 17 NotExists 0 19 18 Delete 0 1 19 Goto 0 16 20 ListReset 0 0 21 Close 0 0 22 Commit 0 0 23 Halt 0 0 } puts { <p>Here is what the program must do. First it has to locate all of the records in the table "examp" that are to be deleted. This is done using a loop very much like the loop used in the SELECT examples above. Once all records have been located, then we can go back through and delete them one by one. Note that we cannot delete each record as soon as we find it. We have to locate all records first, then go back and delete them. This is because the SQLite database backend might change the scan order after a delete operation. And if the scan order changes in the middle of the scan, some records might be visited more than once and other records might not be visited at all.</p> <p>So the implemention of DELETE is really in two loops. The first loop (instructions 5 through 11) locates the records that are to be deleted and saves their keys onto a temporary list, and the second loop (instructions 16 through 19) uses the key list to delete the records one by one. </p> } Code { 0 Transaction 1 0 1 Transaction 0 0 2 VerifyCookie 0 178 3 Integer 0 0 4 OpenRead 0 3 examp } puts { <p>Instructions 0 though 4 are as in the INSERT example. They start transactions for the main and temporary databases, verify the database schema for the main database, and open a read cursor on the table "examp". Notice that the cursor is opened for reading, not writing. At this stage of the program we are only going to be scanning the table, not changing it. We will reopen the same table for writing later, at instruction 15.</p> } Code { 5 Rewind 0 12 } puts { <p>As in the SELECT example, the <a href="opcode.html#Rewind">Rewind</a> instruction rewinds the cursor to the beginning of the table, readying it for use in the loop body.</p> } Code { 6 Column 0 1 7 Integer 50 0 50 8 Ge 1 11 } puts { <p>The WHERE clause is implemented by instructions 6 through 8. The job of the where clause is to skip the ListWrite if the WHERE condition is false. To this end, it jumps ahead to the Next instruction if the "two" column (extracted by the Column instruction) is greater than or equal to 50.</p> <p>As before, the Column instruction uses cursor P1 and pushes the data record in column P2 (1, column "two") onto the stack. The Integer instruction pushes the value 50 onto the top of the stack. After these two instructions the stack looks like:</p> } stack {(integer) 50} \ {(record) current record for column "two" } puts { <p>The <a href="opcode.html#Ge">Ge</a> operator compares the top two elements on the stack, pops them, and then branches based on the result of the comparison. If the second element is >= the top element, then jump to address P2 (the Next instruction at the end of the loop). Because P1 is true, if either operand is NULL (and thus the result is NULL) then take the jump. If we don't jump, just advance to the next instruction.</p> } Code { 9 Recno 0 0 10 ListWrite 0 0 } puts { <p>The <a href="opcode.html#Recno">Recno</a> instruction pushes onto the stack an integer which is the first 4 bytes of the the key to the current entry in a sequential scan of the table pointed to by cursor P1. The <a href="opcode.html#ListWrite">ListWrite</a> instruction writes the integer on the top of the stack into a temporary storage list and pops the top element. This is the important work of this loop, to store the keys of the records to be deleted so we can delete them in the second loop. After this ListWrite instruction the stack is empty again.</p> } Code { 11 Next 0 6 12 Close 0 0 } puts { <p> The Next instruction increments the cursor to point to the next element in the table pointed to by cursor P0, and if it was successful branches to P2 (6, the beginning of the loop body). The Close instruction closes cursor P1. It doesn't affect the temporary storage list because it isn't associated with cursor P1; it is instead a global working list (which can be saved with ListPush).</p> } Code { 13 ListRewind 0 0 } puts { <p> The <a href="opcode.html#ListRewind">ListRewind</a> instruction rewinds the temporary storage list to the beginning. This prepares it for use in the second loop.</p> } Code { 14 Integer 0 0 15 OpenWrite 0 3 } puts { <p> As in the INSERT example, we push the database number P1 (0, the main database) onto the stack and use OpenWrite to open the cursor P1 on table P2 (base page 3, "examp") for modification.</p> } Code { 16 ListRead 0 20 17 NotExists 0 19 18 Delete 0 1 19 Goto 0 16 } puts { <p>This loop does the actual deleting. It is organized differently from the one in the UPDATE example. The ListRead instruction plays the role that the Next did in the INSERT loop, but because it jumps to P2 on failure, and Next jumps on success, we put it at the start of the loop instead of the end. This means that we have to put a Goto at the end of the loop to jump back to the the loop test at the beginning. So this loop has the form of a C while(){...} loop, while the loop in the INSERT example had the form of a do{...}while() loop. The Delete instruction fills the role that the callback function did in the preceding examples. </p> <p>The <a href="opcode.html#ListRead">ListRead</a> instruction reads an element from the temporary storage list and pushes it onto the stack. If this was successful, it continues to the next instruction. If this fails because the list is empty, it branches to P2, which is the instruction just after the loop. Afterwards the stack looks like:</p> } stack {(integer) key for current record} puts { <p>Notice the similarity between the ListRead and Next instructions. Both operations work according to this rule: </p> <blockquote> Push the next "thing" onto the stack and fall through OR jump to P2, depending on whether or not there is a next "thing" to push. </blockquote> <p>One difference between Next and ListRead is their idea of a "thing". The "things" for the Next instruction are records in a database file. "Things" for ListRead are integer keys in a list. Another difference is whether to jump or fall through if there is no next "thing". In this case, Next falls through, and ListRead jumps. Later on, we will see other looping instructions (NextIdx and SortNext) that operate using the same principle.</p> <p>The <a href="opcode.html#NotExists">NotExists</a> instruction pops the top stack element and uses it as an integer key. If a record with that key does not exist in table P1, then jump to P2. If a record does exist, then fall thru to the next instruction. In this case P2 takes us to the Goto at the end of the loop, which jumps back to the ListRead at the beginning. This could have been coded to have P2 be 16, the ListRead at the start of the loop, but the SQLite parser which generated this code didn't make that optimization.</p> <p>The <a href="opcode.html#Delete">Delete</a> does the work of this loop; it pops an integer key off the stack (placed there by the preceding ListRead) and deletes the record of cursor P1 that has that key. Because P2 is true, the row change counter is incremented.</p> <p>The <a href="opcode.html#Goto">Goto</a> jumps back to the beginning of the loop. This is the end of the loop.</p> } Code { 20 ListReset 0 0 21 Close 0 0 22 Commit 0 0 23 Halt 0 0 } puts { <p>This block of instruction cleans up the VDBE program. Three of these instructions aren't really required, but are generated by the SQLite parser from its code templates, which are designed to handle more complicated cases.</p> <p>The <a href="opcode.html#ListReset">ListReset</a> instruction empties the temporary storage list. This list is emptied automatically when the VDBE program terminates, so it isn't necessary in this case. The Close instruction closes the cursor P1. Again, this is done by the VDBE engine when it is finished running this program. The Commit ends the current transaction successfully, and causes all changes that occurred in this transaction to be saved to the database. The final Halt is also unneccessary, since it is added to every VDBE program when it is prepared to run.</p> <p>UPDATE statements work very much like DELETE statements except that instead of deleting the record they replace it with a new one. Consider this example: </p> <blockquote><pre> UPDATE examp SET one= '(' || one || ')' WHERE two < 50; </pre></blockquote> <p>Instead of deleting records where the "two" column is less than 50, this statement just puts the "one" column in parentheses The VDBE program to implement this statement follows:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 Transaction 1 0 1 Transaction 0 0 2 VerifyCookie 0 178 3 Integer 0 0 4 OpenRead 0 3 examp 5 Rewind 0 12 6 Column 0 1 7 Integer 50 0 50 8 Ge 1 11 9 Recno 0 0 10 ListWrite 0 0 11 Next 0 6 12 Close 0 0 13 Integer 0 0 14 OpenWrite 0 3 15 ListRewind 0 0 16 ListRead 0 28 17 Dup 0 0 18 NotExists 0 16 19 String 0 0 ( 20 Column 0 0 21 Concat 2 0 22 String 0 0 ) 23 Concat 2 0 24 Column 0 1 25 MakeRecord 2 0 26 PutIntKey 0 1 27 Goto 0 16 28 ListReset 0 0 29 Close 0 0 30 Commit 0 0 31 Halt 0 0 } puts { <p>This program is essentially the same as the DELETE program except that the body of the second loop has been replace by a sequence of instructions (at addresses 17 through 26) that update the record rather than delete it. Most of this instruction sequence should already be familiar to you, but there are a couple of minor twists so we will go over it briefly. Also note that the order of some of the instructions before and after the 2nd loop has changed. This is just the way the SQLite parser chose to output the code using a different template.</p> <p>As we enter the interior of the second loop (at instruction 17) the stack contains a single integer which is the key of the record we want to modify. We are going to need to use this key twice: once to fetch the old value of the record and a second time to write back the revised record. So the first instruction is a Dup to make a duplicate of the key on the top of the stack. The Dup instruction will duplicate any element of the stack, not just the top element. You specify which element to duplication using the P1 operand. When P1 is 0, the top of the stack is duplicated. When P1 is 1, the next element down on the stack duplication. And so forth.</p> <p>After duplicating the key, the next instruction, NotExists, pops the stack once and uses the value popped as a key to check the existence of a record in the database file. If there is no record for this key, it jumps back to the ListRead to get another key.</p> <p>Instructions 19 through 25 construct a new database record that will be used to replace the existing record. This is the same kind of code that we saw in the description of INSERT and will not be described further. After instruction 25 executes, the stack looks like this:</p> } stack {(record) new data record} {(integer) key} puts { <p>The PutIntKey instruction (also described during the discussion about INSERT) writes an entry into the database file whose data is the top of the stack and whose key is the next on the stack, and then pops the stack twice. The PutIntKey instruction will overwrite the data of an existing record with the same key, which is what we want here. Overwriting was not an issue with INSERT because with INSERT the key was generated by the NewRecno instruction which is guaranteed to provide a key that has not been used before.</p> } if 0 {<p>(By the way, since keys must all be unique and each key is a 32-bit integer, a single SQLite database table can have no more than 2<sup>32</sup> rows. Actually, the Key instruction starts to become very inefficient as you approach this upper bound, so it is best to keep the number of entries below 2<sup>31</sup> or so. Surely a couple billion records will be enough for most applications!)</p> } puts { <h2>CREATE and DROP</h2> <p>Using CREATE or DROP to create or destroy a table or index is really the same as doing an INSERT or DELETE from the special "sqlite_master" table, at least from the point of view of the VDBE. The sqlite_master table is a special table that is automatically created for every SQLite database. It looks like this:</p> <blockquote><pre> CREATE TABLE sqlite_master ( type TEXT, -- either "table" or "index" name TEXT, -- name of this table or index tbl_name TEXT, -- for indices: name of associated table sql TEXT -- SQL text of the original CREATE statement ) </pre></blockquote> <p>Every table (except the "sqlite_master" table itself) and every named index in an SQLite database has an entry in the sqlite_master table. You can query this table using a SELECT statement just like any other table. But you are not allowed to directly change the table using UPDATE, INSERT, or DELETE. Changes to sqlite_master have to occur using the CREATE and DROP commands because SQLite also has to update some of its internal data structures when tables and indices are added or destroyed.</p> <p>But from the point of view of the VDBE, a CREATE works pretty much like an INSERT and a DROP works like a DELETE. When the SQLite library opens to an existing database, the first thing it does is a SELECT to read the "sql" columns from all entries of the sqlite_master table. The "sql" column contains the complete SQL text of the CREATE statement that originally generated the index or table. This text is fed back into the SQLite parser and used to reconstruct the internal data structures describing the index or table.</p> <h2>Using Indexes To Speed Searching</h2> <p>In the example queries above, every row of the table being queried must be loaded off of the disk and examined, even if only a small percentage of the rows end up in the result. This can take a long time on a big table. To speed things up, SQLite can use an index.</p> <p>An SQLite file associates a key with some data. For an SQLite table, the database file is set up so that the key is an integer and the data is the information for one row of the table. Indices in SQLite reverse this arrangement. The index key is (some of) the information being stored and the index data is an integer. To access a table row that has some particular content, we first look up the content in the index table to find its integer index, then we use that integer to look up the complete record in the table.</p> <p>Note that SQLite uses b-trees, which are a sorted data structure, so indices can be used when the WHERE clause of the SELECT statement contains tests for equality or inequality. Queries like the following can use an index if it is available:</p> <blockquote><pre> SELECT * FROM examp WHERE two==50; SELECT * FROM examp WHERE two<50; SELECT * FROM examp WHERE two IN (50, 100); </pre></blockquote> <p>If there exists an index that maps the "two" column of the "examp" table into integers, then SQLite will use that index to find the integer keys of all rows in examp that have a value of 50 for column two, or all rows that are less than 50, etc. But the following queries cannot use the index:</p> <blockquote><pre> SELECT * FROM examp WHERE two%50 == 10; SELECT * FROM examp WHERE two&127 == 3; </pre></blockquote> <p>Note that the SQLite parser will not always generate code to use an index, even if it is possible to do so. The following queries will not currently use the index:</p> <blockquote><pre> SELECT * FROM examp WHERE two+10 == 50; SELECT * FROM examp WHERE two==50 OR two==100; </pre></blockquote> <p>To understand better how indices work, lets first look at how they are created. Let's go ahead and put an index on the two column of the examp table. We have:</p> <blockquote><pre> CREATE INDEX examp_idx1 ON examp(two); </pre></blockquote> <p>The VDBE code generated by the above statement looks like the following:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 Transaction 1 0 1 Transaction 0 0 2 VerifyCookie 0 178 3 Integer 0 0 4 OpenWrite 0 2 5 NewRecno 0 0 6 String 0 0 index 7 String 0 0 examp_idx1 8 String 0 0 examp 9 CreateIndex 0 0 ptr(0x791380) 10 Dup 0 0 11 Integer 0 0 12 OpenWrite 1 0 13 String 0 0 CREATE INDEX examp_idx1 ON examp(tw 14 MakeRecord 5 0 15 PutIntKey 0 0 16 Integer 0 0 17 OpenRead 2 3 examp 18 Rewind 2 24 19 Recno 2 0 20 Column 2 1 21 MakeIdxKey 1 0 n 22 IdxPut 1 0 indexed columns are not unique 23 Next 2 19 24 Close 2 0 25 Close 1 0 26 Integer 333 0 27 SetCookie 0 0 28 Close 0 0 29 Commit 0 0 30 Halt 0 0 } puts { <p>Remember that every table (except sqlite_master) and every named index has an entry in the sqlite_master table. Since we are creating a new index, we have to add a new entry to sqlite_master. This is handled by instructions 3 through 15. Adding an entry to sqlite_master works just like any other INSERT statement so we will not say anymore about it here. In this example, we want to focus on populating the new index with valid data, which happens on instructions 16 through 23.</p> } Code { 16 Integer 0 0 17 OpenRead 2 3 examp } puts { <p>The first thing that happens is that we open the table being indexed for reading. In order to construct an index for a table, we have to know what is in that table. The index has already been opened for writing using cursor 0 by instructions 3 and 4.</p> } Code { 18 Rewind 2 24 19 Recno 2 0 20 Column 2 1 21 MakeIdxKey 1 0 n 22 IdxPut 1 0 indexed columns are not unique 23 Next 2 19 } puts { <p>Instructions 18 through 23 implement a loop over every row of the table being indexed. For each table row, we first extract the integer key for that row using Recno in instruction 19, then get the value of the "two" column using Column in instruction 20. The <a href="opcode.html#MakeIdxKey">MakeIdxKey</a> instruction at 21 converts data from the "two" column (which is on the top of the stack) into a valid index key. For an index on a single column, this is basically a no-op. But if the P1 operand to MakeIdxKey had been greater than one multiple entries would have been popped from the stack and converted into a single index key. The <a href="opcode.html#IdxPut">IdxPut</a> instruction at 22 is what actually creates the index entry. IdxPut pops two elements from the stack. The top of the stack is used as a key to fetch an entry from the index table. Then the integer which was second on stack is added to the set of integers for that index and the new record is written back to the database file. Note that the same index entry can store multiple integers if there are two or more table entries with the same value for the two column. </p> <p>Now let's look at how this index will be used. Consider the following query:</p> <blockquote><pre> SELECT * FROM examp WHERE two==50; </pre></blockquote> <p>SQLite generates the following VDBE code to handle this query:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 one 1 ColumnName 1 0 two 2 Integer 0 0 3 OpenRead 0 3 examp 4 VerifyCookie 0 256 5 Integer 0 0 6 OpenRead 1 4 examp_idx1 7 Integer 50 0 50 8 MakeKey 1 0 n 9 MemStore 0 0 10 MoveTo 1 19 11 MemLoad 0 0 12 IdxGT 1 19 13 IdxRecno 1 0 14 MoveTo 0 0 15 Column 0 0 16 Column 0 1 17 Callback 2 0 18 Next 1 11 19 Close 0 0 20 Close 1 0 21 Halt 0 0 } puts { <p>The SELECT begins in a familiar fashion. First the column names are initialized and the table being queried is opened. Things become different beginning with instructions 5 and 6 where the index file is also opened. Instructions 7 and 8 make a key with the value of 50. The <a href="opcode.html#MemStore">MemStore</a> instruction at 9 stores the index key in VDBE memory location 0. The VDBE memory is used to avoid having to fetch a value from deep in the stack, which can be done, but makes the program harder to generate. The following instruction <a href="opcode.html#MoveTo">MoveTo</a> at address 10 pops the key off the stack and moves the index cursor to the first row of the index with that key. This initializes the cursor for use in the following loop.</p> <p>Instructions 11 through 18 implement a loop over all index records with the key that was fetched by instruction 8. All of the index records with this key will be contiguous in the index table, so we walk through them and fetch the corresponding table key from the index. This table key is then used to move the cursor to that row in the table. The rest of the loop is the same as the loop for the non-indexed SELECT query.</p> <p>The loop begins with the <a href="opcode.html#MemLoad">MemLoad</a> instruction at 11 which pushes a copy of the index key back onto the stack. The instruction <a href="opcode.html#IdxGT">IdxGT</a> at 12 compares the key to the key in the current index record pointed to by cursor P1. If the index key at the current cursor location is greater than the the index we are looking for, then jump out of the loop.</p> <p>The instruction <a href="opcode.html#IdxRecno">IdxRecno</a> at 13 pushes onto the stack the table record number from the index. The following MoveTo pops it and moves the table cursor to that row. The next 3 instructions select the column data the same way as in the non- indexed case. The Column instructions fetch the column data and the callback function is invoked. The final Next instruction advances the index cursor, not the table cursor, to the next row, and then branches back to the start of the loop if there are any index records left.</p> <p>Since the index is used to look up values in the table, it is important that the index and table be kept consistent. Now that there is an index on the examp table, we will have to update that index whenever data is inserted, deleted, or changed in the examp table. Remember the first example above where we were able to insert a new row into the "examp" table using 12 VDBE instructions. Now that this table is indexed, 19 instructions are required. The SQL statement is this:</p> <blockquote><pre> INSERT INTO examp VALUES('Hello, World!',99); </pre></blockquote> <p>And the generated code looks like this:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 Transaction 1 0 1 Transaction 0 0 2 VerifyCookie 0 256 3 Integer 0 0 4 OpenWrite 0 3 examp 5 Integer 0 0 6 OpenWrite 1 4 examp_idx1 7 NewRecno 0 0 8 String 0 0 Hello, World! 9 Integer 99 0 99 10 Dup 2 1 11 Dup 1 1 12 MakeIdxKey 1 0 n 13 IdxPut 1 0 14 MakeRecord 2 0 15 PutIntKey 0 1 16 Close 0 0 17 Close 1 0 18 Commit 0 0 19 Halt 0 0 } puts { <p>At this point, you should understand the VDBE well enough to figure out on your own how the above program works. So we will not discuss it further in this text.</p> <h2>Joins</h2> <p>In a join, two or more tables are combined to generate a single result. The result table consists of every possible combination of rows from the tables being joined. The easiest and most natural way to implement this is with nested loops.</p> <p>Recall the query template discussed above where there was a single loop that searched through every record of the table. In a join we have basically the same thing except that there are nested loops. For example, to join two tables, the query template might look something like this:</p> <p> <ol> <li>Initialize the <b>azColumnName[]</b> array for the callback.</li> <li>Open two cursors, one to each of the two tables being queried.</li> <li>For each record in the first table, do: <ol type="a"> <li>For each record in the second table do: <ol type="i"> <li>If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.</li> <li>Compute all columns for the current row of the result.</li> <li>Invoke the callback function for the current row of the result.</li> </ol></li> </ol> <li>Close both cursors.</li> </ol> </p> <p>This template will work, but it is likely to be slow since we are now dealing with an O(N<sup>2</sup>) loop. But it often works out that the WHERE clause can be factored into terms and that one or more of those terms will involve only columns in the first table. When this happens, we can factor part of the WHERE clause test out of the inner loop and gain a lot of efficiency. So a better template would be something like this:</p> <p> <ol> <li>Initialize the <b>azColumnName[]</b> array for the callback.</li> <li>Open two cursors, one to each of the two tables being queried.</li> <li>For each record in the first table, do: <ol type="a"> <li>Evaluate terms of the WHERE clause that only involve columns from the first table. If any term is false (meaning that the whole WHERE clause must be false) then skip the rest of this loop and continue to the next record.</li> <li>For each record in the second table do: <ol type="i"> <li>If the WHERE clause evaluates to FALSE, then skip the steps that follow and continue to the next record.</li> <li>Compute all columns for the current row of the result.</li> <li>Invoke the callback function for the current row of the result.</li> </ol></li> </ol> <li>Close both cursors.</li> </ol> </p> <p>Additional speed-up can occur if an index can be used to speed the search of either or the two loops.</p> <p>SQLite always constructs the loops in the same order as the tables appear in the FROM clause of the SELECT statement. The left-most table becomes the outer loop and the right-most table becomes the inner loop. It is possible, in theory, to reorder the loops in some circumstances to speed the evaluation of the join. But SQLite does not attempt this optimization.</p> <p>You can see how SQLite constructs nested loops in the following example:</p> <blockquote><pre> CREATE TABLE examp2(three int, four int); SELECT * FROM examp, examp2 WHERE two<50 AND four==two; </pre></blockquote> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 examp.one 1 ColumnName 1 0 examp.two 2 ColumnName 2 0 examp2.three 3 ColumnName 3 0 examp2.four 4 Integer 0 0 5 OpenRead 0 3 examp 6 VerifyCookie 0 909 7 Integer 0 0 8 OpenRead 1 5 examp2 9 Rewind 0 24 10 Column 0 1 11 Integer 50 0 50 12 Ge 1 23 13 Rewind 1 23 14 Column 1 1 15 Column 0 1 16 Ne 1 22 17 Column 0 0 18 Column 0 1 19 Column 1 0 20 Column 1 1 21 Callback 4 0 22 Next 1 14 23 Next 0 10 24 Close 0 0 25 Close 1 0 26 Halt 0 0 } puts { <p>The outer loop over table examp is implement by instructions 7 through 23. The inner loop is instructions 13 through 22. Notice that the "two<50" term of the WHERE expression involves only columns from the first table and can be factored out of the inner loop. SQLite does this and implements the "two<50" test in instructions 10 through 12. The "four==two" test is implement by instructions 14 through 16 in the inner loop.</p> <p>SQLite does not impose any arbitrary limits on the tables in a join. It also allows a table to be joined with itself.</p> <h2>The ORDER BY clause</h2> <p>For historical reasons, and for efficiency, all sorting is currently done in memory.</p> <p>SQLite implements the ORDER BY clause using a special set of instructions to control an object called a sorter. In the inner-most loop of the query, where there would normally be a Callback instruction, instead a record is constructed that contains both callback parameters and a key. This record is added to the sorter (in a linked list). After the query loop finishes, the list of records is sorted and this list is walked. For each record on the list, the callback is invoked. Finally, the sorter is closed and memory is deallocated.</p> <p>We can see the process in action in the following query:</p> <blockquote><pre> SELECT * FROM examp ORDER BY one DESC, two; </pre></blockquote> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 one 1 ColumnName 1 0 two 2 Integer 0 0 3 OpenRead 0 3 examp 4 VerifyCookie 0 909 5 Rewind 0 14 6 Column 0 0 7 Column 0 1 8 SortMakeRec 2 0 9 Column 0 0 10 Column 0 1 11 SortMakeKey 2 0 D+ 12 SortPut 0 0 13 Next 0 6 14 Close 0 0 15 Sort 0 0 16 SortNext 0 19 17 SortCallback 2 0 18 Goto 0 16 19 SortReset 0 0 20 Halt 0 0 } puts { <p>There is only one sorter object, so there are no instructions to open or close it. It is opened automatically when needed, and it is closed when the VDBE program halts.</p> <p>The query loop is built from instructions 5 through 13. Instructions 6 through 8 build a record that contains the azData[] values for a single invocation of the callback. A sort key is generated by instructions 9 through 11. Instruction 12 combines the invocation record and the sort key into a single entry and puts that entry on the sort list.<p> <p>The P3 argument of instruction 11 is of particular interest. The sort key is formed by prepending one character from P3 to each string and concatenating all the strings. The sort comparison function will look at this character to determine whether the sort order is ascending or descending, and whether to sort as a string or number. In this example, the first column should be sorted as a string in descending order so its prefix is "D" and the second column should sorted numerically in ascending order so its prefix is "+". Ascending string sorting uses "A", and descending numeric sorting uses "-".</p> <p>After the query loop ends, the table being queried is closed at instruction 14. This is done early in order to allow other processes or threads to access that table, if desired. The list of records that was built up inside the query loop is sorted by the instruction at 15. Instructions 16 through 18 walk through the record list (which is now in sorted order) and invoke the callback once for each record. Finally, the sorter is closed at instruction 19.</p> <h2>Aggregate Functions And The GROUP BY and HAVING Clauses</h2> <p>To compute aggregate functions, the VDBE implements a special data structure and instructions for controlling that data structure. The data structure is an unordered set of buckets, where each bucket has a key and one or more memory locations. Within the query loop, the GROUP BY clause is used to construct a key and the bucket with that key is brought into focus. A new bucket is created with the key if one did not previously exist. Once the bucket is in focus, the memory locations of the bucket are used to accumulate the values of the various aggregate functions. After the query loop terminates, each bucket is visited once to generate a single row of the results.</p> <p>An example will help to clarify this concept. Consider the following query:</p> <blockquote><pre> SELECT three, min(three+four)+avg(four) FROM examp2 GROUP BY three; </pre></blockquote> <p>The VDBE code generated for this query is as follows:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 three 1 ColumnName 1 0 min(three+four)+avg(four) 2 AggReset 0 3 3 AggInit 0 1 ptr(0x7903a0) 4 AggInit 0 2 ptr(0x790700) 5 Integer 0 0 6 OpenRead 0 5 examp2 7 VerifyCookie 0 909 8 Rewind 0 23 9 Column 0 0 10 MakeKey 1 0 n 11 AggFocus 0 14 12 Column 0 0 13 AggSet 0 0 14 Column 0 0 15 Column 0 1 16 Add 0 0 17 Integer 1 0 18 AggFunc 0 1 ptr(0x7903a0) 19 Column 0 1 20 Integer 2 0 21 AggFunc 0 1 ptr(0x790700) 22 Next 0 9 23 Close 0 0 24 AggNext 0 31 25 AggGet 0 0 26 AggGet 0 1 27 AggGet 0 2 28 Add 0 0 29 Callback 2 0 30 Goto 0 24 31 Noop 0 0 32 Halt 0 0 } puts { <p>The first instruction of interest is the <a href="opcode.html#AggReset">AggReset</a> at 2. The AggReset instruction initializes the set of buckets to be the empty set and specifies the number of memory slots available in each bucket as P2. In this example, each bucket will hold 3 memory slots. It is not obvious, but if you look closely at the rest of the program you can figure out what each of these slots is intended for.</p> <blockquote><table border="2" cellpadding="5"> <tr><th>Memory Slot</th><th>Intended Use Of This Memory Slot</th></tr> <tr><td>0</td><td>The "three" column -- the key to the bucket</td></tr> <tr><td>1</td><td>The minimum "three+four" value</td></tr> <tr><td>2</td><td>The sum of all "four" values. This is used to compute "avg(four)".</td></tr> </table></blockquote> <p>The query loop is implemented by instructions 8 through 22. The aggregate key specified by the GROUP BY clause is computed by instructions 9 and 10. Instruction 11 causes the appropriate bucket to come into focus. If a bucket with the given key does not already exists, a new bucket is created and control falls through to instructions 12 and 13 which initialize the bucket. If the bucket does already exist, then a jump is made to instruction 14. The values of aggregate functions are updated by the instructions between 11 and 21. Instructions 14 through 18 update memory slot 1 to hold the next value "min(three+four)". Then the sum of the "four" column is updated by instructions 19 through 21.</p> <p>After the query loop is finished, the table "examp2" is closed at instruction 23 so that its lock will be released and it can be used by other threads or processes. The next step is to loop over all aggregate buckets and output one row of the result for each bucket. This is done by the loop at instructions 24 through 30. The AggNext instruction at 24 brings the next bucket into focus, or jumps to the end of the loop if all buckets have been examined already. The 3 columns of the result are fetched from the aggregator bucket in order at instructions 25 through 27. Finally, the callback is invoked at instruction 29.</p> <p>In summary then, any query with aggregate functions is implemented by two loops. The first loop scans the input table and computes aggregate information into buckets and the second loop scans through all the buckets to compute the final result.</p> <p>The realization that an aggregate query is really two consequtive loops makes it much easier to understand the difference between a WHERE clause and a HAVING clause in SQL query statement. The WHERE clause is a restriction on the first loop and the HAVING clause is a restriction on the second loop. You can see this by adding both a WHERE and a HAVING clause to our example query:</p> <blockquote><pre> SELECT three, min(three+four)+avg(four) FROM examp2 WHERE three>four GROUP BY three HAVING avg(four)<10; </pre></blockquote> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 ColumnName 0 0 three 1 ColumnName 1 0 min(three+four)+avg(four) 2 AggReset 0 3 3 AggInit 0 1 ptr(0x7903a0) 4 AggInit 0 2 ptr(0x790700) 5 Integer 0 0 6 OpenRead 0 5 examp2 7 VerifyCookie 0 909 8 Rewind 0 26 9 Column 0 0 10 Column 0 1 11 Le 1 25 12 Column 0 0 13 MakeKey 1 0 n 14 AggFocus 0 17 15 Column 0 0 16 AggSet 0 0 17 Column 0 0 18 Column 0 1 19 Add 0 0 20 Integer 1 0 21 AggFunc 0 1 ptr(0x7903a0) 22 Column 0 1 23 Integer 2 0 24 AggFunc 0 1 ptr(0x790700) 25 Next 0 9 26 Close 0 0 27 AggNext 0 37 28 AggGet 0 2 29 Integer 10 0 10 30 Ge 1 27 31 AggGet 0 0 32 AggGet 0 1 33 AggGet 0 2 34 Add 0 0 35 Callback 2 0 36 Goto 0 27 37 Noop 0 0 38 Halt 0 0 } puts { <p>The code generated in this last example is the same as the previous except for the addition of two conditional jumps used to implement the extra WHERE and HAVING clauses. The WHERE clause is implemented by instructions 9 through 11 in the query loop. The HAVING clause is implemented by instruction 28 through 30 in the output loop.</p> <h2>Using SELECT Statements As Terms In An Expression</h2> <p>The very name "Structured Query Language" tells us that SQL should support nested queries. And, in fact, two different kinds of nesting are supported. Any SELECT statement that returns a single-row, single-column result can be used as a term in an expression of another SELECT statement. And, a SELECT statement that returns a single-column, multi-row result can be used as the right-hand operand of the IN and NOT IN operators. We will begin this section with an example of the first kind of nesting, where a single-row, single-column SELECT is used as a term in an expression of another SELECT. Here is our example:</p> <blockquote><pre> SELECT * FROM examp WHERE two!=(SELECT three FROM examp2 WHERE four=5); </pre></blockquote> <p>The way SQLite deals with this is to first run the inner SELECT (the one against examp2) and store its result in a private memory cell. SQLite then substitutes the value of this private memory cell for the inner SELECT when it evaluates the outer SELECT. The code looks like this:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 String 0 0 1 MemStore 0 1 2 Integer 0 0 3 OpenRead 1 5 examp2 4 VerifyCookie 0 909 5 Rewind 1 13 6 Column 1 1 7 Integer 5 0 5 8 Ne 1 12 9 Column 1 0 10 MemStore 0 1 11 Goto 0 13 12 Next 1 6 13 Close 1 0 14 ColumnName 0 0 one 15 ColumnName 1 0 two 16 Integer 0 0 17 OpenRead 0 3 examp 18 Rewind 0 26 19 Column 0 1 20 MemLoad 0 0 21 Eq 1 25 22 Column 0 0 23 Column 0 1 24 Callback 2 0 25 Next 0 19 26 Close 0 0 27 Halt 0 0 } puts { <p>The private memory cell is initialized to NULL by the first two instructions. Instructions 2 through 13 implement the inner SELECT statement against the examp2 table. Notice that instead of sending the result to a callback or storing the result on a sorter, the result of the query is pushed into the memory cell by instruction 10 and the loop is abandoned by the jump at instruction 11. The jump at instruction at 11 is vestigial and never executes.</p> <p>The outer SELECT is implemented by instructions 14 through 25. In particular, the WHERE clause that contains the nested select is implemented by instructions 19 through 21. You can see that the result of the inner select is loaded onto the stack by instruction 20 and used by the conditional jump at 21.</p> <p>When the result of a sub-select is a scalar, a single private memory cell can be used, as shown in the previous example. But when the result of a sub-select is a vector, such as when the sub-select is the right-hand operand of IN or NOT IN, a different approach is needed. In this case, the result of the sub-select is stored in a transient table and the contents of that table are tested using the Found or NotFound operators. Consider this example:</p> <blockquote><pre> SELECT * FROM examp WHERE two IN (SELECT three FROM examp2); </pre></blockquote> <p>The code generated to implement this last query is as follows:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 OpenTemp 1 1 1 Integer 0 0 2 OpenRead 2 5 examp2 3 VerifyCookie 0 909 4 Rewind 2 10 5 Column 2 0 6 IsNull -1 9 7 String 0 0 8 PutStrKey 1 0 9 Next 2 5 10 Close 2 0 11 ColumnName 0 0 one 12 ColumnName 1 0 two 13 Integer 0 0 14 OpenRead 0 3 examp 15 Rewind 0 25 16 Column 0 1 17 NotNull -1 20 18 Pop 1 0 19 Goto 0 24 20 NotFound 1 24 21 Column 0 0 22 Column 0 1 23 Callback 2 0 24 Next 0 16 25 Close 0 0 26 Halt 0 0 } puts { <p>The transient table in which the results of the inner SELECT are stored is created by the <a href="opcode.html#OpenTemp">OpenTemp</a> instruction at 0. This opcode is used for tables that exist for the duration of a single SQL statement only. The transient cursor is always opened read/write even if the main database is read-only. The transient table is deleted automatically when the cursor is closed. The P2 value of 1 means the cursor points to a BTree index, which has no data but can have an arbitrary key.</p> <p>The inner SELECT statement is implemented by instructions 1 through 10. All this code does is make an entry in the temporary table for each row of the examp2 table with a non-NULL value for the "three" column. The key for each temporary table entry is the "three" column of examp2 and the data is an empty string since it is never used.</p> <p>The outer SELECT is implemented by instructions 11 through 25. In particular, the WHERE clause containing the IN operator is implemented by instructions at 16, 17, and 20. Instruction 16 pushes the value of the "two" column for the current row onto the stack and instruction 17 checks to see that it is non-NULL. If this is successful, execution jumps to 20, where it tests to see if top of the stack matches any key in the temporary table. The rest of the code is the same as what has been shown before.</p> <h2>Compound SELECT Statements</h2> <p>SQLite also allows two or more SELECT statements to be joined as peers using operators UNION, UNION ALL, INTERSECT, and EXCEPT. These compound select statements are implemented using transient tables. The implementation is slightly different for each operator, but the basic ideas are the same. For an example we will use the EXCEPT operator.</p> <blockquote><pre> SELECT two FROM examp EXCEPT SELECT four FROM examp2; </pre></blockquote> <p>The result of this last example should be every unique value of the "two" column in the examp table, except any value that is in the "four" column of examp2 is removed. The code to implement this query is as follows:</p> } Code { addr opcode p1 p2 p3 ---- ------------ ----- ----- ----------------------------------- 0 OpenTemp 0 1 1 KeyAsData 0 1 2 Integer 0 0 3 OpenRead 1 3 examp 4 VerifyCookie 0 909 5 Rewind 1 11 6 Column 1 1 7 MakeRecord 1 0 8 String 0 0 9 PutStrKey 0 0 10 Next 1 6 11 Close 1 0 12 Integer 0 0 13 OpenRead 2 5 examp2 14 Rewind 2 20 15 Column 2 1 16 MakeRecord 1 0 17 NotFound 0 19 18 Delete 0 0 19 Next 2 15 20 Close 2 0 21 ColumnName 0 0 four 22 Rewind 0 26 23 Column 0 0 24 Callback 1 0 25 Next 0 23 26 Close 0 0 27 Halt 0 0 } puts { <p>The transient table in which the result is built is created by instruction 0. Three loops then follow. The loop at instructions 5 through 10 implements the first SELECT statement. The second SELECT statement is implemented by the loop at instructions 14 through 19. Finally, a loop at instructions 22 through 25 reads the transient table and invokes the callback once for each row in the result.</p> <p>Instruction 1 is of particular importance in this example. Normally, the Column instruction extracts the value of a column from a larger record in the data of an SQLite file entry. Instruction 1 sets a flag on the transient table so that Column will instead treat the key of the SQLite file entry as if it were data and extract column information from the key.</p> <p>Here is what is going to happen: The first SELECT statement will construct rows of the result and save each row as the key of an entry in the transient table. The data for each entry in the transient table is a never used so we fill it in with an empty string. The second SELECT statement also constructs rows, but the rows constructed by the second SELECT are removed from the transient table. That is why we want the rows to be stored in the key of the SQLite file instead of in the data -- so they can be easily located and deleted.</p> <p>Let's look more closely at what is happening here. The first SELECT is implemented by the loop at instructions 5 through 10. Instruction 5 intializes the loop by rewinding its cursor. Instruction 6 extracts the value of the "two" column from "examp" and instruction 7 converts this into a row. Instruction 8 pushes an empty string onto the stack. Finally, instruction 9 writes the row into the temporary table. But remember, the PutStrKey opcode uses the top of the stack as the record data and the next on stack as the key. For an INSERT statement, the row generated by the MakeRecord opcode is the record data and the record key is an integer created by the NewRecno opcode. But here the roles are reversed and the row created by MakeRecord is the record key and the record data is just an empty string.</p> <p>The second SELECT is implemented by instructions 14 through 19. Instruction 14 intializes the loop by rewinding its cursor. A new result row is created from the "four" column of table "examp2" by instructions 15 and 16. But instead of using PutStrKey to write this new row into the temporary table, we instead call Delete to remove it from the temporary table if it exists.</p> <p>The result of the compound select is sent to the callback routine by the loop at instructions 22 through 25. There is nothing new or remarkable about this loop, except for the fact that the Column instruction at 23 will be extracting a column out of the record key rather than the record data.</p> <h2>Summary</h2> <p>This article has reviewed all of the major techniques used by SQLite's VDBE to implement SQL statements. What has not been shown is that most of these techniques can be used in combination to generate code for an appropriately complex query statement. For example, we have shown how sorting is accomplished on a simple query and we have shown how to implement a compound query. But we did not give an example of sorting in a compound query. This is because sorting a compound query does not introduce any new concepts: it merely combines two previous ideas (sorting and compounding) in the same VDBE program.</p> <p>For additional information on how the SQLite library functions, the reader is directed to look at the SQLite source code directly. If you understand the material in this article, you should not have much difficulty in following the sources. Serious students of the internals of SQLite will probably also what to make a careful study of the VDBE opcodes as documented <a href="opcode.html">here</a>. Most of the opcode documentation is extracted from comments in the source code using a script so you can also get information about the various opcodes directly from the <b>vdbe.c</b> source file. If you have successfully read this far, you should have little difficulty understanding the rest.</p> <p>If you find errors in either the documentation or the code, feel free to fix them and/or contact the author at <a href="mailto:drh@hwaci.com">drh@hwaci.com</a>. Your bug fixes or suggestions are always welcomed.</p> } </tcl> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 | <title>SQLite Version 3 Overview</title> <h2>SQLite Version 3 Overview</h2> <p> SQLite version 3.0 introduces important changes to the library, including: </p> <ul> <li>A more compact format for database files.</li> <li>Manifest typing and BLOB support.</li> <li>Support for both UTF-8 and UTF-16 text.</li> <li>User-defined text collating sequences.</li> <li>64-bit ROWIDs.</li> <li>Improved Concurrency.</li> </ul> <p> This document is a quick introduction to the changes for SQLite 3.0 for users who are already familiar with SQLite version 2.8. </p> <h3>Naming Changes</h3> <p> SQLite version 2.8 will continue to be supported with bug fixes for the foreseeable future. In order to allow SQLite version 2.8 and SQLite version 3.0 to peacefully coexist, the names of key files and APIs in SQLite version 3.0 have been changed to include the character "3". For example, the include file used by C programs has been changed from "sqlite.h" to "sqlite3.h". And the name of the shell program used to interact with databases has been changed from "sqlite.exe" to "sqlite3.exe". With these changes, it is possible to have both SQLite 2.8 and SQLite 3.0 installed on the same system at the same time. And it is possible for the same C program to link against both SQLite 2.8 and SQLite 3.0 at the same time and to use both libraries at the same time. </p> <h3>New File Format</h3> <p> The format used by SQLite database files has been completely revised. The old version 2.1 format and the new 3.0 format are incompatible with one another. Version 2.8 of SQLite will not read a version 3.0 database files and version 3.0 of SQLite will not read a version 2.8 database file. </p> <p> To convert an SQLite 2.8 database into an SQLite 3.0 database, have ready the command-line shells for both version 2.8 and 3.0. Then enter a command like the following: </p> <blockquote><pre> sqlite OLD.DB .dump | sqlite3 NEW.DB </pre></blockquote> <p> The new database file format uses B+trees for tables. In a B+tree, all data is stored in the leaves of the tree instead of in both the leaves and the intermediate branch nodes. The use of B+trees for tables allows for better scalability and the storage of larger data fields without the use of overflow pages. Traditional B-trees are still used for indices.</p> <p> The new file format also supports variable pages sizes between 512 and 32768 bytes. The size of a page is stored in the file header so the same library can read databases with different pages sizes, in theory, though this feature has not yet been implemented in practice. </p> <p> The new file format omits unused fields from its disk images. For example, indices use only the key part of a B-tree record and not the data. So for indices, the field that records the length of the data is omitted. Integer values such as the length of key and data are stored using a variable-length encoding so that only one or two bytes are required to store the most common cases but up to 64-bits of information can be encoded if needed. Integer and floating point data is stored on the disk in binary rather than being converted into ASCII as in SQLite version 2.8. These changes taken together result in database files that are typically 25% to 35% smaller than the equivalent files in SQLite version 2.8. </p> <p> Details of the low-level B-tree format used in SQLite version 3.0 can be found in header comments to the <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/btree.c">btree.c</a> source file. </p> <h3>Manifest Typing and BLOB Support</h3> <p> SQLite version 2.8 will deal with data in various formats internally, but when writing to the disk or interacting through its API, SQLite 2.8 always converts data into ASCII text. SQLite 3.0, in contrast, exposes its internal data representations to the user and stores binary representations to disk when appropriate. The exposing of non-ASCII representations was added in order to support BLOBs. </p> <p> SQLite version 2.8 had the feature that any type of data could be stored in any table column regardless of the declared type of that column. This feature is retained in version 3.0, though in a slightly modified form. Each table column will store any type of data, though columns have an affinity for the format of data defined by their declared datatype. When data is inserted into a column, that column will make at attempt to convert the data format into the columns declared type. All SQL database engines do this. The difference is that SQLite 3.0 will still store the data even if a format conversion is not possible. </p> <p> For example, if you have a table column declared to be of type "INTEGER" and you try to insert a string, the column will look at the text string and see if it looks like a number. If the string does look like a number it is converted into a number and into an integer if the number does not have a fractional part, and stored that way. But if the string is not a well-formed number it is still stored as a string. A column with a type of "TEXT" tries to convert numbers into an ASCII-Text representation before storing them. But BLOBs are stored in TEXT columns as BLOBs because you cannot in general convert a BLOB into text. </p> <p> In most other SQL database engines the datatype is associated with the table column that holds the data - with the data container. In SQLite 3.0, the datatype is associated with the data itself, not with its container. <a href="http://www.paulgraham.com/">Paul Graham</a> in his book <a href="http://www.paulgraham.com/acl.html"><i>ANSI Common Lisp</i></a> calls this property "Manifest Typing". Other writers have other definitions for the term "manifest typing", so beware of confusion. But by whatever name, that is the datatype model supported by SQLite 3.0. </p> <p> Additional information about datatypes in SQLite version 3.0 is available <a href="datatype3.html">separately</a>. </p> <h3>Support for UTF-8 and UTF-16</h3> <p> The new API for SQLite 3.0 contains routines that accept text as both UTF-8 and UTF-16 in the native byte order of the host machine. Each database file manages text as either UTF-8, UTF-16BE (big-endian), or UTF-16LE (little-endian). Internally and in the disk file, the same text representation is used everywhere. If the text representation specified by the database file (in the file header) does not match the text representation required by the interface routines, then text is converted on-the-fly. Constantly converting text from one representation to another can be computationally expensive, so it is suggested that programmers choose a single representation and stick with it throughout their application. </p> <p> In the current implementation of SQLite, the SQL parser only works with UTF-8 text. So if you supply UTF-16 text it will be converted. This is just an implementation issue and there is nothing to prevent future versions of SQLite from parsing UTF-16 encoded SQL natively. </p> <p> When creating new user-defined SQL functions and collating sequences, each function or collating sequence can specify it if works with UTF-8, UTF-16be, or UTF-16le. Separate implementations can be registered for each encoding. If an SQL function or collating sequences is required but a version for the current text encoding is not available, then the text is automatically converted. As before, this conversion takes computation time, so programmers are advised to pick a single encoding and stick with it in order to minimize the amount of unnecessary format juggling. </p> <p> SQLite is not particular about the text it receives and is more than happy to process text strings that are not normalized or even well-formed UTF-8 or UTF-16. Thus, programmers who want to store IS08859 data can do so using the UTF-8 interfaces. As long as no attempts are made to use a UTF-16 collating sequence or SQL function, the byte sequence of the text will not be modified in any way. </p> <h3>User-defined Collating Sequences</h3> <p> A collating sequence is just a defined order for text. When SQLite 3.0 sorts (or uses a comparison operator like "<" or ">=") the sort order is first determined by the data type. </p> <ul> <li>NULLs sort first</li> <li>Numeric values sort next in numerical order</li> <li>Text values come after numerics</li> <li>BLOBs sort last</li> </ul> <p> Collating sequences are used for comparing two text strings. The collating sequence does not change the ordering of NULLs, numbers, or BLOBs, only text. </p> <p> A collating sequence is implemented as a function that takes the two strings being compared as inputs and returns negative, zero, or positive if the first string is less than, equal to, or greater than the second. SQLite 3.0 comes with a single built-in collating sequence named "BINARY" which is implemented using the memcmp() routine from the standard C library. The BINARY collating sequence works well for English text. For other languages or locales, alternative collating sequences may be preferred. </p> <p> The decision of which collating sequence to use is controlled by the COLLATE clause in SQL. A COLLATE clause can occur on a table definition, to define a default collating sequence to a table column, or on field of an index, or in the ORDER BY clause of a SELECT statement. Planned enhancements to SQLite are to include standard CAST() syntax to allow the collating sequence of an expression to be defined. </p> <h3>64-bit ROWIDs</h3> <p> Every row of a table has a unique rowid. If the table defines a column with the type "INTEGER PRIMARY KEY" then that column becomes an alias for the rowid. But with or without an INTEGER PRIMARY KEY column, every row still has a rowid. </p> <p> In SQLite version 3.0, the rowid is a 64-bit signed integer. This is an expansion of SQLite version 2.8 which only permitted rowids of 32-bits. </p> <p> To minimize storage space, the 64-bit rowid is stored as a variable length integer. Rowids between 0 and 127 use only a single byte. Rowids between 0 and 16383 use just 2 bytes. Up to 2097152 uses three bytes. And so forth. Negative rowids are allowed but they always use nine bytes of storage and so their use is discouraged. When rowids are generated automatically by SQLite, they will always be non-negative. </p> <h3>Improved Concurrency</h3> <p> SQLite version 2.8 allowed multiple simultaneous readers or a single writer but not both. SQLite version 3.0 allows one process to begin writing the database while other processes continue to read. The writer must still obtain an exclusive lock on the database for a brief interval in order to commit its changes, but the exclusive lock is no longer required for the entire write operation. A <a href="lockingv3.html">more detailed report</a> on the locking behavior of SQLite version 3.0 is available separately. </p> <p> A limited form of table-level locking is now also available in SQLite. If each table is stored in a separate database file, those separate files can be attached to the main database (using the ATTACH command) and the combined databases will function as one. But locks will only be acquired on individual files as needed. So if you redefine "database" to mean two or more database files, then it is entirely possible for two processes to be writing to the same database at the same time. To further support this capability, commits of transactions involving two or more ATTACHed database are now atomic. </p> <h3>Credits</h3> <p> SQLite version 3.0 is made possible in part by AOL developers supporting and embracing great Open-Source Software. </p> |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 | <title>Appropriate Uses For SQLite</title> <h2>Appropriate Uses For SQLite</h2> <p> SQLite is different from most other SQL database engines in that its primary design goal is to be simple: </p> <ul> <li>Simple to administer</li> <li>Simple to operate</li> <li>Simple to embed in a larger program</li> <li>Simple to maintain and customize</li> </ul> <p> Many people like SQLite because it is small and fast. But those qualities are just happy accidents. Users also find that SQLite is very reliable. Reliability is a consequence of simplicity. With less complication, there is less to go wrong. So, yes, SQLite is small, fast, and reliable, but first and foremost, SQLite strives to be simple. </p> <p> Simplicity in a database engine can be either a strength or a weakness, depending on what you are trying to do. In order to achieve simplicity, SQLite has had to sacrifice other characteristics that some people find useful, such as high concurrency, fine-grained access control, a rich set of built-in functions, stored procedures, esoteric SQL language features, XML and/or Java extensions, tera- or peta-byte scalability, and so forth. If you need some of these features and do not mind the added complexity that they bring, then SQLite is probably not the database for you. SQLite is not intended to be an enterprise database engine. It not designed to compete with Oracle or PostgreSQL. </p> <p> The basic rule of thumb for when it is appropriate to use SQLite is this: Use SQLite in situations where simplicity of administration, implementation, and maintenance are more important than the countless complex features that enterprise database engines provide. As it turns out, situations where simplicity is the better choice are more common than many people realize. </p> <h2>Situations Where SQLite Works Well</h2> <ul> <li><p><b>Websites</b></p> <p>SQLite usually will work great as the database engine for low to medium traffic websites (which is to say, 99.9% of all websites). The amount of web traffic that SQLite can handle depends, of course, on how heavily the website uses its database. Generally speaking, any site that gets fewer than a 100000 hits/day should work fine with SQLite. The 100000 hits/day figure is a conservative estimate, not a hard upper bound. SQLite has been demonstrated to work with 10 times that amount of traffic.</p> </li> <li><p><b>Embedded devices and applications</b></p> <p>Because an SQLite database requires little or no administration, SQLite is a good choice for devices or services that must work unattended and without human support. SQLite is a good fit for use in cellphones, PDAs, set-top boxes, and/or appliances. It also works well as an embedded database in downloadable consumer applications. </p> </li> <li><p><b>Application File Format</b></p> <p> SQLite has been used with great success as the on-disk file format for desktop applications such as financial analysis tools, CAD packages, record keeping programs, and so forth. The traditional File/Open operation does an sqlite3_open() and executes a BEGIN TRANSACTION to get exclusive access to the content. File/Save does a COMMIT followed by another BEGIN TRANSACTION. The use of transactions guarantees that updates to the application file are atomic, durable, isolated, and consistent. </p> <p> Temporary triggers can be added to the database to record all changes into a (temporary) undo/redo log table. These changes can then be played back when the user presses the Undo and Redo buttons. Using this technique, a unlimited depth undo/redo implementation can be written in surprising little code. </p> </li> <li><p><b>Replacement for <i>ad hoc</i> disk files</b></p> <p>Many programs use fopen(), fread(), and fwrite() to create and manage files of data in home-grown formats. SQLite works particularly well as a replacement for these <i>ad hoc</i> data files.</p> </li> <li><p><b>Internal or temporary databases</b></p> <p> For programs that have a lot of data that must be sifted and sorted in diverse ways, it is often easier and quicker to load the data into an in-memory SQLite database and use queries with joins and ORDER BY clauses to extract the data in the form and order needed rather than to try to code the same operations manually. Using an SQL database internally in this way also gives the program greater flexibility since new columns and indices can be added without having to recode every query. </p> </li> <li><p><b>Command-line dataset analysis tool</b></p> <p> Experienced SQL users can employ the command-line <b>sqlite</b> program to analyze miscellaneous datasets. Raw data can be imported from CSV files, then that data can be sliced and diced to generate a myriad of summary reports. Possible uses include website log analysis, sports statistics analysis, compilation of programming metrics, and analysis of experimental results. </p> <p> You can also do the same thing with a enterprise client/server database, of course. The advantages to using SQLite in this situation are that SQLite is much easier to set up and the resulting database is a single file that you can store on a floppy disk or flash-memory stick or email to a colleague. </p> </li> <li><p><b>Stand-in for an enterprise database during demos or testing</b></p> <p> If you are writing a client application for an enterprise database engine, it makes sense to use a generic database backend that allows you to connect to many different kinds of SQL database engines. It makes even better sense to go ahead and include SQLite in the mix of supported database and to statically link the SQLite engine in with the client. That way the client program can be used standalone with an SQLite data file for testing or for demonstrations. </p> </li> <li><p><b>Database Pedagogy</b></p> <p> Because it is simple to setup and use (installation is trivial: just copy the <b>sqlite</b> or <b>sqlite.exe</b> executable to the target machine and run it) SQLite makes a good database engine for use in teaching SQL. Students can easily create as many databases as they like and can email databases to the instructor for comments or grading. For more advanced students who are interested in studying how an RDBMS is implemented, the modular and well-commented and documented SQLite code can serve as a good basis. This is not to say that SQLite is an accurate model of how other database engines are implemented, but rather a student who understands how SQLite works can more quickly comprehend the operational principles of other systems. </p> </li> <li><p><b>Experimental SQL language extensions</b></p> <p>The simple, modular design of SQLite makes it a good platform for prototyping new, experimental database language features or ideas. </p> </li> </ul> <h2>Situations Where Another RDBMS May Work Better</h2> <ul> <li><p><b>Client/Server Applications</b><p> <p>If you have many client programs accessing a common database over a network, you should consider using a client/server database engine instead of SQLite. SQLite will work over a network filesystem, but because of the latency associated with most network filesystems, performance will not be great. Also, the file locking logic of many network filesystems implementation contains bugs (on both Unix and windows). If file locking does not work like it should, it might be possible for two or more client programs to modify the same part of the same database at the same time, resulting in database corruption. Because this problem results from bugs in the underlying filesystem implementation, there is nothing SQLite can do to prevent it.</p> <p>A good rule of thumb is that you should avoid using SQLite in situations where the same database will be accessed simultaneously from many computers over a network filesystem.</p> </li> <li><p><b>High-volume Websites</b></p> <p>SQLite will normally work fine as the database backend to a website. But if you website is so busy that your are thinking of splitting the database component off onto a separate machine, then you should definitely consider using an enterprise-class client/server database engine instead of SQLite.</p> </li> <li><p><b>Very large datasets</b></p> <p>When you start a transaction in SQLite (which happens automatically before any write operation that is not within an explicit BEGIN...COMMIT) the engine has to allocate a bitmap of dirty pages in the disk file to help it manage its rollback journal. SQLite needs 256 bytes of RAM for every 1MiB of database (assuming a 1024-byte page size: less memory is used with larger page sizes, of course). For smaller databases, the amount of memory required is not a problem, but when database begin to grow into the multi-gigabyte range, the size of the bitmap can get quite large. If you need to store and modify more than a few dozen GB of data, you should consider using a different database engine. </p> </li> <li><p><b>High Concurrency</b></p> <p> SQLite uses reader/writer locks on the entire database file. That means if any process is reading from any part of the database, all other processes are prevented from writing any other part of the database. Similarly, if any one process is writing to the database, all other processes are prevented from reading any other part of the database. For many situations, this is not a problem. Each application does its database work quickly and moves on, and no lock lasts for more than a few dozen milliseconds. But there are some applications that require more concurrency, and those applications may need to seek a different solution. </p> </li> </ul> |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | <html> <body bgcolor="white"> <h1 align="center"> Copyright Release for<br> Contributions To SQLite </h1> <p> SQLite is software that implements an embeddable SQL database engine. SQLite is available for free download from http://www.sqlite.org/. The principal author and maintainer of SQLite has disclaimed all copyright interest in his contributions to SQLite and thus released his contributions into the public domain. In order to keep the SQLite software unencumbered by copyright claims, the principal author asks others who may from time to time contribute changes and enhancements to likewise disclaim their own individual copyright interest. </p> <p> Because the SQLite software found at http://www.sqlite.org/ is in the public domain, anyone is free to download the SQLite software from that website, make changes to the software, use, distribute, or sell the modified software, under either the original name or under some new name, without any need to obtain permission, pay royalties, acknowledge the original source of the software, or in any other way compensate, identify, or notify the original authors. Nobody is in any way compelled to contribute their SQLite changes and enhancements back to the SQLite website. This document concerns only changes and enhancements to SQLite that are intentionally and deliberately contributed back to the SQLite website. </p> <p> For the purposes of this document, "SQLite software" shall mean any computer source code, documentation, makefiles, test scripts, or other information that is published on the SQLite website, http://www.sqlite.org/. Precompiled binaries are excluded from the definition of "SQLite software" in this document because the process of compiling the software may introduce information from outside sources which is not properly a part of SQLite. </p> <p> The header comments on the SQLite source files exhort the reader to share freely and to never take more than one gives. In the spirit of that exhortation I make the following declarations: </p> <ol> <li><p> I dedicate to the public domain any and all copyright interest in the SQLite software that was publicly available on the SQLite website (http://www.sqlite.org/) prior to the date of the signature below and any changes or enhancements to the SQLite software that I may cause to be published on that website in the future. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to the SQLite software under copyright law. </p></li> <li><p> To the best of my knowledge and belief, the changes and enhancements that I have contributed to SQLite are either originally written by me or are derived from prior works which I have verified are also in the public domain and are not subject to claims of copyright by other parties. </p></li> <li><p> To the best of my knowledge and belief, no individual, business, organization, government, or other entity has any copyright interest in the SQLite software as it existed on the SQLite website as of the date on the signature line below. </p></li> <li><p> I agree never to publish any additional information to the SQLite website (by CVS, email, scp, FTP, or any other means) unless that information is an original work of authorship by me or is derived from prior published versions of SQLite. I agree never to copy and paste code into the SQLite code base from other sources. I agree never to publish on the SQLite website any information that would violate a law or breach a contract. </p></li> </ol> <p> <table width="100%" cellpadding="0" cellspacing="0"> <tr> <td width="60%" valign="top"> Signature: <p> </p> <p> </p> <p> </p> </td><td valign="top" align="left"> Date: </td></tr> <td colspan=2> Name (printed): </td> </tr> </table> </body> </html> |
cannot compute difference between binary files
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
cannot compute difference between binary files
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
|
| < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < < |
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 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 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 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 | #!/usr/bin/tclsh # # This script processes raw page text into its final form for display. # Invoke this command as follows: # # tclsh wrap.tcl $(DOC) $(SRC) $(DEST) source1.in source2.in ... # # The $(DOC) and $(SRC) values are the names of directories containing # the documentation source and program source. $(DEST) is the name of # of the directory where generated HTML is written. sourceN.in is the # input file to be processed. The output is sourceN.html in the # local directory. # # Changes made to the source files: # # * An appropriate header is prepended to the file. # * Any <title>...</title> in the input is moved into the prepended # header. # * An appropriate footer is appended. # * Scripts within <tcl>...</tcl> are evaluated. Output that # is emitted from these scripts by "puts" appears in place of # the original script. # set DOC [lindex $argv 0] set SRC [lindex $argv 1] set DEST [lindex $argv 2] set HOMEDIR [pwd] rename puts real_puts proc puts {text} { real_puts $::OUT $text flush $::OUT } # The following proc is used to ensure consistent formatting in the # HTML generated by lang.tcl and pragma.tcl. # proc Syntax {args} { puts {<table cellpadding="10" class=pdf_syntax>} foreach {rule body} $args { puts "<tr><td align=\"right\" valign=\"top\">" puts "<i><font color=\"#ff3434\">$rule</font></i> ::=</td>" regsub -all < $body {%LT} body regsub -all > $body {%GT} body regsub -all %LT $body {</font></b><i><font color="#ff3434">} body regsub -all %GT $body {</font></i><b><font color="#2c2cf0">} body regsub -all {[]|[*?]} $body {</font></b>&<b><font color="#2c2cf0">} body regsub -all "\n" [string trim $body] "<br>\n" body regsub -all "\n *" $body "\n\\ \\ \\ \\ " body regsub -all {[|,.*()]} $body {<big>&</big>} body regsub -all { = } $body { <big>=</big> } body regsub -all {STAR} $body {<big>*</big>} body ## These metacharacters must be handled to undo being ## treated as SQL punctuation characters above. regsub -all {RPPLUS} $body {</font></b>)+<b><font color="#2c2cf0">} body regsub -all {LP} $body {</font></b>(<b><font color="#2c2cf0">} body regsub -all {RP} $body {</font></b>)<b><font color="#2c2cf0">} body ## Place the left-hand side of the rule in the 2nd table column. puts "<td><b><font color=\"#2c2cf0\">$body</font></b></td></tr>" } puts {</table>} } foreach infile [lrange $argv 3 end] { cd $HOMEDIR real_puts "Processing $infile" set fd [open $infile r] set in [read $fd] close $fd set title {No Title} regexp {<title>([^\n]*)</title>} $in all title regsub {<title>[^\n]*</title>} $in {} in set outfile [file root [file tail $infile]].html set ::OUT [open $::DEST/$outfile w] puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">} puts {<html><head>} puts "<title>$title</title>" puts {<style type="text/css"> body { max-width: 800px; /* not supported in IE 6 */ margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%; } a { color: #4F7263 } a:visited { color: #80a796 } .logo { position:absolute; margin:3px; } .tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px; } .toolbar { background-color: #80a796; position: relative; font-variant: small-caps; clear: both; text-align: center; line-height: 1.6em; margin-bottom: 50px; padding:1px 8px; height:1%; /* IE hack to fix rounded corner positions */ } .toolbar a { color: white; text-decoration: none; padding: 6px 4px; } .toolbar a:visited { color: white; } .toolbar a:hover { color: #80a796; background: white; } .content { margin: 5%; } .content dt { font-weight:bold; } .content dd { margin-bottom: 25px; margin-left:20%; } .content ul { padding:0px; padding-left: 15px; margin:0px; } /* rounded corners */ .se,.ne,.nw,.sw { position: absolute; width:8px; height:8px; font-size:7px; /* IE hack to ensure height=8px */ } .se { background-image: url(se.png); bottom: 0px; right: 0px; } .ne { background-image: url(ne.png); top: 0px; right: 0px; } .sw { background-image: url(sw.png); bottom: 0px; left: 0px; } .nw { background-image: url(nw.png); top: 0px; left: 0px; } </style> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> } puts {</head>} puts {<body> <div><!-- container div to satisfy validator --> <img class="logo" src="http://www.sqlite.org/SQLite.gif" alt="SQLite Logo"> <div><!-- IE hack to prevent disappearing logo--></div> <div class="tagline">The World's Most Used SQL Database.</div> <div class="toolbar"> <a href="index.html">Home</a> <a href="about.html">About</a> <a href="docs.html">Documentation</a> <a href="download.html">Download</a> <a href="copyright.html">License</a> <a href="press.html">Advocacy</a> <a href="devhome.html">Developers</a> <a href="news.html">News</a> <a href="support.html">Support</a> <!-- rounded corners --> <div class="ne"></div><div class="se"></div><div class="nw"></div><div class="sw"></div> </div> } regsub -all {<tcl>} $in "\175; eval \173" in regsub -all {</tcl>} $in "\175; puts \173" in eval "puts \173$in\175" cd $::HOMEDIR puts {<hr><small><i>} set mtime [file mtime $infile] set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1] puts "This page last modified $date" puts {</i></small></div></body></html>} close $::OUT } |