Skip to main content

mariadb_cli/cli/
data.rs

1//! Moving data in and out of the server.
2
3use clap::{Args, Subcommand, ValueEnum};
4
5/// What a copy or a load does when one item is refused.
6///
7/// A domain rather than a truth value, because the manual publishes the two
8/// words and publishes them on both commands. A caller who has to guess which
9/// way a bare mark points is a caller who finds out by losing the load.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
11pub enum OnError {
12    /// Stop at the first refusal and leave nothing half done.
13    Stop,
14    /// Carry on, and report every refusal with its own reason.
15    Skip,
16}
17
18impl OnError {
19    /// Whether this policy stops the whole run at the first refusal.
20    #[must_use]
21    pub const fn stops(self) -> bool {
22        matches!(self, Self::Stop)
23    }
24}
25
26/// The two data movement commands.
27#[derive(Debug, Clone, Subcommand)]
28pub enum DataCommand {
29    /// Re-creatable logical copy.
30    Export(ExportArgs),
31    /// Load a tabular file.
32    Import(ImportArgs),
33}
34
35/// Producing a logical copy.
36///
37/// Consistency across tables comes from a transaction with a consistent
38/// snapshot, so no reader or writer is ever blocked. When the storage engine
39/// cannot provide one, the copy still runs and the gap is declared.
40#[derive(Debug, Clone, Args)]
41pub struct ExportArgs {
42    /// Where to write the copy.
43    ///
44    /// Named `--to` and NOT `--output`, because `--output` is a global flag
45    /// meaning "write this invocation's answer to a file". Two declarations of
46    /// one long name are matched by the argument layer as a single argument, so
47    /// the value reached both: the copy was written to that path and then the
48    /// single output destination wrote its own receipt over it, destroying the
49    /// copy. The two destinations are separate things and now say so.
50    ///
51    /// Optional to the argument layer and required to the command. Publishing
52    /// the contract must cost nothing, and a caller asking what this command
53    /// answers should not have to invent a destination first. Absence is
54    /// refused where the copy is actually run, and carries a code.
55    #[arg(long = "to", value_name = "FILE")]
56    pub to: Option<std::path::PathBuf>,
57    /// Restrict to these tables.
58    #[arg(long, value_delimiter = ',')]
59    pub table: Vec<String>,
60    /// Copy the structure only, without any row.
61    #[arg(long)]
62    pub structure_only: bool,
63    /// Ceiling on the volume of the copy, in bytes.
64    ///
65    /// Reaching it removes the partial file rather than leaving it where the
66    /// finished one belongs, so a copy that stopped early is never mistaken
67    /// for a copy that finished.
68    #[arg(long, value_name = "N")]
69    pub max_bytes: Option<usize>,
70}
71
72/// Loading a tabular file.
73///
74/// The file is opened by the caller and never by the server, so the server's
75/// file privilege is not involved. Batches commit as they go and the resume
76/// mark tells where to continue after an interruption.
77#[derive(Debug, Clone, Args)]
78pub struct ImportArgs {
79    /// File to read.
80    ///
81    /// Optional to the argument layer and required to the command, for the
82    /// reason given on [`ExportArgs::to`].
83    #[arg(long)]
84    pub file: Option<std::path::PathBuf>,
85    /// Table to load into.
86    ///
87    /// Optional to the argument layer and required to the command, for the
88    /// same reason as the file.
89    #[arg(long)]
90    pub table: Option<String>,
91    /// Rows per committed batch; defaults to the stored key.
92    #[arg(long)]
93    pub batch_size: Option<usize>,
94    /// Continue from this row offset.
95    #[arg(long)]
96    pub resume_from: Option<u64>,
97    /// Field separator of the file.
98    #[arg(long)]
99    pub separator: Option<char>,
100    /// The file carries a header row.
101    #[arg(long)]
102    pub header: bool,
103    /// What a refused row does to the rest of the load.
104    ///
105    /// Defaults to the stored `data.stop_on_refusal`, so a host that has
106    /// decided once does not decide again on every invocation.
107    #[arg(long = "on-error", value_name = "POLICY")]
108    pub on_error: Option<OnError>,
109}