mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Activity counters, read twice so the answer means something.
//!
//! A counter on this server is a total since the server started. Read once it
//! says almost nothing: a caller cannot tell a busy minute from a busy month.
//! So this command takes two readings separated by a declared interval and
//! reports the difference alongside the total. The interval always appears in
//! the answer, so it is never implicit.

use super::{cell, fetch, matches_pattern, number_of, pairs, text_of, ServerSettings};
use crate::cli::server::StatusArgs;
use crate::error::{Failure, Result};
use crate::output::{Envelope, Gap, Row};
use indexmap::IndexMap;
use mysql_async::{Conn, Params};
use serde_json::{json, Value};
use tokio_util::sync::CancellationToken;

/// The counter that says how long the server has been up.
///
/// A drop in this counter is the only reliable sign that the server restarted
/// between the two readings, which makes every difference meaningless.
const UPTIME: &str = "Uptime";

/// Reads the counters twice and reports what changed in between.
///
/// # Errors
///
/// Returns a server failure when the server restarted between the two
/// readings, an interrupted failure when the caller stopped the work during
/// the interval, and the mapped driver failure when the counters cannot be
/// read at all.
pub async fn run(
    connection: &mut Conn,
    args: &StatusArgs,
    settings: &ServerSettings,
    token: &CancellationToken,
) -> Result<Envelope> {
    let interval = args.interval.unwrap_or(settings.status_interval_secs);

    let first = read_counters(connection).await?;
    super::wait_interval(interval, token).await?;
    let second = read_counters(connection).await?;

    refuse_across_restart(&first, &second, interval)?;

    let rows = compare(&first, &second, args.pattern.as_deref());
    let (summary, gaps) = summarise(connection, &second).await;

    let mut envelope = Envelope::new(
        "server status",
        json!({
            "interval_secs": interval,
            "summary": summary,
            "rows": rows,
        }),
    );
    for gap in gaps {
        envelope = envelope.with_gap(gap);
    }
    Ok(envelope)
}

/// Reads every counter the server publishes, in the server's own order.
async fn read_counters(connection: &mut Conn) -> Result<IndexMap<String, String>> {
    let rows = fetch(connection, "SHOW GLOBAL STATUS", Params::Empty).await?;
    Ok(pairs(&rows))
}

/// Refuses the difference when the server restarted between the two readings.
///
/// A restart resets every counter, so the difference would be a negative
/// number dressed up as a measurement. Refusing is the only honest answer.
///
/// # Errors
///
/// Returns a server failure when the second reading shows less uptime than the
/// first.
pub fn refuse_across_restart(
    first: &IndexMap<String, String>,
    second: &IndexMap<String, String>,
    interval: u64,
) -> Result<()> {
    let before: Option<i64> = first.get(UPTIME).and_then(|text| text.parse().ok());
    let after: Option<i64> = second.get(UPTIME).and_then(|text| text.parse().ok());

    match (before, after) {
        (Some(before), Some(after)) if after < before => Err(Failure::server(
            "server.restarted_between_readings",
            "the server restarted between the two readings, so no difference can be computed",
        )
        .with_detail("interval", interval.to_string())
        .with_hint(format!(
            "read again once the server is stable; the interval used was {interval} seconds"
        ))),
        _ => Ok(()),
    }
}

/// Builds one row per counter, carrying the total and the change.
///
/// A counter the caller's pattern excludes never reaches the answer, and a
/// counter that is not a number keeps its text with no difference attached,
/// because subtracting text would invent a measurement.
#[must_use]
pub fn compare(
    first: &IndexMap<String, String>,
    second: &IndexMap<String, String>,
    pattern: Option<&str>,
) -> Vec<Row> {
    let mut rows = Vec::new();
    for (name, current) in second {
        if pattern.is_some_and(|pattern| !matches_pattern(pattern, name)) {
            continue;
        }
        let previous = first.get(name);
        let mut row = Row::new();
        row.insert("name".to_owned(), json!(name));
        row.insert("value".to_owned(), json!(current));
        row.insert("previous".to_owned(), json!(previous));
        row.insert("delta".to_owned(), difference(previous, current));
        rows.push(row);
    }
    rows
}

