mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! The published command surface.
//!
//! Every command a caller may run appears here, and nothing appears here that
//! the caller may not run. `meta commands` walks this tree, so the published
//! surface and the real surface cannot drift apart.

pub mod config;
pub mod conn;
pub mod data;
pub mod globals;
pub mod history;
pub mod meta;
pub mod query;
pub mod schema;
pub mod server;

use clap::{Parser, Subcommand};

/// One-shot client for MariaDB servers.
///
/// The process is born, does its work and dies within a single invocation.
#[derive(Debug, Parser)]
#[command(
    name = "mariadb-cli",
    version,
    about = "One-shot agent-native command line client for MariaDB servers",
    long_about = None,
    propagate_version = true,
    disable_help_subcommand = true,
)]
pub struct Cli {
    /// The marks that mean the same thing on every command.
    #[command(flatten)]
    pub globals: globals::GlobalFlags,

    /// The one command this invocation runs.
    #[command(subcommand)]
    pub command: Command,
}

/// The eight command families.
#[derive(Debug, Clone, Subcommand)]
pub enum Command {
    /// Connection profiles.
    #[command(subcommand)]
    Conn(conn::ConnCommand),

    /// Structure of the database.
    #[command(subcommand)]
    Schema(schema::SchemaCommand),

    /// Reading and changing.
    #[command(subcommand)]
    Query(query::QueryCommand),

    /// Moving data in and out.
    #[command(subcommand)]
    Data(data::DataCommand),

    /// What the server is doing.
    #[command(subcommand)]
    Server(server::ServerCommand),

    /// Version history of tables that keep one.
    #[command(subcommand)]
    History(history::HistoryCommand),

    /// Stored configuration.
    #[command(subcommand)]
    Config(config::ConfigCommand),

    /// Self-description.
    #[command(subcommand)]
    Meta(meta::MetaCommand),
}

impl Command {
    /// The published name of this command, as it appears in the surface map.
    ///
    /// This is the identifier the output envelope carries and the one
    /// `meta schema --command` accepts, so both always agree with the tree.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Conn(inner) => inner.published_name(),
            Self::Schema(inner) => inner.published_name(),
            Self::Query(inner) => inner.published_name(),
            Self::Data(inner) => inner.published_name(),
            Self::Server(inner) => inner.published_name(),
            Self::History(inner) => inner.published_name(),
            Self::Config(inner) => inner.published_name(),
            Self::Meta(inner) => inner.published_name(),
        }
    }
}

impl conn::ConnCommand {
    /// The published name of this profile command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Add(_) => "conn add",
            Self::List => "conn list",
            Self::Show(_) => "conn show",
            Self::Edit(_) => "conn edit",
            Self::Remove(_) => "conn remove",
            Self::Test(_) => "conn test",
            Self::Default(_) => "conn default",
        }
    }
}

impl schema::SchemaCommand {
    /// The published name of this structure command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Map(_) => "schema map",
            Self::Databases => "schema databases",
            Self::Tables(_) => "schema tables",
            Self::Columns(_) => "schema columns",
            Self::Keys(_) => "schema keys",
            Self::Indexes(_) => "schema indexes",
            Self::Checks(_) => "schema checks",
            Self::Views(_) => "schema views",
            Self::Routines(_) => "schema routines",
            Self::Triggers(_) => "schema triggers",
            Self::Events(_) => "schema events",
            Self::Sequences(_) => "schema sequences",
            Self::Partitions(_) => "schema partitions",
            Self::Search(_) => "schema search",
            Self::Stats(_) => "schema stats",
            Self::Ddl(_) => "schema ddl",
            Self::Count(_) => "schema count",
            Self::Size(_) => "schema size",
            Self::Grants => "schema grants",
        }
    }
}

impl query::QueryCommand {
    /// The published name of this query command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Run(_) => "query run",
            Self::Sample(_) => "query sample",
            Self::Explain(_) => "query explain",
            Self::Analyze(_) => "query analyze",
            Self::Plan(_) => "query plan",
            Self::Lineage(_) => "query lineage",
            Self::File(_) => "query file",
            Self::Tx(_) => "query tx",
            Self::Call(_) => "query call",
            // Named by its action, not by its family. The four actions are
            // four published commands, so answering all four with the contract
            // of `query named` told a caller about a command it had not asked
            // about, and anything branching on the contract's `command` field
            // branched on the wrong name.
            Self::Named(args) => args.action.published_name(),
        }
    }
}

impl data::DataCommand {
    /// The published name of this data command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Export(_) => "data export",
            Self::Import(_) => "data import",
        }
    }
}

impl server::ServerCommand {
    /// The published name of this server command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Status(_) => "server status",
            Self::Variables(_) => "server variables",
            Self::Processes(_) => "server processes",
            Self::Replica => "server replica",
            Self::Kill(_) => "server kill",
            Self::Capabilities => "server capabilities",
            Self::Queries(_) => "server queries",
            Self::Locks => "server locks",
        }
    }
}

impl history::HistoryCommand {
    /// The published name of this history command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::AsOf(_) => "history as-of",
            Self::Between(_) => "history between",
            Self::Tables(_) => "history tables",
        }
    }
}

impl config::ConfigCommand {
    /// The published name of this configuration command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Set(_) => "config set",
            Self::Get(_) => "config get",
            Self::List(_) => "config list",
            Self::Path => "config path",
            Self::Unset(_) => "config unset",
            Self::Doctor => "config doctor",
        }
    }
}

impl meta::MetaCommand {
    /// The published name of this discovery command.
    #[must_use]
    pub const fn published_name(&self) -> &'static str {
        match self {
            Self::Commands(_) => "meta commands",
            Self::Schema(_) => "meta schema",
            Self::Version => "meta version",
            Self::Manual(_) => "meta manual",
            Self::Completions(_) => "meta completions",
        }
    }
}

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

    /// The tree parses and every flag has a long name, as the contract requires.
    #[test]
    fn the_command_tree_is_well_formed() {
        Cli::command().debug_assert();
    }

    /// The surface carries exactly the fifty-nine commands the map publishes.
    #[test]
    fn the_surface_has_the_published_command_count() {
        fn leaves(command: &clap::Command) -> usize {
            let mut total = 0;
            for sub in command.get_subcommands() {
                if sub.get_subcommands().next().is_some() {
                    total += leaves(sub);
                } else {
                    total += 1;
                }
            }
            total
        }
        // `query named` carries four actions of its own; the map counts it as
        // one command, so its three extra leaves are discounted here.
        const NAMED_EXTRA_LEAVES: usize = 3;
        assert_eq!(leaves(&Cli::command()) - NAMED_EXTRA_LEAVES, 60);
    }
}