Skip to main content

Module exec

Module exec 

Source
Expand description

Sending a caller’s statement to the server, and everything that guards it.

§Every statement travels as a prepared statement

This is not a preference and it is not a performance choice. It is the structural defence of the whole product, and it is the only one that does not depend on this tool reading the caller’s text correctly.

The server manual states that the text of a prepared statement must represent one single statement, never several. So the server itself refuses a text carrying more than one command, and that refusal holds even if every textual guard in crate::sql were wrong.

Concretely: every round trip here uses the driver’s exec_* family, which speaks the binary prepared protocol, and never the query_* family, which speaks the text protocol and would hand the server a text it is free to split. Replacing an exec_* call with a query_* call removes the defence silently, which is why it is written down here.

§The order of the layers

For every caller statement, in this order and never another:

  1. crate::sql::guard::admit refuses a multiple command and any reach for the server’s own filesystem, before a single byte is sent.
  2. crate::sql::classify() decides from the syntax tree whether the statement reads, changes, defines or administers. A shape it does not recognise is refused and is never treated as a read.
  3. Only then does the prepared statement reach the server.

§The parts

  • prepare is the single gateway every statement passes through.
  • read serves a statement that returns rows, without ever persisting.
  • change serves a statement that alters data, with its ceilings.
  • plan serves the plan of a statement, estimated or measured.
  • script serves a file of statements and the atomic block.
  • routine serves a stored routine and its output parameters.
  • named serves a statement stored under a name.
  • lineage resolves result columns to their physical origin, offline.

Re-exports§

pub use change::ChangeOutcome;
pub use plan::Estimate;
pub use prepare::bind;
pub use prepare::gate;
pub use prepare::Gated;

Modules§

change
Statements that alter data, and every ceiling that guards them.
lineage
Where each column of a result physically comes from.
named
Running a statement kept under a name.
named_store
Where a statement kept under a name lives between invocations.
plan
What a statement would do, asked two different ways.
prepare
The single gateway every caller statement passes through.
read
Statements that return rows.
routine
Calling a stored routine.
script
Running a file of statements, and the atomic block.
script_split
Cutting a file of statements into the statements it carries.

Structs§

ChangeCounts
The two counts a change produces, and which of them the caller asked for.
Policy
Every ceiling and every guard one invocation runs under.
WriteState
Whether the destination refuses changes of its own accord.

Enums§

Ephemeral
State an invocation created that dies with the process.
ReadOnlyProbe
How often the destination is asked whether it accepts a change.

Constants§

DEFAULT_MAX_INPUT_BYTES
What one invocation will read before judging any of it, absent a setting.