mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Running a file of statements, and the atomic block.
//!
//! Cutting a file into its statements is [`super::script_split`]; this module
//! takes the pieces it produced and runs them.
//!
//! # What escapes an atomic block
//!
//! A statement that defines an object confirms itself on this server, so a
//! block cannot undo it. Such a statement therefore always produces a notice of
//! escape: the caller asked for all or nothing, and this part is neither.

pub use super::script_split::{split, validate_delimiter, Piece, Statements};

use super::prepare::{self, Gated};
use super::{change, read, Policy, WriteState};
use crate::error::Result;
use crate::sql::classify::Classification;
use mysql_async::Conn;
use serde_json::{json, Value};

/// Whether a statement escapes an atomic block.
///
/// A statement that defines an object confirms itself on this server, so the
/// block cannot undo it. Reporting that is the whole point: the caller asked
/// for all or nothing, and this part is neither.
#[must_use]
pub const fn escapes_block(classification: Classification) -> bool {
    matches!(
        classification,
        Classification::Definition | Classification::Administration
    )
}

/// The notice one escaping statement produces.
#[must_use]
pub fn escape_notice(
    piece: &Piece,
    classification: Classification,
) -> crate::output::envelope::Gap {
    crate::output::envelope::Gap::new(
        format!("statement_{}", piece.index),
        "escapes_atomic_block",
        format!(
            "the statement on line {} is a {} and confirms itself, so the block cannot undo it",
            piece.line,
            classification.as_str()
        ),
    )
}

/// Everything running one statement of a file takes.
///
/// The five describe one thing, which is how a statement is to be run: on which
/// connection, under which policy, against which record of what has already
/// been written, on a destination that may refuse change of its own, and with
/// which reading of the server's types. Carried apart, every function that runs
/// a statement had to repeat the same list, and every new one had to repeat it
/// again in the same order.
pub struct Run<'a> {
    /// The connection every statement is asked on.
    pub conn: &'a mut Conn,
    /// What this invocation admits.
    pub policy: &'a Policy,
    /// What has already been written, and what that now demands.
    pub write_state: &'a mut WriteState,
    /// Whether the destination itself refuses change.
    pub server_read_only: bool,
    /// How the server's own types are read back.
    pub conversion: &'a crate::types::Conversion,
    /// Whether a statement that failed ends the run.
    ///
    /// True everywhere but a file whose caller asked to carry on. A block is
    /// never allowed to carry on, because a block that skipped a statement and
    /// was then confirmed is precisely the half-applied script FR-029 forbids.
    pub stop_on_failure: bool,
}

