Struct Shell 

pub struct Shell {

    pub layout: Layout,
    pub bail: bool,
    pub echo: bool,
    pub timer: bool,
    pub stats: bool,
    pub show_changes: bool,
    pub explain_plan: bool,
    pub crlf: bool,
    pub prompt_main: String,
    pub prompt_continue: String,
    pub explain_mode: ExplainMode,
    pub nonce: Option<String>,
    pub testcase: Option<String>,
    pub captured: String,
    pub tests_run: usize,
    pub tests_failed: usize,
    pub viewer: Option<PathBuf>,
    pub auth: bool,
    pub authorized: Rc<RefCell<Vec<String>>>,
    pub trace: Option<String>,
    pub scanstats: String,
    pub defensive: bool,
    pub done: bool,
    pub failed: bool,
    pub first_error: Option<DbError>,
    pub line: usize,
    pub log_to: Option<String>,
    pub progress_interval: u64,
    pub progress_limit: u64,
    pub progress_once: bool,
    pub progress_quiet: bool,
    pub progress_pending_limit: bool,
    pub readonly: bool,
    pub safe: bool,
    pub sink: Option<String>,
    pub rows_since_redirect: usize,
    pub parameters: BTreeMap<String, Value<'static>>,
    /* private fields */
}

One shell session: the databases it can reach, and every setting a dot command can change.

Fields

layout: Layout

How results are laid out.

bail: bool

Whether a failing statement stops the script.

echo: bool

Whether each statement is echoed before it runs.

timer: bool

Whether to print how long each statement took.

stats: bool

Whether the page cache’s counters are printed after each statement.

show_changes: bool

Whether to print the change count after each statement.

explain_plan: bool

Whether an EXPLAIN QUERY PLAN is printed before each statement.

crlf: bool

Whether output lines end with a carriage return, which .crlf sets.

prompt_main: String

The prompt an interactive session prints for a new statement.

prompt_continue: String

The prompt it prints for a statement that is not finished.

explain_mode: ExplainMode

When an EXPLAIN listing is laid out as a table.

nonce: Option<String>

The token .nonce set, which suspends safe mode for one command.

testcase: Option<String>

The name of the .testcase that is capturing output, if one is.

captured: String

What has been printed since that .testcase.

tests_run: usize

How many .checks have run.

tests_failed: usize

How many of them failed.

viewer: Option<PathBuf>

Where a .excel or .www file is being written, if one is.

auth: bool

Whether the authorizer’s decisions are printed, which .auth sets.

authorized: Rc<RefCell<Vec<String>>>

The decisions it has recorded since the last statement.

trace: Option<String>

Where .trace sends each statement, when it sends it anywhere.

scanstats: String

What .scanstats was set to.

defensive: bool

Whether SQLITE_DBCONFIG_DEFENSIVE is in force.

On, because the reference’s shell turns it on. It is the flag that makes PRAGMA journal_mode = OFF and PRAGMA writable_schema = ON refuse rather than take effect, and a shell that left it off answered those two differently from the reference on a fresh database.

done: bool

Whether the shell should stop.

failed: bool

Whether anything has failed, which decides the exit code.

first_error: Option<DbError>

The engine’s error for the first statement that failed since failed was last cleared, when the failure came from the engine.

Kept so a command can report the right status (task-2120). The printed text says what went wrong; only the DbError says which class of failure it was. inillucent run used to report every failure in a script as syntax with exit code 1, so a statement the engine has not built - exec reports it as unsupported with exit code 3 - told the caller to look for a mistake in SQL that had none.

line: usize

The line the statement being run started on.

log_to: Option<String>

Where .log was pointed, when it was pointed anywhere.

Recorded and never written to: this engine emits no log messages, so the destination is a place nothing arrives. .show reports it, which is the only thing that reads it.

progress_interval: u64

How often .progress was asked to run a handler, in opcodes.

Recorded and reported by .show, and never acted on: the reference’s handler prints nothing unless --limit is given, and this engine’s VM has no per-opcode callback to hang one on. Keeping the state means a script written for the reference sets it and runs on rather than stopping at “unknown command”.

progress_limit: u64

The --limit .progress was given.

progress_once: bool

Whether .progress --once was asked for.

progress_quiet: bool

Whether .progress --quiet was asked for.

progress_pending_limit: bool

Whether the next number belongs to a --limit that has just been read.

readonly: bool

Whether a statement that changes something is refused.

-readonly on the command line, and --readonly on inillucent and inillucent-mcp. The binder decides what writes, not a scan of the text: EXPLAIN QUERY PLAN over the statement fails with “not a read-only statement” for anything that does, which cannot be talked past with whitespace, a comment or an unusual capitalisation. It is the same mechanism inillucent-driver uses and it is deliberately the same one - two classifiers would eventually disagree, and the one that let a write through would be the one nobody was watching.

