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}