57 lines
3.1 KiB
Markdown
57 lines
3.1 KiB
Markdown
|
<h1 align="center">The dbtotxt Tool</h1>
|
||
|
|
|
||
|
|
The dbtotxt utility program reads an SQLite database file and writes its
|
||
|
|
raw binary content to screen as a hex dump for testing and debugging
|
||
|
|
purposes.
|
||
|
|
|
||
|
|
The hex-dump output is formatted in such a way as to be easily readable
|
||
|
|
both by humans and by software. The dbtotxt utility has long been a part
|
||
|
|
of the TH3 test suite. The output of dbtotxt can be embedded in TH3 test
|
||
|
|
scripts and used to generate very specific database files, perhaps with
|
||
|
|
deliberately introduced corruption. The cov1/corrupt*.test modules in
|
||
|
|
TH3 make extensive use of dbtotxt.
|
||
|
|
|
||
|
|
More recently (2018-12-13) the dbtotxt utility has been added to the SQLite
|
||
|
|
core and the command-line shell (CLI) has been augmented to be able to read
|
||
|
|
dbtotxt output. The CLI dot-command is:
|
||
|
|
|
||
|
|
> .open --hexdb ?OPTIONAL-FILENAME?
|
||
|
|
|
||
|
|
If the OPTIONAL-FILENAME is included, then content is read from that file.
|
||
|
|
If OPTIONAL-FILENAME is omitted, then the text is taken from the input stream,
|
||
|
|
terminated by the "| end" line of the dbtotxt text. This allows small test
|
||
|
|
databases to be embedded directly in scripts. Consider this example:
|
||
|
|
|
||
|
|
>
|
||
|
|
.open --hexdb
|
||
|
|
| size 8192 pagesize 4096 filename x9.db
|
||
|
|
| page 1 offset 0
|
||
|
|
| 0: 53 51 4c 69 74 65 20 66 6f 72 6d 61 74 20 33 00 SQLite format 3.
|
||
|
|
| 16: 10 00 01 01 00 40 20 20 00 00 00 04 00 00 00 02 .....@ ........
|
||
|
|
| 32: 00 00 00 00 00 00 00 00 00 00 00 01 00 00 00 04 ................
|
||
|
|
| 48: 00 00 00 00 00 00 00 00 00 00 00 01 00 00 00 00 ................
|
||
|
|
| 80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 04 ................
|
||
|
|
| 96: 00 2e 30 38 0d 00 00 00 01 0f c0 00 0f c0 00 00 ..08............
|
||
|
|
| 4032: 3e 01 06 17 11 11 01 69 74 61 62 6c 65 74 31 74 >......itablet1t
|
||
|
|
| 4048: 31 02 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 1.CREATE TABLE t
|
||
|
|
| 4064: 31 28 78 2c 79 20 44 45 46 41 55 4c 54 20 78 27 1(x,y DEFAULT x'
|
||
|
|
| 4080: 66 66 27 2c 7a 20 44 45 46 41 55 4c 54 20 30 29 ff',z DEFAULT 0)
|
||
|
|
| page 2 offset 4096
|
||
|
|
| 0: 0d 08 14 00 04 00 10 00 0e 05 0a 0f 04 15 00 10 ................
|
||
|
|
| 16: 88 02 03 05 90 04 0e 08 00 00 00 00 00 00 00 00 ................
|
||
|
|
| 1040: 00 00 00 00 ff 87 7c 02 05 8f 78 0e 08 00 00 00 ......|...x.....
|
||
|
|
| 2064: 00 00 00 ff 0c 0a 01 fb 00 00 00 00 00 00 00 00 ................
|
||
|
|
| 2560: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 83 ................
|
||
|
|
| 2576: 78 01 05 87 70 0e 08 00 00 00 00 00 00 00 00 00 x...p...........
|
||
|
|
| 3072: 00 00 00 00 00 00 00 00 00 ff 00 00 01 fb 00 00 ................
|
||
|
|
| 3584: 00 00 00 00 00 83 78 00 05 87 70 0e 08 00 00 00 ......x...p.....
|
||
|
|
| 4080: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ................
|
||
|
|
| end x9.db
|
||
|
|
SELECT rowid FROM t1;
|
||
|
|
PRAGMA integrity_check;
|
||
|
|
|
||
|
|
You can run this script to see that the database file is correctly decoded
|
||
|
|
and loaded. Furthermore, you can make subtle corruptions to the input
|
||
|
|
database simply by editing the hexadecimal description, then rerun the
|
||
|
|
script to verify that SQLite correctly handles the corruption.
|