The file is still open for writing. The capability table says readonly_open is partial and says exactly this, which is why the row is worth reading before an application decides what it means by “open this read only”.

safe: bool

Whether the commands that reach outside the database are refused.

-safe on the command line. The set is the reference’s: running a program (.shell, .system), loading a shared library (.load), changing the working directory (.cd), handing a file to whatever the system opens it with (.excel, .www), and writing output through a pipe (.output |cmd, .once |cmd). Every one of them is a way for a script that was only supposed to query a database to run code.

.nonce lifts it for one command, which is the reference’s own escape hatch and is why the token is a secret the script’s author chose.

sink: Option<String>

Where output goes when a caller is collecting it rather than printing.

Not the same as captured, and deliberately outside it. captured belongs to .testcase/.check, which compare one command’s output against an expected digest; this belongs to a caller running the shell as a subroutine - the run command and the MCP server behind it

• and has to still be collecting while a .testcase inside the script it was given is doing its own thing. So say checks the testcase first, and a script that uses both nests the way it reads.

A .once or .output redirect is checked before this and takes the rows, which is what makes export --out write its file - see the comment in say. So a collected script that redirects hands its caller whatever was not redirected, which for an export is nothing.

complain writes here whatever a redirect is doing, because a caller collecting output wants the error in the same stream a person would have seen it in rather than appended to the rows in the file. It still sets failed.

rows_since_redirect: usize

How many result rows have been rendered since output was last sent somewhere with redirect.

So a command that redirects can say what it wrote. export --out sends its rows to a file, which leaves it nothing to report from the text it collected; counting the lines back out of the file would have to know which of the eight formats writes a header, a separator rule or several lines to the row. The number the renderer was handed is the answer, and it costs one addition.

parameters: BTreeMap<String, Value<'static>>

The values .parameter set bound, by the name they were given.

The shell’s own table, not the engine’s. SQLite keeps them in a temp.sqlite_parameters table and binds from it before each step; the visible behaviour is the same and this needs no reserved table name. Ordered by key, which is the order .parameter list prints and the order the reference prints.

Implementations

impl Shell

pub fn open_one(path: &str) -> Result<Opened, String>

Opens one database, with the modules and the flags a shell gives it.

@param path - the file, or an in-memory name

pub fn open_one_as(path: &str, read_only: bool) -> Result<Opened, String>

Opens one database, read only when the surface asked for it.

@param path - the file, or an in-memory name @param read_only - whether this connection may write the file

pub fn open_one_reporting( path: &str, read_only: bool, ) -> Result<Opened, DbError>

Shell::open_one_as, handing back the engine’s own error.

@param path - the file, or an in-memory name @param read_only - whether this connection may write the file

pub fn open(path: &str) -> Result<Shell, String>

Opens a shell on a database file, or on an in-memory one.

pub fn open_as(path: &str, read_only: bool) -> Result<Shell, String>

Opens a shell on a database file, read only when the surface asked.

@param path - the file, or an in-memory name @param read_only - whether this connection may write the file

pub fn open_reporting(path: &str, read_only: bool) -> Result<Shell, DbError>

Opens a shell, handing back the engine’s own error.

So a caller can report the status the engine gave (task-1979, C6). open_as folds the failure into a sentence, and the command surface then reported every open failure as io - including a file another process holds, which is busy and is the one an agent or a script can act on by retrying.

@param path - the file, or an in-memory name @param read_only - whether this connection may write the file

pub fn connection(&self) -> Connection<'_>

Returns the connection statements run on.

Always the same session, so a temporary object made by one statement is there for the next one.

pub fn limit(&self, limit: Limit) -> i64

Returns what one run-time limit is set to on the open database.

@param limit - which limit

pub fn set_limit(&mut self, limit: Limit, requested: i64) -> i64

Sets one run-time limit on the open database, returning its old value.

@param limit - which limit @param requested - the value asked for

pub fn boolean_pragma(&self, name: &str) -> bool

Returns whether a boolean pragma reads on.

@param name - the pragma’s name

pub fn set_boolean_pragma(&mut self, name: &str, value: bool) -> bool

Sets a boolean pragma, reporting whether the engine took it.

@param name - the pragma’s name @param value - what to set it to

pub fn set_authorizer(&mut self, on: bool)

Installs or removes the authorizer that .auth on prints through.

@param on - whether the decisions are watched

pub fn set_defensive(&mut self, on: bool) -> bool

Puts the connection into or out of defensive mode.

@param on - whether the flag is in force

pub fn cache_stats(&self) -> CacheStats

Returns what the page cache has been asked to do.

pub fn pool_bytes(&self) -> usize

Returns how many bytes the page cache is holding.

pub fn backup_to(&self, path: &str) -> Result<(), String>

Copies the open database into a file and checks the copy.

@param path - where the copy goes

pub fn path(&self) -> &str

