mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Moving data in and out of the server.

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

/// What a copy or a load does when one item is refused.
///
/// A domain rather than a truth value, because the manual publishes the two
/// words and publishes them on both commands. A caller who has to guess which
/// way a bare mark points is a caller who finds out by losing the load.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum OnError {
    /// Stop at the first refusal and leave nothing half done.
    Stop,
    /// Carry on, and report every refusal with its own reason.
    Skip,
}

impl OnError {
    /// Whether this policy stops the whole run at the first refusal.
    #[must_use]
    pub const fn stops(self) -> bool {
        matches!(self, Self::Stop)
    }
}

/// The two data movement commands.
#[derive(Debug, Clone, Subcommand)]
pub enum DataCommand {
    /// Re-creatable logical copy.
    Export(ExportArgs),
    /// Load a tabular file.
    Import(ImportArgs),
}

/// Producing a logical copy.
///
/// Consistency across tables comes from a transaction with a consistent
/// snapshot, so no reader or writer is ever blocked. When the storage engine
/// cannot provide one, the copy still runs and the gap is declared.
#[derive(Debug, Clone, Args)]
pub struct ExportArgs {
    /// Where to write the copy.
    ///
    /// Named `--to` and NOT `--output`, because `--output` is a global flag
    /// meaning "write this invocation's answer to a file". Two declarations of
    /// one long name are matched by the argument layer as a single argument, so
    /// the value reached both: the copy was written to that path and then the
    /// single output destination wrote its own receipt over it, destroying the
    /// copy. The two destinations are separate things and now say so.
    ///
    /// 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 invent a destination first. Absence is
    /// refused where the copy is actually run, and carries a code.
    #[arg(long = "to", value_name = "FILE")]
    pub to: Option<std::path::PathBuf>,
    /// Restrict to these tables.
    #[arg(long, value_delimiter = ',')]
    pub table: Vec<String>,
    /// Copy the structure only, without any row.
    #[arg(long)]
    pub structure_only: bool,
    /// Ceiling on the volume of the copy, in bytes.
    ///
    /// Reaching it removes the partial file rather than leaving it where the
    /// finished one belongs, so a copy that stopped early is never mistaken
    /// for a copy that finished.
    #[arg(long, value_name = "N")]
    pub max_bytes: Option<usize>,
}

/// Loading a tabular file.
///
/// The file is opened by the caller and never by the server, so the server's
/// file privilege is not involved. Batches commit as they go and the resume
/// mark tells where to continue after an interruption.
#[derive(Debug, Clone, Args)]
pub struct ImportArgs {
    /// File to read.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// reason given on [`ExportArgs::to`].
    #[arg(long)]
    pub file: Option<std::path::PathBuf>,
    /// Table to load into.
    ///
    /// Optional to the argument layer and required to the command, for the
    /// same reason as the file.
    #[arg(long)]
    pub table: Option<String>,
    /// Rows per committed batch; defaults to the stored key.
    #[arg(long)]
    pub batch_size: Option<usize>,
    /// Continue from this row offset.
    #[arg(long)]
    pub resume_from: Option<u64>,
    /// Field separator of the file.
    #[arg(long)]
    pub separator: Option<char>,
    /// The file carries a header row.
    #[arg(long)]
    pub header: bool,
    /// What a refused row does to the rest of the load.
    ///
    /// Defaults to the stored `data.stop_on_refusal`, so a host that has
    /// decided once does not decide again on every invocation.
    #[arg(long = "on-error", value_name = "POLICY")]
    pub on_error: Option<OnError>,
}