Skip to main content

mariadb_cli/exec/
script.rs

1//! Running a file of statements, and the atomic block.
2//!
3//! Cutting a file into its statements is [`super::script_split`]; this module
4//! takes the pieces it produced and runs them.
5//!
6//! # What escapes an atomic block
7//!
8//! A statement that defines an object confirms itself on this server, so a
9//! block cannot undo it. Such a statement therefore always produces a notice of
10//! escape: the caller asked for all or nothing, and this part is neither.
11
12pub use super::script_split::{split, validate_delimiter, Piece, Statements};
13
14use super::prepare::{self, Gated};
15use super::{change, read, Policy, WriteState};
16use crate::error::Result;
17use crate::sql::classify::Classification;
18use mysql_async::Conn;
19use serde_json::{json, Value};
20
21/// Whether a statement escapes an atomic block.
22///
23/// A statement that defines an object confirms itself on this server, so the
24/// block cannot undo it. Reporting that is the whole point: the caller asked
25/// for all or nothing, and this part is neither.
26#[must_use]
27pub const fn escapes_block(classification: Classification) -> bool {
28    matches!(
29        classification,
30        Classification::Definition | Classification::Administration
31    )
32}
33
34/// The notice one escaping statement produces.
35#[must_use]
36pub fn escape_notice(
37    piece: &Piece,
38    classification: Classification,
39) -> crate::output::envelope::Gap {
40    crate::output::envelope::Gap::new(
41        format!("statement_{}", piece.index),
42        "escapes_atomic_block",
43        format!(
44            "the statement on line {} is a {} and confirms itself, so the block cannot undo it",
45            piece.line,
46            classification.as_str()
47        ),
48    )
49}
50
51/// Everything running one statement of a file takes.
52///
53/// The five describe one thing, which is how a statement is to be run: on which
54/// connection, under which policy, against which record of what has already
55/// been written, on a destination that may refuse change of its own, and with
56/// which reading of the server's types. Carried apart, every function that runs
57/// a statement had to repeat the same list, and every new one had to repeat it
58/// again in the same order.
59pub struct Run<'a> {
60    /// The connection every statement is asked on.
61    pub conn: &'a mut Conn,
62    /// What this invocation admits.
63    pub policy: &'a Policy,
64    /// What has already been written, and what that now demands.
65    pub write_state: &'a mut WriteState,
66    /// Whether the destination itself refuses change.
67    pub server_read_only: bool,
68    /// How the server's own types are read back.
69    pub conversion: &'a crate::types::Conversion,
70    /// Whether a statement that failed ends the run.
71    ///
72    /// True everywhere but a file whose caller asked to carry on. A block is
73    /// never allowed to carry on, because a block that skipped a statement and
74    /// was then confirmed is precisely the half-applied script FR-029 forbids.
75    pub stop_on_failure: bool,
76}
77
78/// Confirms changes this invocation already sent, so they outlive the process.
79///
80/// # Why this has to exist at all
81///
82/// Every connection opens with `SET autocommit = 0`, and the reason written
83/// beside that statement is a good one: a read must never persist anything, and
84/// a statement the caller did not mean to commit is discarded when the process
85/// ends. What was missing is the other half. A caller who DID mean it — who
86/// passed the confirmation mark and received `affected: 1` — also had the change
87/// discarded, because nothing ever sent this.
88///
89/// Measured against a real server before the fix: `query run` inserting one row
90/// ended in zero, reported one row changed, and a second process counted none.
91/// The same insert through `query tx`, which confirms its own block, persisted.
92/// The report was never false about the statement; it was silent about the
93/// transaction the statement was still sitting in.
94///
95/// It survived because no proof read a change back from a SECOND process. A
96/// proof that reads the count reported by the process that just wrote it is
97/// reading the inside of the open transaction, and everything looks right in
98/// there.
99///
100/// # Errors
101///
102/// Returns the driver failure when the server refuses the confirmation, which
103/// is the one moment a caller has to be told the change is not there.
104pub async fn confirm_changes(conn: &mut Conn) -> Result<()> {
105    prepare::exec_drop(conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await
106}
107
108/// The statement that opens an atomic block.
109pub const BEGIN_BLOCK: &str = "START TRANSACTION";
110/// The statement that confirms an atomic block.
111pub const CONFIRM_BLOCK: &str = "COMMIT";
112/// The statement that undoes an atomic block.
113pub const UNDO_BLOCK: &str = "ROLLBACK";
114
115/// Runs one statement of a file or a block and says what it did.
116///
117/// # Errors
118///
119/// Returns the failure the statement produced, which is what stops the file or
120/// undoes the block.
121pub async fn one_of_many(gated: &Gated, run: &mut Run<'_>) -> Result<Value> {
122    if gated.classification().is_read() {
123        let result = read::collect(run.conn, gated, run.policy.max_rows, run.conversion).await?;
124        return Ok(json!({"read": true, "row_count": result.rows.len()}));
125    }
126    let outcome = change::apply(
127        gated,
128        run.conn,
129        run.policy,
130        run.write_state,
131        run.server_read_only,
132    )
133    .await?;
134    Ok(change::describe(gated, &outcome))
135}
136
137/// The columns a run of a file announces, one record per statement.
138pub const FILE_COLUMNS: [&str; 3] = ["statement", "line", "outcome"];
139
140/// Runs one statement of a file and builds the record FR-028 publishes.
141///
142/// The record carries where the statement was and what it did, and never the
143/// statement's own text, which is dropped before the server is asked.
144///
145/// # Errors
146///
147/// Returns the failure the statement produced, carrying its position.
148async fn record_of(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
149    let (index, line) = (piece.index, piece.line);
150    let stop = run.stop_on_failure;
151    match attempt(piece, run).await {
152        Ok(record) => Ok(record),
153        Err(failure) if stop => Err(failure),
154        Err(failure) => Ok(refused(index, line, &failure)),
155    }
156}
157
158/// The record of one statement that failed, for a run told to carry on.
159///
160/// The record keeps the three published columns, so a caller reading the file
161/// as a continuous flow sees the same shape whether the statement worked or
162/// not, and learns which it was from the outcome rather than from the shape.
163fn refused(index: usize, line: usize, failure: &crate::error::Failure) -> crate::output::Row {
164    let mut record = crate::output::Row::new();
165    record.insert("statement".to_owned(), json!(index));
166    record.insert("line".to_owned(), json!(line));
167    record.insert(
168        "outcome".to_owned(),
169        json!({
170            "failed": true,
171            "code": failure.code(),
172            "message": failure.message(),
173            "exit": failure.exit_number().code(),
174        }),
175    );
176    record
177}
178
179/// Runs one statement and builds its record, failing as it always did.
180async fn attempt(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
181    let where_it_is = format!("statement {}, line {}", piece.index, piece.line);
182    let gated = prepare::gate(&piece.sql, &[], run.policy)
183        .map_err(|failure| failure.with_cause(where_it_is.clone()))?;
184    // Nothing after this point needs the text, so it is not kept alive across
185    // the round trip to the server.
186    drop(piece.sql);
187    let outcome = one_of_many(&gated, run)
188        .await
189        .map_err(|failure| failure.with_cause(where_it_is))?;
190
191    let mut record = crate::output::Row::new();
192    record.insert("statement".to_owned(), json!(piece.index));
193    record.insert("line".to_owned(), json!(piece.line));
194    record.insert("outcome".to_owned(), outcome);
195    Ok(record)
196}
197
198/// Runs a file of statements, stopping at the first one that fails.
199///
200/// Stopping is not a preference: a statement that failed may well be the one
201/// the rest depended on, so carrying on would apply a script whose first half
202/// never happened.
203///
204/// This is the whole-answer path, so it gathers the records it produces. The
205/// promise that memory does not follow volume is made for a run consumed as a
206/// continuous flow, which is [`stream_file`].
207///
208/// # Errors
209///
210/// Returns the failure of the first statement that produced one, carrying the
211/// position of that statement in the file.
212pub async fn run_file<S: IntoIterator<Item = Piece>>(
213    statements: S,
214    run: &mut Run<'_>,
215) -> Result<Value> {
216    let mut answers = Vec::new();
217    for piece in statements {
218        let record = record_of(piece, run).await?;
219        answers.push(Value::Object(record.into_iter().collect()));
220    }
221    // A file that only read has nothing to confirm and confirming costs it a
222    // round trip; a file that changed anything has everything to confirm.
223    if !run.policy.dry_run {
224        confirm_changes(run.conn).await?;
225    }
226    Ok(json!({"statement_count": answers.len(), "rows": answers}))
227}
228
229/// Runs a file of statements, writing each record as its statement finishes.
230///
231/// This is the second clause of Proof 5: a long command file holds no more at
232/// its last statement than at its first. The statements arrive one at a time
233/// from the cut and each record leaves as it is made, so nothing here grows
234/// with the count of statements.
235///
236/// # Why a cut answer does not cut the run
237///
238/// The output operations decide records, not statements. A ceiling reached
239/// part way through stops the records leaving; it must never stop the file
240/// being applied, because a statement not run is a different thing from a row
241/// not printed, and a script half applied is exactly what FR-028 forbids. The
242/// run therefore carries on to the end, and the answer that was cut simply
243/// closes without the record that would declare it whole.
244///
245/// `sink` carries the channel, the shape and the tail the closing record
246/// declares besides the count: the command that produced the records and the
247/// destination they came from, which a flow has no envelope of its own to carry
248/// (FR-143).
249///
250/// # Errors
251///
252/// Returns the failure of the first statement that produced one, and a limit
253/// failure when the reader closed the output channel.
254pub async fn stream_file<W: std::io::Write, S: IntoIterator<Item = Piece>>(
255    statements: S,
256    run: &mut Run<'_>,
257    sink: crate::output::stream::Sink<'_, W>,
258    pipeline: &crate::output::Pipeline,
259    token: &tokio_util::sync::CancellationToken,
260) -> Result<u64> {
261    let crate::output::stream::Sink {
262        writer,
263        formatter,
264        tail,
265    } = sink;
266    let columns: Vec<String> = FILE_COLUMNS.iter().map(|name| (*name).to_owned()).collect();
267    // FR-039. The volume ceiling covers the frame this shape writes around the
268    // records, not the records alone, so the frame is measured before the first
269    // record is offered and charged against the ceiling here.
270    let mut formatter = formatter;
271    let mut stage = pipeline.flow_framed(&mut *formatter, tail, &columns, 0, &[])?;
272    let mut flow = crate::output::stream::Stream::open(writer, formatter, tail, &columns)?;
273    let mut still_emitting = true;
274
275    for piece in statements {
276        // Between statements, never inside one. A statement already sent is
277        // seen through so the file's record says what really happened to it,
278        // and the next one is simply not begun. A long file used to run to its
279        // last statement after the signal, because the check lived above this
280        // loop and nothing here asked again.
281        if token.is_cancelled() {
282            return Err(crate::error::Failure::interrupted(
283                "interrupted.between_statements",
284                "the invocation was stopped between two statements of the file",
285            ));
286        }
287        let record = record_of(piece, run).await?;
288        if !still_emitting {
289            continue;
290        }
291        match stage.offer(record) {
292            crate::output::ops::Step::Emit(shaped) => flow.write(&shaped)?,
293            crate::output::ops::Step::Skip => {}
294            crate::output::ops::Step::Stop => still_emitting = false,
295        }
296    }
297
298    // Confirmed before the closing record is written, because the record is
299    // what tells the caller the file was applied and it must not say so while
300    // the work is still inside a transaction nobody closed. A ceiling that cut
301    // the OUTPUT never cuts the RUN, which is the paragraph above this
302    // function, so the statements are all sent by here either way.
303    if !run.policy.dry_run {
304        confirm_changes(run.conn).await?;
305    }
306
307    // Reaching the end of the file is what makes the answer whole, and a
308    // ceiling that cut it is what makes it not, so the closing record is
309    // written here and only when both hold.
310    if stage.is_whole() {
311        // A run of a file has no ceiling on rows to reach, so it closes
312        // declaring nothing left out.
313        return flow.finish(tail, &[], stage.applied().as_ref());
314    }
315    Ok(flow.emitted())
316}
317
318/// Admits every statement of a block and declares the ones that escape it.
319///
320/// The escape is declared before the block opens, so the caller reads which
321/// part of the promise the server will not keep even if the block itself never
322/// gets that far.
323///
324/// # Errors
325///
326/// Returns the refusal the first inadmissible statement earned.
327pub fn gate_block(
328    statements: &[String],
329    policy: &Policy,
330) -> Result<(Vec<Gated>, Vec<crate::output::envelope::Gap>)> {
331    let mut gaps = Vec::new();
332    let mut gated = Vec::new();
333    for (position, text) in statements.iter().enumerate() {
334        let one = prepare::gate(text, &[], policy)?;
335        if escapes_block(one.classification()) {
336            let piece = Piece {
337                index: position + 1,
338                line: position + 1,
339                sql: text.clone(),
340            };
341            gaps.push(escape_notice(&piece, one.classification()));
342        }
343        gated.push(one);
344    }
345    Ok((gated, gaps))
346}
347
348/// Runs statements together, so they are confirmed or undone as one.
349///
350/// A statement that confirms itself escapes the block. That is a property of
351/// the server and not a choice made here, so each such statement is declared as
352/// a gap rather than silently counted inside the promise.
353///
354/// # Errors
355///
356/// Returns the failure of the first statement that produced one, after asking
357/// the server to undo everything the block had done.
358pub async fn run_block(gated: &[Gated], run: &mut Run<'_>) -> Result<Value> {
359    prepare::exec_drop(run.conn, BEGIN_BLOCK, mysql_async::Params::Empty).await?;
360    let mut answers = Vec::new();
361    for one in gated {
362        match one_of_many(one, run).await {
363            Ok(answer) => answers.push(answer),
364            Err(failure) => {
365                // The undo is attempted whatever happens, and its own outcome
366                // never replaces the failure that made the caller stop.
367                let _ = prepare::exec_drop(run.conn, UNDO_BLOCK, mysql_async::Params::Empty).await;
368                return Err(failure);
369            }
370        }
371    }
372    prepare::exec_drop(run.conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await?;
373    Ok(json!({"rows": answers, "confirmed": true, "statement_count": gated.len()}))
374}
375
376#[cfg(test)]
377mod tests {
378    use super::*;
379
380    /// A statement that confirms itself is exactly what an atomic block cannot
381    /// undo, so it always produces a notice.
382    #[test]
383    fn a_statement_that_confirms_itself_always_escapes_the_block() {
384        assert!(escapes_block(Classification::Definition));
385        assert!(escapes_block(Classification::Administration));
386        assert!(!escapes_block(Classification::Change));
387        assert!(!escapes_block(Classification::Read));
388
389        let piece = Piece {
390            index: 3,
391            line: 12,
392            sql: "CREATE TABLE t (a INT)".to_owned(),
393        };
394        let notice = escape_notice(&piece, Classification::Definition);
395        assert_eq!(notice.object, "statement_3");
396        assert_eq!(notice.cause, "escapes_atomic_block");
397        assert!(notice.detail.contains("12") && notice.detail.contains("definition"));
398    }
399}