mariadb_cli/cli/query.rs
1//! Reading and changing: the ten commands that send statements to the server.
2//!
3//! Every statement here travels as a prepared statement. The server refuses a
4//! prepared text carrying more than one statement, which puts the multiple
5//! command refusal on the server side instead of relying on the client reading
6//! the text correctly.
7
8use clap::{Args, Subcommand};
9
10/// The ten query commands.
11#[derive(Debug, Clone, Subcommand)]
12pub enum QueryCommand {
13 /// Run a read or a change, according to the classification.
14 Run(RunArgs),
15 /// Sample the first rows of a table.
16 Sample(SampleArgs),
17 /// Plan without executing, with optimiser reasoning on demand.
18 Explain(ExplainArgs),
19 /// Real measurement, treated as a change because it executes.
20 Analyze(StatementArgs),
21 /// Plan of a statement already running.
22 Plan(PlanArgs),
23 /// Physical origin of the result columns.
24 Lineage(StatementArgs),
25 /// Run a file of statements.
26 File(FileArgs),
27 /// Group statements in one atomic block.
28 Tx(TxArgs),
29 /// Call a stored routine and return its output parameters.
30 Call(CallArgs),
31 /// Store and run a named statement with typed parameters.
32 Named(NamedArgs),
33}
34
35/// A statement and the values bound to it.
36#[derive(Debug, Clone, Args)]
37pub struct StatementArgs {
38 /// The statement text; omit to read it from the standard input.
39 pub statement: Option<String>,
40
41 /// Read the statement from the standard input.
42 #[arg(long, conflicts_with = "statement")]
43 pub stdin: bool,
44
45 /// A value bound to a parameter marker; repeatable and positional in order.
46 #[arg(long = "param", value_name = "VALUE")]
47 pub params: Vec<String>,
48}
49
50/// Running one statement.
51#[derive(Debug, Clone, Args)]
52pub struct RunArgs {
53 /// The statement, wherever it was read from.
54 #[command(flatten)]
55 pub statement: StatementArgs,
56}
57
58/// Sampling a table.
59#[derive(Debug, Clone, Args)]
60pub struct SampleArgs {
61 /// Table to sample.
62 ///
63 /// Optional to the argument layer and required to the command. Publishing
64 /// the contract must cost nothing, and a caller asking what this command
65 /// answers should not have to name a table first. Absence is refused where
66 /// the sampling is actually run, and carries a code.
67 #[arg(long)]
68 pub table: Option<String>,
69 /// How many rows to return.
70 #[arg(long)]
71 pub rows: Option<usize>,
72}
73
74/// Obtaining a plan without executing.
75#[derive(Debug, Clone, Args)]
76pub struct ExplainArgs {
77 /// The statement whose plan is wanted, never executed.
78 #[command(flatten)]
79 pub statement: StatementArgs,
80
81 /// Also return the optimiser's decision trace.
82 #[arg(long)]
83 pub trace: bool,
84}
85
86/// Plan of a statement already running.
87#[derive(Debug, Clone, Args)]
88pub struct PlanArgs {
89 /// Connection identifier of the running statement.
90 ///
91 /// Optional to the argument layer and required to the command, for the
92 /// reason given on [`SampleArgs::table`].
93 ///
94 /// Published as `--connection`, which is the name the manual carries, with
95 /// `--id` kept as an alias for the form this build served first.
96 #[arg(long = "connection", alias = "id")]
97 pub id: Option<u64>,
98}
99
100/// Running a file of statements.
101#[derive(Debug, Clone, Args)]
102pub struct FileArgs {
103 /// File to run.
104 ///
105 /// Optional to the argument layer and required to the command, for the
106 /// reason given on [`SampleArgs::table`].
107 pub path: Option<std::path::PathBuf>,
108 /// Statement separator; defaults to the stored key.
109 #[arg(long)]
110 pub delimiter: Option<String>,
111 /// What a failed statement does to the rest of the file.
112 ///
113 /// Stopping is the default and always was, because a statement that failed
114 /// may well be the one the rest depended on. Skipping is for the file whose
115 /// statements are independent of one another, where one bad line should not
116 /// cost the other nine hundred.
117 #[arg(long = "on-error", value_name = "POLICY")]
118 pub on_error: Option<crate::cli::data::OnError>,
119}
120
121/// Grouping statements in one atomic block.
122#[derive(Debug, Clone, Args)]
123pub struct TxArgs {
124 /// A statement of the block; repeatable and run in order.
125 #[arg(long = "statement", value_name = "SQL")]
126 pub statements: Vec<String>,
127 /// Read the statements from the standard input, one per line.
128 #[arg(long, conflicts_with = "statements")]
129 pub stdin: bool,
130 /// Read the statements from a file, one per line.
131 ///
132 /// The manual publishes the block this way and this build offered only the
133 /// statement by statement form and the standard input. A caller with the
134 /// block already in a file had to take it apart to pass it in.
135 #[arg(long, value_name = "PATH", conflicts_with_all = ["statements", "stdin"])]
136 pub file: Option<std::path::PathBuf>,
137}
138
139/// Calling a stored routine.
140#[derive(Debug, Clone, Args)]
141pub struct CallArgs {
142 /// Routine name.
143 ///
144 /// Optional to the argument layer and required to the command, for the
145 /// reason given on [`SampleArgs::table`].
146 pub routine: Option<String>,
147 /// A value bound to a routine parameter; repeatable and positional in order.
148 ///
149 /// The values fill the positions that are NOT outputs, in the order they
150 /// are written, because an output parameter carries nothing in.
151 #[arg(long = "param", value_name = "VALUE")]
152 pub params: Vec<String>,
153 /// A parameter whose final value is wanted back; repeatable.
154 #[arg(long = "out", value_name = "NAME")]
155 pub outputs: Vec<String>,
156}
157
158/// Storing and running a named statement.
159#[derive(Debug, Clone, Args)]
160pub struct NamedArgs {
161 /// Which of the four things to do with a named statement.
162 #[command(subcommand)]
163 pub action: NamedAction,
164}
165
166/// What to do with a named statement.
167///
168/// The name and the statement text stay plain strings here, and the argument
169/// layer no longer demands them, so publishing the contract of any action costs
170/// nothing. The empty string stands for absence, because nothing can be kept,
171/// removed or run under an empty name, and the refusal is raised where the
172/// action is actually served.
173#[derive(Debug, Clone, Subcommand)]
174pub enum NamedAction {
175 /// Store a statement under a name.
176 Save {
177 /// Name to store it under.
178 #[arg(default_value = "")]
179 name: String,
180 /// The statement text.
181 #[arg(default_value = "")]
182 statement: String,
183 /// A typed parameter declaration, as `name:type`.
184 #[arg(long = "param", value_name = "NAME:TYPE")]
185 params: Vec<String>,
186 /// Ceiling on rows this stored statement may return.
187 #[arg(long)]
188 max_rows: Option<usize>,
189 },
190 /// List stored statements.
191 List,
192 /// Delete a stored statement.
193 Remove {
194 /// Name to delete.
195 #[arg(default_value = "")]
196 name: String,
197 },
198 /// Run a stored statement.
199 Run {
200 /// Name to run.
201 #[arg(default_value = "")]
202 name: String,
203 /// A value bound to a declared parameter, as `name=value`.
204 ///
205 /// The manual publishes this as `--param`, so that is the name served.
206 /// `--arg` is kept as an alias because this build served it first and
207 /// an argv that already worked must go on working.
208 #[arg(long = "param", alias = "arg", value_name = "NAME=VALUE")]
209 args: Vec<String>,
210 },
211}
212
213impl NamedAction {
214 /// The published name of this action, as the command map lists it.
215 ///
216 /// Each action is a published command of its own, so each names itself.
217 /// Answering with the family name, as this once did, meant a caller asking
218 /// what `query named run` returns was told about `query named` instead.
219 #[must_use]
220 pub const fn published_name(&self) -> &'static str {
221 match self {
222 Self::Save { .. } => "query named save",
223 Self::List => "query named list",
224 Self::Remove { .. } => "query named remove",
225 Self::Run { .. } => "query named run",
226 }
227 }
228}