Returns where the database was opened from.

pub fn recovery(&self) -> Recovery

Returns what opening the active database did to it.

See inillucent_driver::Recovery; the caller decides whether to report it, which for the command surface is “only when it says something happened”.

pub fn log_sequence(&self) -> u64

Returns which segment of its log the active database is writing.

pub fn active(&self) -> usize

Returns which slot statements run on.

pub fn slots(&self) -> Vec<Option<String>>

Returns each slot and what it holds, for .connection.

pub fn use_slot(&mut self, slot: usize) -> Result<(), String>

Switches to one slot, opening an in-memory database if it is closed.

Out of range is ignored, which is what the reference does with it.

@param slot - which connection to run statements on

pub fn close_slot(&mut self, slot: usize)

Closes one slot, moving back to slot zero if it was the active one.

Slot zero is never closed: it is the database the shell was started on, and a shell with nothing open has nothing to run a statement against.

@param slot - which connection to close

pub fn reopen(&mut self, path: &str) -> Result<(), String>

Closes the current database and opens another.

pub fn say(&mut self, line: &str)

Prints one line to wherever output is currently going.

pub fn complain(&mut self, message: &str)

Prints an error, which always goes to standard error.

Unless a caller is collecting output, in which case it goes there: a command run through the MCP server has no standard error anybody will ever read, and an error that vanished would be worse than one printed among the rows.

pub fn unsafe_refused(&mut self, command: &str) -> bool

Refuses a command that safe mode does not allow, and says which it was.

Returns whether the caller may go on. A matching .nonce has already cleared safe mode for this command by the time this is asked, because that is what .nonce does.

@param command - the dot command being attempted, leading dot included

pub fn redirect(&mut self, path: Option<&str>, once: bool) -> Result<(), String>

Sends output to a file, or back to standard output when path is none.

@param path - the file to write, or none to go back to standard output @param once - whether the redirect ends after the next SQL statement

pub fn output_target(&self) -> &str

Where output is going, as .show names it.

stdout when nothing is redirecting, and the file name when .output or .once is.

pub fn cancel_flag(&self) -> Arc<AtomicBool>

Returns a handle to the flag that stops the running statement.

A front end registers it with interrupt::stop_on_ctrl_c; a program embedding the shell can set it from any thread.

pub fn run(&mut self, sql: &str)

Runs one complete statement and prints whatever it produced.

pub fn collect( &self, sql: &str, ) -> Result<(Vec<String>, Vec<Vec<Value<'static>>>), Failure>

Runs a statement and collects its column names and rows.

pub fn collect_bound( &self, sql: &str, bound: &[OwnedDatum], ) -> Result<(Vec<String>, Vec<Vec<Value<'static>>>), Failure>

Runs a statement with values bound by position, and collects its rows.

By position, because a caller that is a program has no names. The shell’s own .parameter table binds :name and @name markers, which is what a person typing a script wants; a command arriving over MCP or off a command line carries an ordered array and means ?1, ?2, … . Going through the named table for those was the first thing tried, and it bound nothing at all: the engine reports a numbered marker under a name that is not the text ?1, so every lookup missed and every value silently arrived as NULL. Binding by the index the parser assigned cannot miss.

Both mechanisms apply: positional values are bound first and the named table after, so a script that sets :limit once and passes ?1 per call gets both.

@param sql - the statement @param bound - the values for ?1, ?2, … in order

pub fn trailing_statement(&self, sql: &str) -> Option<String>

Returns the text left over after the first statement, when it holds another one.

The parser’s own count, not a scan for semicolons. A trigger body contains a semicolon, and a string literal can contain anything, so counting them is how a correct script gets refused and an incorrect one gets accepted. prepare_with_tail reports how many bytes the first statement used, and leading_trivia reports how much of what is left is not a statement at all - which is what makes a trailing semicolon and a trailing comment not count as a second statement. Both are the engine’s own, so there is no second scanner here to disagree with the parser.

A script that will not compile answers None: it is a syntax error, and it should be reported as the syntax error it is rather than as a script with too many statements in it.

@param sql - the text a caller passed as one statement

pub fn execute(&mut self, sql: &str) -> Result<(), String>

Runs a statement for its effect, reporting only a failure.

@param sql - the statements, separated by semicolons

pub fn writes(&self, sql: &str) -> bool

Returns whether a statement changes something, by its class.

From inillucent_driver::readonly, the same answer the command surface and the driver use (task-1979, section 5.2). It used to ask the engine to plan the statement and read the text of the failure, and explain answers Ok for an INSERT, a write pragma, an ATTACH and a VACUUM INTO - so this reported that none of them writes.

@param sql - the statement

pub fn scalar(&self, sql: &str) -> Option<String>

Returns one column of one row, as text.

pub fn column(&self, sql: &str) -> Vec<String>

Returns the first column of every row, as text.