mariadb_cli/cli/conn.rs
1//! Connection profiles: the named destinations the product talks to.
2
3use clap::{Args, Subcommand};
4
5/// The seven profile lifecycle commands.
6#[derive(Debug, Clone, Subcommand)]
7pub enum ConnCommand {
8 /// Create a named profile.
9 Add(AddArgs),
10 /// List profiles without revealing any secret.
11 List,
12 /// Show one profile with its secret redacted.
13 Show(NameArgs),
14 /// Change a field of an existing profile.
15 Edit(EditArgs),
16 /// Delete a profile and the secret it holds.
17 Remove(NameArgs),
18 /// Open, confirm and close the connection.
19 Test(TestArgs),
20 /// Set which profile applies without an explicit choice.
21 Default(NameArgs),
22}
23
24/// A command addressing one profile by name.
25///
26/// The name is optional to the argument layer and required to the command.
27/// Publishing the contract must cost nothing, and a caller asking what this
28/// command answers should not have to invent a profile first. Absence is
29/// refused where the profile is actually touched, and carries a code.
30#[derive(Debug, Clone, Args)]
31pub struct NameArgs {
32 /// Profile name.
33 pub name: Option<String>,
34}
35
36/// Fields accepted when creating a profile.
37///
38/// The secret never travels as a flag value, because a flag value is visible
39/// in the process list of the whole machine.
40// Allowed: a command line offers independent switches, and clap builds
41// this record field by field from them. Folding them into a nested
42// type would publish a grouping the manual does not have and change
43// the path every reader writes, for no gain to the caller.
44#[allow(clippy::struct_excessive_bools)]
45#[derive(Debug, Clone, Args)]
46pub struct AddArgs {
47 /// Profile name.
48 ///
49 /// Optional to the argument layer and required to the command, for the
50 /// reason given on [`NameArgs`].
51 pub name: Option<String>,
52
53 /// Server host.
54 #[arg(long)]
55 pub host: Option<String>,
56
57 /// Server port.
58 #[arg(long)]
59 pub port: Option<u16>,
60
61 /// Local socket path, preferred over the network when present.
62 ///
63 /// Also spelled `--pipe`, which is the name the manual publishes for the
64 /// same thing on the local channel Windows offers. The requirement number
65 /// is deliberately not written here: a number in a comment counts as a
66 /// citation to the coverage walk, and that requirement is still waiting on
67 /// a host this suite does not have. Naming it would discharge it.
68 ///
69 /// One field carries both spellings, deliberately:
70 /// the driver has a single setting for it, documented as "path to unix
71 /// socket (or named pipe on Windows)", so two fields would be two names
72 /// for one destination and the caller could set one while the work read
73 /// the other. That is precisely how `--db` and `--database` came to lose a
74 /// parameter in silence, and an alias cannot do it.
75 #[arg(long, alias = "pipe")]
76 pub socket: Option<std::path::PathBuf>,
77
78 /// User the credential belongs to.
79 #[arg(long)]
80 pub user: Option<String>,
81
82 /// Read the secret from the standard input.
83 #[arg(long)]
84 pub password_stdin: bool,
85
86 /// Fix the database, so the profile stops taking a database parameter.
87 ///
88 /// The database itself is named by the global `--database`, which the
89 /// manual publishes for this command. A second local flag for the same
90 /// idea used to sit here and it silently won: the global absorbed the
91 /// value the caller wrote and the local field it filled was a different
92 /// one, so `conn add p --database loja` stored no database at all and
93 /// still succeeded.
94 ///
95 /// Takes an optional value, like the two truth values below it. Creating a
96 /// profile has no third state to carry — there is nothing stored yet to
97 /// leave alone — so `--pin-database false` and leaving it out mean the same
98 /// thing here. It accepts the value anyway, because the alternative was
99 /// measured and is worse: on this one command `--require-tls true` was
100 /// accepted while `--pin-database true` ended in 2 with `unexpected
101 /// argument 'true'`, a message that names the value rather than the flag
102 /// and leaves the caller to guess which of three siblings takes one. The
103 /// spelling `conn edit` publishes has to work here too, or the caller
104 /// learns a form that breaks when they move it one command sideways.
105 #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
106 pub pin_database: Option<bool>,
107
108 /// Declared authentication method.
109 #[arg(long)]
110 pub auth: Option<String>,
111
112 /// Client certificate presented to the server.
113 #[arg(long)]
114 pub client_cert: Option<std::path::PathBuf>,
115
116 /// Key matching the client certificate.
117 #[arg(long)]
118 pub client_key: Option<std::path::PathBuf>,
119
120 /// Authority used to verify the server certificate.
121 #[arg(long)]
122 pub ca: Option<std::path::PathBuf>,
123
124 /// Refuse to open unless the channel is encrypted.
125 ///
126 /// Three states, because two cannot carry the answer. Written bare it
127 /// demands encryption, written `--require-tls false` it states this
128 /// destination does not, and left out it says nothing and lets the stored
129 /// `conn.require_tls` decide. A bare truth value here would make the stored
130 /// key unbeatable, which is the precedence the product publishes inverted.
131 #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
132 pub require_tls: Option<bool>,
133
134 /// Session adjustments applied when opening.
135 #[arg(long, value_name = "SETTING")]
136 pub session_setup: Vec<String>,
137
138 /// Refuse any change through this profile.
139 ///
140 /// Takes an optional value for the reason given on `--pin-database` above:
141 /// creating a profile has no third state, but the spelling has to match the
142 /// one `conn edit` publishes.
143 #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
144 pub read_only_profile: Option<bool>,
145
146 /// Confirm the connection right away.
147 #[arg(long)]
148 pub check: bool,
149}
150
151/// Fields accepted when editing a profile.
152#[derive(Debug, Clone, Args)]
153pub struct EditArgs {
154 /// Profile name.
155 ///
156 /// Optional to the argument layer and required to the command, for the
157 /// reason given on [`NameArgs`].
158 pub name: Option<String>,
159
160 /// The fields this edit may change.
161 #[command(flatten)]
162 pub fields: EditableFields,
163}
164
165/// Every field an edit may change.
166#[derive(Debug, Clone, Args)]
167pub struct EditableFields {
168 /// Server host.
169 #[arg(long)]
170 pub host: Option<String>,
171 /// Server port.
172 #[arg(long)]
173 pub port: Option<u16>,
174 /// Local socket path, also spelled `--pipe` for the reason given on
175 /// [`AddArgs`].
176 #[arg(long, alias = "pipe")]
177 pub socket: Option<std::path::PathBuf>,
178 /// User the credential belongs to.
179 #[arg(long)]
180 pub user: Option<String>,
181 /// Read a new secret from the standard input.
182 #[arg(long)]
183 pub password_stdin: bool,
184 /// Fix the database, so the profile stops taking a database parameter.
185 ///
186 /// Three states rather than two, which every truth value an edit may write
187 /// carries here: written bare it fixes the database, written
188 /// `--pin-database false` it releases it, and left out it changes nothing.
189 /// Two states would make an edit that names one field reset the other, so
190 /// "not mentioned" has to be a value the field can hold.
191 ///
192 /// # A stated departure
193 ///
194 /// The project's own guidance on this argument library says never to take a
195 /// truth value as `Option<bool>` and to use `bool`. Every truth value in
196 /// this struct departs from it, deliberately, and the reason is the sentence
197 /// above: that guidance is written for a flag that answers "was this
198 /// asked for", where two states are all there is to say. These answer a
199 /// different question — "should this field change, and to what" — and it
200 /// has three answers. Collapsing it would not simplify the type, it would
201 /// silently delete stored policy on every edit that did not restate it.
202 ///
203 /// The same guidance offers a way to get three states without this type: a
204 /// pair of plain `bool` flags, `--pin-database` and `--no-pin-database`,
205 /// each overriding the other, where writing neither is the third state.
206 /// That works, and it is declined on size rather than on correctness. The
207 /// three editable truth values here would become six flags, in a product
208 /// whose FR-053 publishes its own surface for an agent to read and whose
209 /// whole argument is that a smaller answer is a better one. Doubling the
210 /// surface to avoid one wrapper is the trade in the wrong direction.
211 ///
212 /// The count said six and twelve until an audit counted them: three, not
213 /// six. The argument survived being wrong by a factor of two, because
214 /// doubling is doubling at any size — but the number is what carries it, and
215 /// this is the second time in one sitting that a sentence in this repository
216 /// stopped matching the thing beside it while still reading as true. The
217 /// first was `tests/support/delegated.rs`, whose own correction notes that
218 /// its count is spelled out because it was wrong once. A number in prose is
219 /// a claim, and nothing here checks it.
220 ///
221 /// Recorded here rather than left to be re-derived, because a departure
222 /// nobody wrote down reads as an oversight by whoever finds it next — and
223 /// an alternative discarded without a line reads as one never considered.
224 ///
225 /// The prose above is written for whoever maintains this, and `long_help`
226 /// keeps it out of the terminal. Without that, clap serves the whole doc
227 /// comment as the help of this flag, so a caller asking what a flag does was
228 /// handed an audit note naming a test file and a requirement number.
229 #[arg(
230 long,
231 value_name = "BOOL",
232 num_args = 0..=1,
233 default_missing_value = "true",
234 long_help = "Fix this profile to one database.\n\n\
235 Three states rather than two: written bare it fixes the database, \
236 written `--pin-database false` it releases it, and left out it \
237 changes nothing. Two states would make an edit that names one field \
238 reset the other, so a field left unmentioned has to be a value it \
239 can hold."
240 )]
241 pub pin_database: Option<bool>,
242 /// Refuse any change through this profile.
243 ///
244 /// Carries the same three states as `--pin-database` above, and for the
245 /// same reason. It did not, and the gap was not visible from here: the
246 /// field beside it announced that "every editable field here" had three
247 /// states while this one had two, so a reader checking the sentence rather
248 /// than the attribute found the promise and stopped. FR-087 then published
249 /// `conn edit producao --read-only-profile` as its example and that form
250 /// ended in 2, because the value was required.
251 ///
252 /// Kept out of the terminal by `long_help`, for the reason stated on
253 /// `--pin-database` above.
254 #[arg(
255 long,
256 value_name = "BOOL",
257 num_args = 0..=1,
258 default_missing_value = "true",
259 long_help = "Refuse any change through this profile.\n\n\
260 Three states, like `--pin-database`: written bare it refuses every \
261 change, written `--read-only-profile false` it allows them again, \
262 and left out it changes nothing."
263 )]
264 pub read_only_profile: Option<bool>,
265
266 /// Declared authentication method.
267 #[arg(long)]
268 pub auth: Option<String>,
269
270 /// Client certificate presented to the server.
271 ///
272 /// Editable for the reason the whole group below is: a destination that
273 /// only admits an identified caller is exactly the destination whose
274 /// identity expires, and an identity that can be written once but never
275 /// replaced obliges the caller to delete the profile and build it again.
276 /// That trades a rotation for the secret the profile holds, which the
277 /// caller may no longer have.
278 #[arg(long)]
279 pub client_cert: Option<std::path::PathBuf>,
280
281 /// Key matching the client certificate.
282 #[arg(long)]
283 pub client_key: Option<std::path::PathBuf>,
284
285 /// Authority used to verify the server certificate.
286 #[arg(long)]
287 pub ca: Option<std::path::PathBuf>,
288
289 /// Whether this destination demands an encrypted channel.
290 ///
291 /// Three states, matching the field it writes and `--pin-database` beside
292 /// it: written bare it demands encryption, written `--require-tls false` it
293 /// says this destination does not, and left out it changes nothing and
294 /// leaves whatever the profile already said.
295 #[arg(long, value_name = "BOOL", num_args = 0..=1, default_missing_value = "true")]
296 pub require_tls: Option<bool>,
297
298 /// Session adjustments applied when opening.
299 ///
300 /// A list cannot borrow the three-state shape of the values above, because
301 /// "not mentioned" and "mentioned as nothing" are the same empty list. So
302 /// the empty text is spelled out and means the empty list: `--session-setup
303 /// ''` clears the adjustments, any other use replaces them, and leaving the
304 /// flag out keeps them. Without that spelling the adjustments would be the
305 /// one stored field an edit could add to and never take away.
306 #[arg(long, value_name = "SETTING")]
307 pub session_setup: Vec<String>,
308}
309
310/// Options of the connectivity check.
311#[derive(Debug, Clone, Args)]
312pub struct TestArgs {
313 /// Profile to test; defaults to the global choice.
314 pub name: Option<String>,
315}