/// The change between two readings of one counter, when both are numbers.
fn difference(previous: Option<&String>, current: &str) -> Value {
    let before: Option<i64> = previous.and_then(|text| text.trim().parse().ok());
    let after: Option<i64> = current.trim().parse().ok();
    match (before, after) {
        (Some(before), Some(after)) => json!(after - before),
        _ => Value::Null,
    }
}

/// The four indicators a caller looking at a slow server asks for first.
///
/// The connection ceiling and the longest running statement need their own
/// reads. The longest statement needs the right to observe other connections,
/// and a credential without it still gets the counters, with the missing part
/// declared as a gap rather than losing the whole answer.
async fn summarise(
    connection: &mut Conn,
    counters: &IndexMap<String, String>,
) -> (Value, Vec<Gap>) {
    let mut gaps = Vec::new();
    let in_use: i64 = read_counter(counters, "Threads_connected");
    let running: i64 = read_counter(counters, "Threads_running");

    let ceiling = match scalar(connection, "SELECT @@max_connections").await {
        Ok(value) => value,
        Err(failure) => {
            gaps.push(Gap::new(
                "connection_ceiling",
                "unreadable",
                failure.message().to_owned(),
            ));
            Value::Null
        }
    };

    let longest = match longest_statement(connection).await {
        Ok(value) => value,
        Err(failure) => {
            gaps.push(Gap::new(
                "longest_statement_seconds",
                "permission",
                failure.message().to_owned(),
            ));
            Value::Null
        }
    };

    let mut summary = json!({
        "connections_in_use": in_use,
        "connections_running": running,
        "connections_idle": (in_use - running).max(0),
        "connection_ceiling": ceiling,
        "longest_statement_seconds": longest,
    });
    match page_cache(counters) {
        Ok(cache) => summary["page_cache"] = cache,
        Err(gap) => gaps.push(gap),
    }
    (summary, gaps)
}

/// How much of the page reading was served from memory rather than from disk.
///
/// The two counters this is built from were already travelling in the rows, and
/// nobody was doing the division. A caller looking at a slow server needs to
/// separate a bad statement from a server whose memory is too small for its
/// working set, and that is the one number that separates them.
///
/// The figure is cumulative since the server started, like every counter here,
/// so it describes the life of the server and never the interval between the
/// two readings.
///
/// # Errors
///
/// Returns the gap to declare when the server publishes neither counter, since
/// answering nought would say the server never served a page from memory.
fn page_cache(counters: &IndexMap<String, String>) -> std::result::Result<Value, Gap> {
    const REQUESTS: &str = "Innodb_buffer_pool_read_requests";
    const FROM_DISK: &str = "Innodb_buffer_pool_reads";

    if !counters.contains_key(REQUESTS) && !counters.contains_key(FROM_DISK) {
        return Err(Gap::new(
            "page_cache",
            "not_published",
            "this server publishes neither page cache counter",
        ));
    }

    let requests = read_counter(counters, REQUESTS);
    let from_disk = read_counter(counters, FROM_DISK);
    let from_memory = (requests - from_disk).max(0);
    // A server that has read no page yet has no ratio, and calling that nought
    // would report a cache that never works rather than one never asked.
    let ratio = (requests > 0).then(|| {
        // Rounded to two places with whole numbers only, and half away from
        // zero, which is where the pair of approximate divisions used to land.
        // Rendering a counter as an approximate number first is what this
        // avoids: a counter past two to the fifty-third does not survive that
        // rendering, so the ratio drifted on exactly the busy server it is
        // asked about. Both counters are known to be at or above zero here,
        // and the divisor is known to be above it, so neither sign nor a
        // division by nothing can arise.
        let hundredths =
            (i128::from(from_memory) * 20_000 + i128::from(requests)) / (i128::from(requests) * 2);
        let written = format!("{}.{:02}", hundredths / 100, hundredths % 100);
        serde_json::from_str::<serde_json::Value>(&written).unwrap_or(Value::Null)
    });

    Ok(json!({
        "hit_ratio_pct": ratio,
        "pages_from_memory": from_memory,
        "pages_from_disk": from_disk,
    }))
}

/// One counter as a number, or zero when the server does not publish it.
fn read_counter(counters: &IndexMap<String, String>, name: &str) -> i64 {
    counters
        .get(name)
        .and_then(|text| text.trim().parse().ok())
        .unwrap_or_default()
}