/// Confirms changes this invocation already sent, so they outlive the process.
///
/// # Why this has to exist at all
///
/// Every connection opens with `SET autocommit = 0`, and the reason written
/// beside that statement is a good one: a read must never persist anything, and
/// a statement the caller did not mean to commit is discarded when the process
/// ends. What was missing is the other half. A caller who DID mean it — who
/// passed the confirmation mark and received `affected: 1` — also had the change
/// discarded, because nothing ever sent this.
///
/// Measured against a real server before the fix: `query run` inserting one row
/// ended in zero, reported one row changed, and a second process counted none.
/// The same insert through `query tx`, which confirms its own block, persisted.
/// The report was never false about the statement; it was silent about the
/// transaction the statement was still sitting in.
///
/// It survived because no proof read a change back from a SECOND process. A
/// proof that reads the count reported by the process that just wrote it is
/// reading the inside of the open transaction, and everything looks right in
/// there.
///
/// # Errors
///
/// Returns the driver failure when the server refuses the confirmation, which
/// is the one moment a caller has to be told the change is not there.
pub async fn confirm_changes(conn: &mut Conn) -> Result<()> {
    prepare::exec_drop(conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await
}

/// The statement that opens an atomic block.
pub const BEGIN_BLOCK: &str = "START TRANSACTION";
/// The statement that confirms an atomic block.
pub const CONFIRM_BLOCK: &str = "COMMIT";
/// The statement that undoes an atomic block.
pub const UNDO_BLOCK: &str = "ROLLBACK";

/// Runs one statement of a file or a block and says what it did.
///
/// # Errors
///
/// Returns the failure the statement produced, which is what stops the file or
/// undoes the block.
pub async fn one_of_many(gated: &Gated, run: &mut Run<'_>) -> Result<Value> {
    if gated.classification().is_read() {
        let result = read::collect(run.conn, gated, run.policy.max_rows, run.conversion).await?;
        return Ok(json!({"read": true, "row_count": result.rows.len()}));
    }
    let outcome = change::apply(
        gated,
        run.conn,
        run.policy,
        run.write_state,
        run.server_read_only,
    )
    .await?;
    Ok(change::describe(gated, &outcome))
}

/// The columns a run of a file announces, one record per statement.
pub const FILE_COLUMNS: [&str; 3] = ["statement", "line", "outcome"];

/// Runs one statement of a file and builds the record FR-028 publishes.
///
/// The record carries where the statement was and what it did, and never the
/// statement's own text, which is dropped before the server is asked.
///
/// # Errors
///
/// Returns the failure the statement produced, carrying its position.
async fn record_of(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
    let (index, line) = (piece.index, piece.line);
    let stop = run.stop_on_failure;
    match attempt(piece, run).await {
        Ok(record) => Ok(record),
        Err(failure) if stop => Err(failure),
        Err(failure) => Ok(refused(index, line, &failure)),
    }
}

/// The record of one statement that failed, for a run told to carry on.
///
/// The record keeps the three published columns, so a caller reading the file
/// as a continuous flow sees the same shape whether the statement worked or
/// not, and learns which it was from the outcome rather than from the shape.
fn refused(index: usize, line: usize, failure: &crate::error::Failure) -> crate::output::Row {
    let mut record = crate::output::Row::new();
    record.insert("statement".to_owned(), json!(index));
    record.insert("line".to_owned(), json!(line));
    record.insert(
        "outcome".to_owned(),
        json!({
            "failed": true,
            "code": failure.code(),
            "message": failure.message(),
            "exit": failure.exit_number().code(),
        }),
    );
    record
}

/// Runs one statement and builds its record, failing as it always did.
async fn attempt(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
    let where_it_is = format!("statement {}, line {}", piece.index, piece.line);
    let gated = prepare::gate(&piece.sql, &[], run.policy)
        .map_err(|failure| failure.with_cause(where_it_is.clone()))?;
    // Nothing after this point needs the text, so it is not kept alive across
    // the round trip to the server.
    drop(piece.sql);
    let outcome = one_of_many(&gated, run)
        .await
        .map_err(|failure| failure.with_cause(where_it_is))?;

    let mut record = crate::output::Row::new();
    record.insert("statement".to_owned(), json!(piece.index));
    record.insert("line".to_owned(), json!(piece.line));
    record.insert("outcome".to_owned(), outcome);
    Ok(record)
}

/// Runs a file of statements, stopping at the first one that fails.
///
/// Stopping is not a preference: a statement that failed may well be the one
/// the rest depended on, so carrying on would apply a script whose first half
/// never happened.
///
/// This is the whole-answer path, so it gathers the records it produces. The
/// promise that memory does not follow volume is made for a run consumed as a
/// continuous flow, which is [`stream_file`].
///
/// # Errors
///
/// Returns the failure of the first statement that produced one, carrying the
/// position of that statement in the file.
pub async fn run_file<S: IntoIterator<Item = Piece>>(
    statements: S,
    run: &mut Run<'_>,
) -> Result<Value> {
    let mut answers = Vec::new();
    for piece in statements {
        let record = record_of(piece, run).await?;
        answers.push(Value::Object(record.into_iter().collect()));
    }
    // A file that only read has nothing to confirm and confirming costs it a
    // round trip; a file that changed anything has everything to confirm.
    if !run.policy.dry_run {
        confirm_changes(run.conn).await?;
    }
    Ok(json!({"statement_count": answers.len(), "rows": answers}))
}

/// Runs a file of statements, writing each record as its statement finishes.
///
/// This is the second clause of Proof 5: a long command file holds no more at
/// its last statement than at its first. The statements arrive one at a time
/// from the cut and each record leaves as it is made, so nothing here grows
/// with the count of statements.
///
/// # Why a cut answer does not cut the run
///
/// The output operations decide records, not statements. A ceiling reached
/// part way through stops the records leaving; it must never stop the file
/// being applied, because a statement not run is a different thing from a row
/// not printed, and a script half applied is exactly what FR-028 forbids. The
/// run therefore carries on to the end, and the answer that was cut simply
/// closes without the record that would declare it whole.
///
/// `sink` carries the channel, the shape and the tail the closing record
/// declares besides the count: the command that produced the records and the
/// destination they came from, which a flow has no envelope of its own to carry
/// (FR-143).
///
/// # Errors
///
/// Returns the failure of the first statement that produced one, and a limit
/// failure when the reader closed the output channel.
pub async fn stream_file<W: std::io::Write, S: IntoIterator<Item = Piece>>(
    statements: S,
    run: &mut Run<'_>,
    sink: crate::output::stream::Sink<'_, W>,
    pipeline: &crate::output::Pipeline,
    token: &tokio_util::sync::CancellationToken,
) -> Result<u64> {
    let crate::output::stream::Sink {
        writer,
        formatter,
        tail,
    } = sink;
    let columns: Vec<String> = FILE_COLUMNS.iter().map(|name| (*name).to_owned()).collect();
    // FR-039. The volume ceiling covers the frame this shape writes around the
    // records, not the records alone, so the frame is measured before the first
    // record is offered and charged against the ceiling here.
    let mut formatter = formatter;
    let mut stage = pipeline.flow_framed(&mut *formatter, tail, &columns, 0, &[])?;
    let mut flow = crate::output::stream::Stream::open(writer, formatter, tail, &columns)?;
    let mut still_emitting = true;

    for piece in statements {
        // Between statements, never inside one. A statement already sent is
        // seen through so the file's record says what really happened to it,
        // and the next one is simply not begun. A long file used to run to its
        // last statement after the signal, because the check lived above this
        // loop and nothing here asked again.
        if token.is_cancelled() {
            return Err(crate::error::Failure::interrupted(
                "interrupted.between_statements",
                "the invocation was stopped between two statements of the file",
            ));
        }
        let record = record_of(piece, run).await?;
        if !still_emitting {
            continue;
        }
        match stage.offer(record) {
            crate::output::ops::Step::Emit(shaped) => flow.write(&shaped)?,
            crate::output::ops::Step::Skip => {}
            crate::output::ops::Step::Stop => still_emitting = false,
        }
    }

    // Confirmed before the closing record is written, because the record is
    // what tells the caller the file was applied and it must not say so while
    // the work is still inside a transaction nobody closed. A ceiling that cut
    // the OUTPUT never cuts the RUN, which is the paragraph above this
    // function, so the statements are all sent by here either way.
    if !run.policy.dry_run {
        confirm_changes(run.conn).await?;
    }

    // Reaching the end of the file is what makes the answer whole, and a
    // ceiling that cut it is what makes it not, so the closing record is
    // written here and only when both hold.
    if stage.is_whole() {
        // A run of a file has no ceiling on rows to reach, so it closes
        // declaring nothing left out.
        return flow.finish(tail, &[], stage.applied().as_ref());
    }
    Ok(flow.emitted())
}

/// Admits every statement of a block and declares the ones that escape it.
///
/// The escape is declared before the block opens, so the caller reads which
/// part of the promise the server will not keep even if the block itself never
/// gets that far.
///
/// # Errors
///
/// Returns the refusal the first inadmissible statement earned.
pub fn gate_block(
    statements: &[String],
    policy: &Policy,
) -> Result<(Vec<Gated>, Vec<crate::output::envelope::Gap>)> {
    let mut gaps = Vec::new();
    let mut gated = Vec::new();
    for (position, text) in statements.iter().enumerate() {
        let one = prepare::gate(text, &[], policy)?;
        if escapes_block(one.classification()) {
            let piece = Piece {
                index: position + 1,
                line: position + 1,
                sql: text.clone(),
            };
            gaps.push(escape_notice(&piece, one.classification()));
        }
        gated.push(one);
    }
    Ok((gated, gaps))
}

/// Runs statements together, so they are confirmed or undone as one.
///
/// A statement that confirms itself escapes the block. That is a property of
/// the server and not a choice made here, so each such statement is declared as
/// a gap rather than silently counted inside the promise.
///
/// # Errors
///
/// Returns the failure of the first statement that produced one, after asking
/// the server to undo everything the block had done.
pub async fn run_block(gated: &[Gated], run: &mut Run<'_>) -> Result<Value> {
    prepare::exec_drop(run.conn, BEGIN_BLOCK, mysql_async::Params::Empty).await?;
    let mut answers = Vec::new();
    for one in gated {
        match one_of_many(one, run).await {
            Ok(answer) => answers.push(answer),
            Err(failure) => {
                // The undo is attempted whatever happens, and its own outcome
                // never replaces the failure that made the caller stop.
                let _ = prepare::exec_drop(run.conn, UNDO_BLOCK, mysql_async::Params::Empty).await;
                return Err(failure);
            }
        }
    }
    prepare::exec_drop(run.conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await?;
    Ok(json!({"rows": answers, "confirmed": true, "statement_count": gated.len()}))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A statement that confirms itself is exactly what an atomic block cannot
    /// undo, so it always produces a notice.
    #[test]
    fn a_statement_that_confirms_itself_always_escapes_the_block() {
        assert!(escapes_block(Classification::Definition));
        assert!(escapes_block(Classification::Administration));
        assert!(!escapes_block(Classification::Change));
        assert!(!escapes_block(Classification::Read));

        let piece = Piece {
            index: 3,
            line: 12,
            sql: "CREATE TABLE t (a INT)".to_owned(),
        };
        let notice = escape_notice(&piece, Classification::Definition);
        assert_eq!(notice.object, "statement_3");
        assert_eq!(notice.cause, "escapes_atomic_block");
        assert!(notice.detail.contains("12") && notice.detail.contains("definition"));
    }
}