Skip to content

CLI.md

Latest commit

 

History

History
38 lines (28 loc) · 2.66 KB

CLI.md

File metadata and controls

38 lines (28 loc) · 2.66 KB
Raw

CLI

The CLI tool is call sqlinsite.

Commands

  • sqlinsite profile - Profiles a SQLite file using a set of queries specified in an input file. See details in PROFILE.md
    • --test-file - SQLite file to test. Statements run in place; write statements permanently modify this file.
    • --statements - A file with one or more SQLite statements to use in the profiling test. Uses Statements File Format.
    • --out-file - Path to save the output file. Uses Output File Format.
    • --timing - raw (default) emits raw monotonic-clock ticks; relative rebases Time Start/Time End to the start of the run so they begin near zero. Time End - Time Start is the per-access cost either way.
    • --quiet - Suppress the run summary printed to stderr.
  • sqlinsite map - Maps the schema tables, data tables, and indexes to the pages storing them. Output for each page includes header information, free bytes, rows/keys it holds, and pointers to other pages. The result is written as an indexed SQLite database (not JSON) so visualize can query it by page-number range and scale to billions of pages. See details in MAP.md
    • --test-file - SQLite file to map.
    • --out-file - Path to save the generated map (a SQLite database).
  • sqlinsite visualize - Command to visualize sqlinsite profile and sqlinsite map results. See details in VISUALIZE.md
    • sqlinsite visualize serve - Start a local web server hosting an interactive canvas view (runs in the foreground; Ctrl-C to stop).
      • --map-file - Path to map file generated by sqlinsite map command.
      • --profile-file - Optional. Path to profile CSV generated by sqlinsite profile command; enables the read/write overlay.
      • --port - Optional. Listen port (default 8080; 0 picks a free port).
  • sqlinsite --help (or -h) - Print usage and exit.

Options accept both --flag value and --flag=value forms. Unknown commands, unknown options, and missing option values are reported with usage and exit code 2.

Error policy

If a statement fails to prepare or step, the error is reported to stderr and profiling continues with the next statement (one bad statement does not abort the session). The overall process exit code is non-zero if any statement failed. Rows already emitted for successful statements are kept.

Exit codes: 0 success, 1 a runtime failure occurred (bad statement, missing test file, output error), 2 invalid command line.

See ../examples/README.md for a full worked example.