mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Reading and changing: the ten commands that send statements to the server.
//!
//! Every statement here travels as a prepared statement. The server refuses a
//! prepared text carrying more than one statement, which puts the multiple
//! command refusal on the server side instead of relying on the client reading
//! the text correctly.

use clap::{Args, Subcommand};

/// The ten query commands.
#[derive(Debug, Clone, Subcommand)]
pub enum QueryCommand {
    /// Run a read or a change, according to the classification.
    Run(RunArgs),
    /// Sample the first rows of a table.
    Sample(SampleArgs),
    /// Plan without executing, with optimiser reasoning on demand.
    Explain(ExplainArgs),
    /// Real measurement, treated as a change because it executes.
    Analyze(StatementArgs),
    /// Plan of a statement already running.
    Plan(PlanArgs),
    /// Physical origin of the result columns.
    Lineage(StatementArgs),
    /// Run a file of statements.
    File(FileArgs),
    /// Group statements in one atomic block.
    Tx(TxArgs),
    /// Call a stored routine and return its output parameters.
    Call(CallArgs),
    /// Store and run a named statement with typed parameters.
    Named(NamedArgs),
}

/// A statement and the values bound to it.
#[derive(Debug, Clone, Args)]
pub struct StatementArgs {
    /// The statement text; omit to read it from the standard input.
    pub statement: Option<String>,

    /// Read the statement from the standard input.
    #[arg(long, conflicts_with = "statement")]
    pub stdin: bool,

    /// A value bound to a parameter marker; repeatable and positional in order.
    #[arg(long = "param", value_name = "VALUE")]
    pub params: Vec<String>,
}

/// Running one statement.
#[derive(Debug, Clone, Args)]
pub struct RunArgs {
    /// The statement, wherever it was read from.
    #[command(flatten)]
    pub statement: StatementArgs,
}

/// Sampling a table.
#[derive(Debug, Clone, Args)]
pub struct SampleArgs {
    /// Table to sample.
    ///
    /// Optional to the argument layer and required to the command. Publishing
    /// the contract must cost nothing, and a caller asking what this command
    /// answers should not have to name a table first. Absence is refused where
    /// the sampling is actually run, and carries a code.
    #[arg(long)]
    pub table: Option<String>,
    /// How many rows to return.
    #[arg(long)]
    pub rows: Option<usize>,
}

/// Obtaining a plan without executing.
#[derive(Debug, Clone, Args)]
pub struct ExplainArgs {
    /// The statement whose plan is wanted, never executed.
    #[command(flatten)]
    pub statement: StatementArgs,

    /// Also return the optimiser's decision trace.
    #[arg(long)]
    pub trace: bool,
}

/// Plan of a statement already running.
#[derive(Debug, Clone, Args)]
pub struct PlanArgs {
    /// Connection identifier of the running statement.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`SampleArgs::table`].
    ///
    /// Published as `--connection`, which is the name the manual carries, with
    /// `--id` kept as an alias for the form this build served first.
    #[arg(long = "connection", alias = "id")]
    pub id: Option<u64>,
}

/// Running a file of statements.
#[derive(Debug, Clone, Args)]
pub struct FileArgs {
    /// File to run.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`SampleArgs::table`].
    pub path: Option<std::path::PathBuf>,
    /// Statement separator; defaults to the stored key.
    #[arg(long)]
    pub delimiter: Option<String>,
    /// What a failed statement does to the rest of the file.
    ///
    /// Stopping is the default and always was, because a statement that failed
    /// may well be the one the rest depended on. Skipping is for the file whose
    /// statements are independent of one another, where one bad line should not
    /// cost the other nine hundred.
    #[arg(long = "on-error", value_name = "POLICY")]
    pub on_error: Option<crate::cli::data::OnError>,
}

/// Grouping statements in one atomic block.
#[derive(Debug, Clone, Args)]
pub struct TxArgs {
    /// A statement of the block; repeatable and run in order.
    #[arg(long = "statement", value_name = "SQL")]
    pub statements: Vec<String>,
    /// Read the statements from the standard input, one per line.
    #[arg(long, conflicts_with = "statements")]
    pub stdin: bool,
    /// Read the statements from a file, one per line.
    ///
    /// The manual publishes the block this way and this build offered only the
    /// statement by statement form and the standard input. A caller with the
    /// block already in a file had to take it apart to pass it in.
    #[arg(long, value_name = "PATH", conflicts_with_all = ["statements", "stdin"])]
    pub file: Option<std::path::PathBuf>,
}

/// Calling a stored routine.
#[derive(Debug, Clone, Args)]
pub struct CallArgs {
    /// Routine name.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`SampleArgs::table`].
    pub routine: Option<String>,
    /// A value bound to a routine parameter; repeatable and positional in order.
    ///
    /// The values fill the positions that are NOT outputs, in the order they
    /// are written, because an output parameter carries nothing in.
    #[arg(long = "param", value_name = "VALUE")]
    pub params: Vec<String>,
    /// A parameter whose final value is wanted back; repeatable.
    #[arg(long = "out", value_name = "NAME")]
    pub outputs: Vec<String>,
}

/// Storing and running a named statement.
#[derive(Debug, Clone, Args)]
pub struct NamedArgs {
    /// Which of the four things to do with a named statement.
    #[command(subcommand)]
    pub action: NamedAction,
}

/// What to do with a named statement.
///
/// The name and the statement text stay plain strings here, and the argument
/// layer no longer demands them, so publishing the contract of any action costs
/// nothing. The empty string stands for absence, because nothing can be kept,
/// removed or run under an empty name, and the refusal is raised where the
/// action is actually served.
#[derive(Debug, Clone, Subcommand)]
pub enum NamedAction {
    /// Store a statement under a name.
    Save {
        /// Name to store it under.
        #[arg(default_value = "")]
        name: String,
        /// The statement text.
        #[arg(default_value = "")]
        statement: String,
        /// A typed parameter declaration, as `name:type`.
        #[arg(long = "param", value_name = "NAME:TYPE")]
        params: Vec<String>,
        /// Ceiling on rows this stored statement may return.
        #[arg(long)]
        max_rows: Option<usize>,
    },
    /// List stored statements.
    List,
    /// Delete a stored statement.
    Remove {
        /// Name to delete.
        #[arg(default_value = "")]
        name: String,
    },
    /// Run a stored statement.
    Run {
        /// Name to run.
        #[arg(default_value = "")]
        name: String,
        /// A value bound to a declared parameter, as `name=value`.
        ///
        /// The manual publishes this as `--param`, so that is the name served.
        /// `--arg` is kept as an alias because this build served it first and
        /// an argv that already worked must go on working.
        #[arg(long = "param", alias = "arg", value_name = "NAME=VALUE")]
        args: Vec<String>,
    },
}

impl NamedAction {
    /// The published name of this action, as the command map lists it.
    ///
    /// Each action is a published command of its own, so each names itself.
    /// Answering with the family name, as this once did, meant a caller asking
    /// what `query named run` returns was told about `query named` instead.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Save { .. } => "query named save",
            Self::List => "query named list",
            Self::Remove { .. } => "query named remove",
            Self::Run { .. } => "query named run",
        }
    }
}