sqlite3 '-batch' option appears undocumented
I've had a hard time looking for a more substantial description of sqlite3's '-batch' option than what the command line says ("force batch I/O"), which doesn't mean much to me.
Naively I'd expected to find something in the cli.html page.
In a recent forum thread, someone complained that he also was "unclear" about this option, to which Larry Brasfield replied:
How 'sqlite3 -batch ...' differs from 'sqlite3 ...' invoked with redirected input is not a simple subject. (Anybody who doubts this should study shell.c, paying attention to sets/uses of the variable stdin_is_interactive and various tests such as 'isatty(0)', 'in!=0' and 'in==stdin'.)
It thus seems to me that there is room for improving the documentation here.
-batch automatically exits the sqlite command line so you don't leave an active job hanging.
I use it like this in cron
0 */6 * * * (sleep 20; cd /var/www/html/ssmppt15l/ && touch sweep.txt && /usr/bin/sqlite3 -batch ':memory:' '.read sweep_ramdisk.sql')
If you run /usr/bin/sqlite3 -batch ':memory:' '.read sweep_ramdisk.sql' at the cli, the sqlite will process and then exit as if you had entered the .quit command.
It should cause an "exit code" to be returned when the process terminates. An "interactive process" (one that does not have -batch specified) does not return a failure (non-zero) exit code because it is not possible for an interactive process to exit other than successfully (though opinions may vary, it is a fact, though I suppose that EOF on the input stream could constitute an ABEND).
A process created using redirection (eg "sqlite3 <input >output") is an interactive process and as such should always return 0 as the exit code notwithstanding any transient failure other than process ABEND (such as the previously mentioned EOF condition, perhaps). Contrast with "sqlite3 -batch <input >output" which should return a non-zero exit code only in the event that the process ABENDed -- an EOF on the input stream is NOT an ABEND.
An examination of the shell.c code would be necessary to determine if this is indeed what the -batch option does. However, this is the "normal" meaning of such options converting an "interactive" program to "batch" operation. It is what an one would expect such a parameter to mean.
Note also -bail which will presumably make a -batch exit immediately when encountering an error.
Rudimentary testing indicates that -batch forces "batch" mode even if the input is from a tty (console) (basically, that there is no interactive prompt issued). It may affect the process return code, but I have not tested that.
-bail only has effect when in "non-interactive mode", that is the input is not from a tty (console) or -batch is specified.
Browsing the source for the shell program, the setting of stdin_is_interactive cause numerous miscellaneous effects. Among the things affected are error message generation, whether the input line is saved in the history file, and whether an interrupt signal causes program exit or just aborts the current command.