/// The time in seconds of the longest statement running right now.
async fn longest_statement(connection: &mut Conn) -> Result<Value> {
    let rows = fetch(
        connection,
        "SELECT MAX(TIME) FROM information_schema.PROCESSLIST WHERE COMMAND <> 'Sleep'",
        Params::Empty,
    )
    .await
    .map_err(|failure| super::observation_failure(failure, "PROCESS", "other-connections"))?;
    Ok(rows
        .first()
        .and_then(|row| row.values().next())
        .cloned()
        .unwrap_or(Value::Null))
}

/// Reads a single value from a statement that returns exactly one.
async fn scalar(connection: &mut Conn, sql: &str) -> Result<Value> {
    let rows = fetch(connection, sql, Params::Empty).await?;
    Ok(rows
        .first()
        .and_then(|row| row.values().next())
        .cloned()
        .unwrap_or(Value::Null))
}

/// The name of one counter row, for a caller reading the answer back.
#[must_use]
pub fn row_name(row: &Row) -> String {
    text_of(cell(row, "name"))
}

/// The change recorded on one counter row.
#[must_use]
pub fn row_delta(row: &Row) -> Option<i64> {
    number_of(cell(row, "delta"))
}

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

    fn reading(pairs: &[(&str, &str)]) -> IndexMap<String, String> {
        pairs
            .iter()
            .map(|(name, value)| ((*name).to_owned(), (*value).to_owned()))
            .collect()
    }

    /// The difference between two readings is what the caller asked for, and
    /// the total is kept beside it rather than replaced by it.
    #[test]
    fn a_counter_reports_both_its_total_and_its_change() {
        let first = reading(&[("Questions", "100")]);
        let second = reading(&[("Questions", "142")]);
        let rows = compare(&first, &second, None);
        assert_eq!(rows.len(), 1);
        assert_eq!(row_name(&rows[0]), "Questions");
        assert_eq!(row_delta(&rows[0]), Some(42));
        assert_eq!(rows[0]["value"], json!("142"));
        assert_eq!(rows[0]["previous"], json!("100"));
    }

    /// A counter that is not a number keeps its text and gets no invented
    /// difference.
    #[test]
    fn a_counter_that_is_not_a_number_gets_no_difference() {
        let first = reading(&[("Rsa_public_key", "-----BEGIN")]);
        let second = reading(&[("Rsa_public_key", "-----BEGIN")]);
        let rows = compare(&first, &second, None);
        assert_eq!(rows[0]["delta"], Value::Null);
    }

    /// A counter absent from the first reading has no difference, because a
    /// missing reading is not a zero reading.
    #[test]
    fn a_counter_absent_from_the_first_reading_gets_no_difference() {
        let rows = compare(&reading(&[]), &reading(&[("New_counter", "5")]), None);
        assert_eq!(rows[0]["delta"], Value::Null);
        assert_eq!(rows[0]["previous"], Value::Null);
    }

    /// The caller's pattern decides which counters reach the answer.
    #[test]
    fn the_pattern_narrows_the_counters() {
        let first = reading(&[("Questions", "1"), ("Threads_connected", "3")]);
        let second = reading(&[("Questions", "9"), ("Threads_connected", "4")]);
        let rows = compare(&first, &second, Some("threads_%"));
        assert_eq!(rows.len(), 1);
        assert_eq!(row_name(&rows[0]), "Threads_connected");
    }

    /// A restart between the readings refuses the difference outright rather
    /// than reporting a negative change as if it were a measurement.
    #[test]
    fn a_restart_between_readings_refuses_the_difference() {
        let first = reading(&[(UPTIME, "9000")]);
        let second = reading(&[(UPTIME, "4")]);
        let failure =
            refuse_across_restart(&first, &second, 5).expect_err("a restart must be refused");
        assert_eq!(failure.exit_number().code(), 11);
        assert!(failure.hint().is_some_and(|hint| hint.contains('5')));
    }

    /// A server that stayed up allows the difference.
    #[test]
    fn a_stable_server_allows_the_difference() {
        let first = reading(&[(UPTIME, "9000")]);
        let second = reading(&[(UPTIME, "9005")]);
        assert!(refuse_across_restart(&first, &second, 5).is_ok());
    }
}