Struct Context 

pub struct Context {
    pub limit: usize,
    pub null: String,
    /* private fields */
}

Where a command runs: the database, and the limits placed on it.

Fields

limit: usize

How many rows a command hands back when it was not told.

null: String

What to print where a value is null.

Implementations

impl Context

pub fn open( path: &str, mode: OpenMode, root: Option<PathBuf>, ) -> Result<Context, Failed>

Opens a context on a database.

@param path - the file, or an in-memory name @param readonly - whether writes are refused @param root - the directory paths are confined to, if any

pub fn open_for( path: &str, mode: OpenMode, root: Option<PathBuf>, may_create: bool, ) -> Result<Context, Failed>

Opens a database for one command, which may or may not make the file.

@param path - the database to open @param mode - whether writes are refused @param root - the directory every file is confined to, when there is one @param may_create - whether this caller is allowed to make the file

pub fn use_database(&mut self, path: &str) -> Result<(), Failed>

Points this context at a different file, reopening only if it moved.

One open database at a time, and that is a decision rather than a simplification. One file is one buffer pool, and a server holding four of them holds four pools whose sizes nobody asked about. A caller that alternates pays a reopen; a caller that does not pays nothing.

@param path - the file to use

pub fn refuse_the_world(&mut self)

Refuses every shell command that reaches outside the database.

Always on over MCP, and there is no flag to turn it off (task-1979, H1). The set is the reference’s -safe: 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. An MCP server that left it off handed an agent a shell on the host, whatever --root said - and a child spawned that way inherits the server’s standard output, which is the JSON-RPC channel, so its output landed in the middle of a reply and the client could not match one to its id.

A flag was the alternative and was rejected: an operator who forgets it hands an agent a shell, and there is no case for an MCP server with safe mode off.

pub fn recovery(&self) -> Recovery

Returns what opening this context’s database did to it.

See Outcome::with_recovery for what the command surface does with it.

pub fn stray_log_segments(&self) -> &[u64]

Returns the strays this context’s open found. See Context::strays_beside.

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

Returns a handle to this session’s cancellation flag.

Setting it stops the statement that is running, at the next batch. It is cleared when the next command is armed, so a cancel that arrives between two calls belongs to the one that has finished and is discarded rather than applied to the one that has not started.

pub fn preserve_cancellation(&self)

Says that this surface clears the cancellation flag itself.

Only inillucent-mcp does, because it is the only one that reads its input on a second thread. See budget::arm_as_it_stands.

pub fn shell(&mut self) -> &mut Shell

Returns the shell commands drive.

pub fn path(&self) -> &str

Returns the file this context is open on.

pub fn readonly(&self) -> bool

Returns whether writes are refused.

pub fn cap_rows(&self, asked: usize) -> Result<usize, Failed>

Refuses a row count past this surface’s ceiling, when it has one.

The command line has no ceiling and the MCP server does, which is the whole distinction: a person running inillucent query against their own database and asking for every row is asking for what they want, and an agent doing the same thing to a served database is the case --root and --readonly already exist for. Zero means every row and is refused where a ceiling is set, because “every row” is precisely the request the ceiling is about.

@param asked - the row count the caller wants

pub fn set_max_rows(&mut self, most: Option<usize>)

Sets the ceiling on how many rows one call hands back.

@param most - the ceiling, or None for the command line’s absence of one

pub fn set_limits(&mut self, limits: StatementLimits)

Sets what one command may spend inside the engine.

@param limits - the budget, or Limits::unbounded for a command line

pub fn limits(&self) -> StatementLimits

Returns what one command on this surface may spend inside the engine.

A verb that runs work outside the executor - a migration reads a remote server and writes rows through a second connection - asks so that it can put itself under the same ceiling rather than beside it.

pub fn confined(&self) -> bool

Returns whether this surface was confined to a directory.

Confinement is about reach, not only about paths. --root exists so that an MCP server can be handed to an agent without handing it the file system, and a verb that dialled a host and a port would be a hole straight through it. A command that can reach something other than a file asks this and refuses.

pub fn confine(&self, path: &str) -> Result<PathBuf, Failed>

Refuses a path outside the root, when a root was set.

The decision is not made here. It is made by inillucent_vfs::confine, which resolves the path through the file system rather than reading its text, and which the VFS consults again at the moment the file is opened. This method exists so that a person reading a refusal is told the path they typed and the directory they confined to, neither of which survives as far as the VFS.

The check this replaced compared normalised path text against the root. A junction below the root passed it and opened a database outside the root.

@param path - the path a caller named

pub fn refuse_if_it_writes(&self, sql: &str) -> Result<(), Failed>

Refuses a statement that changes something, when read-only.

By the statement’s class, in one place shared with the driver (task-1979, section 5.2). The check this replaces asked the engine to EXPLAIN the statement and refused only when the message contained “not a read-only statement” - text compile_explain never produces for an INSERT, a write pragma, an ATTACH or a VACUUM INTO, all of which therefore ran and persisted through --readonly. The class comes from the parser’s own classify_statement; the pragma lists are in inillucent_driver::readonly so this and the driver cannot disagree.

This is the layer that gives the caller a good message. The layer that makes the property true is the commit path, which refuses a write on a connection opened read only whatever reached it.

@param sql - the statement

pub fn collect_output(&mut self, input: &str) -> String

Runs shell input, collecting everything it printed.

@param input - the lines, dot commands included