mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Structure discovery: the nineteen commands that read server metadata.
//!
//! Discovery is metadata reading and never changes the server, so a profile
//! marked read-only still answers every command here.

use clap::{Args, Subcommand, ValueEnum};

/// How deep a listing goes.
///
/// A level with a published domain rather than a bare truth value, because the
/// manual publishes both `--detail summary` and `--detail full` and publishes a
/// refusal for a level outside the domain. A truth value cannot carry that
/// refusal: an unknown word beside it is not a level at all, and the argument
/// layer would reject it as an unexpected value rather than as a level nobody
/// offers.
///
/// Two levels and not three. The catalogue entries carry exactly two depths,
/// the short field list and the short one plus its extras, so a third name
/// would promise a depth that does not exist behind it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum Detail {
    /// The fields every form of the listing returns.
    Summary,
    /// Those fields and every extra the catalogue holds.
    Full,
}

impl Detail {
    /// Whether this level asks for the extras as well.
    #[must_use]
    pub const fn is_full(self) -> bool {
        matches!(self, Self::Full)
    }

    /// The level a command asked for, or the one that command defaults to.
    ///
    /// The default belongs to the command and not to the argument type, because
    /// the same type serves a listing whose extras a requirement demands and one
    /// whose extras cost an extra read nobody asked for.
    #[must_use]
    pub fn or_default(asked: Option<Self>, fallback: Self) -> bool {
        asked.unwrap_or(fallback).is_full()
    }
}

/// The nineteen structure commands.
#[derive(Debug, Clone, Subcommand)]
pub enum SchemaCommand {
    /// Compact map of the whole database.
    Map(MapArgs),
    /// List databases.
    Databases,
    /// List tables.
    Tables(TablesArgs),
    /// Describe the columns of a table.
    Columns(DetailedTableArgs),
    /// List foreign keys, optionally flagging those without a supporting index.
    Keys(AdvisableTableArgs),
    /// List indexes, optionally flagging those already covered by another.
    Indexes(AdvisableTableArgs),
    /// List the value restrictions a table imposes, with each condition.
    Checks(DetailedTableArgs),
    /// List views, with a cut for the materialised ones.
    Views(ViewsArgs),
    /// List routines and functions.
    Routines(ScopeArgs),
    /// List triggers.
    Triggers(ScopeArgs),
    /// List scheduled events.
    Events(ScopeArgs),
    /// List sequences.
    Sequences(ScopeArgs),
    /// List partitions.
    Partitions(DetailedTableArgs),
    /// Find an object by name pattern.
    Search(SearchArgs),
    /// Table statistics.
    Stats(DetailedTableArgs),
    /// Textual, re-creatable definition of an object.
    Ddl(DdlArgs),
    /// Exact row count, on demand.
    Count(TableArgs),
    /// Space per database and ranking of the largest objects.
    Size(SizeArgs),
    /// Effective permissions of the connected user.
    Grants,
}

/// How wide and how deep the compact map goes.
#[derive(Debug, Clone, Args)]
pub struct MapArgs {
    /// Include column comments in the map.
    #[arg(long)]
    pub with_comments: bool,
}

/// Listing scoped to a database.
#[derive(Debug, Clone, Args)]
pub struct ScopeArgs {
    /// How deep the listing goes.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
}

/// Table listing, with physical metadata on demand.
#[derive(Debug, Clone, Args)]
pub struct TablesArgs {
    /// How deep the listing goes; the full level adds engine, collation, size
    /// and comment.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
    /// Read every database the credential can see.
    #[arg(long)]
    pub all_databases: bool,
}

/// A command addressing one table.
#[derive(Debug, Clone, Args)]
pub struct TableArgs {
    /// Table name.
    ///
    /// 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 reading is actually run, and carries a code.
    #[arg(long)]
    pub table: Option<String>,
}

/// A command addressing one table, at a depth the caller may choose.
#[derive(Debug, Clone, Args)]
pub struct DetailedTableArgs {
    /// Table name.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`TableArgs::table`].
    #[arg(long)]
    pub table: Option<String>,
    /// How deep the description goes.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
}

/// A table command that can also report structural advice.
#[derive(Debug, Clone, Args)]
pub struct AdvisableTableArgs {
    /// Table name.
    #[arg(long)]
    pub table: Option<String>,
    /// How deep the listing goes.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
    /// Report structure without supporting index; costs extra analysis.
    ///
    /// Asks for this one invocation. A host that wants it on every listing
    /// stores `schema.index_advice` instead, and then this mark adds nothing.
    ///
    /// Published as `--warn`, which is the name the manual carries, with
    /// `--advise` kept as an alias for the form this build served first.
    #[arg(long = "warn", alias = "advise")]
    pub advise: bool,
}

/// View listing, with a cut for materialised views.
#[derive(Debug, Clone, Args)]
pub struct ViewsArgs {
    /// How deep the listing goes.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
    /// Return only materialised views.
    #[arg(long)]
    pub materialized: bool,
}

/// Object search across several kinds.
#[derive(Debug, Clone, Args)]
pub struct SearchArgs {
    /// Name pattern, written as a bare word.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`TableArgs::table`].
    pub pattern: Option<String>,
    /// Name pattern, written as a flag.
    ///
    /// The manual publishes the pattern this way and this build served it as a
    /// bare word, so both are accepted and the flag wins when the two disagree.
    /// A caller who writes the manual's own example must not be refused.
    #[arg(long, value_name = "PATTERN")]
    pub like: Option<String>,
    /// Restrict to these object kinds.
    ///
    /// Published as `--type`, which is the name the manual carries. `--kind` is
    /// accepted as well, because that is the name this build served before the
    /// two were reconciled and an argv that already worked must go on working.
    #[arg(long = "type", alias = "kind", value_delimiter = ',')]
    pub kind: Vec<String>,
    /// How deep each match goes.
    #[arg(long, value_name = "LEVEL")]
    pub detail: Option<Detail>,
}

/// The definition of one named object.
#[derive(Debug, Clone, Args)]
pub struct DdlArgs {
    /// Object name.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`TableArgs::table`].
    pub object: Option<String>,
    /// Object kind.
    #[arg(long)]
    pub kind: Option<String>,
}

/// Space report.
#[derive(Debug, Clone, Args)]
pub struct SizeArgs {
    /// How many of the largest objects to rank.
    #[arg(long)]
    pub top: Option<usize>,
}