Skip to main content

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}