mariadb_cli/cli/server.rs
1//! Server diagnosis: what the server is doing right now.
2//!
3//! These commands stay on the published surface even when the credential
4//! lacks the observation permission. Missing permission is reported as a
5//! failure with a hint, so the command tree never differs between
6//! destinations.
7
8use clap::{Args, Subcommand, ValueEnum};
9
10/// What a listed connection is doing right now.
11///
12/// A domain rather than free text, because a word the server never writes
13/// would narrow the listing to nothing and read exactly like a quiet server.
14#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
15pub enum ConnectionState {
16 /// Working on a statement.
17 Running,
18 /// Holding the connection open and doing nothing.
19 Sleeping,
20}
21
22impl ConnectionState {
23 /// The word the server writes in its own command column.
24 #[must_use]
25 pub const fn command_word(self) -> &'static str {
26 match self {
27 Self::Running => "Query",
28 Self::Sleeping => "Sleep",
29 }
30 }
31}
32
33/// The eight server commands.
34#[derive(Debug, Clone, Subcommand)]
35pub enum ServerCommand {
36 /// Activity counters, with the difference between two readings.
37 Status(StatusArgs),
38 /// Configuration variables.
39 Variables(PatternArgs),
40 /// Active connections.
41 Processes(ProcessesArgs),
42 /// Replica situation.
43 Replica,
44 /// End the work of another connection.
45 Kill(KillArgs),
46 /// Server variant and the conditional features available.
47 Capabilities,
48 /// Costliest statements, grouped by signature.
49 Queries(TopArgs),
50 /// Locks, waits and open transactions.
51 Locks,
52}
53
54/// Reading the activity counters.
55///
56/// A counter only means something as a difference between two readings, so the
57/// command takes two by default, separated by a declared interval.
58#[derive(Debug, Clone, Args)]
59pub struct StatusArgs {
60 /// Seconds between the two readings; defaults to the stored key.
61 #[arg(long)]
62 pub interval: Option<u64>,
63 /// Keep only counters whose name matches this pattern.
64 #[arg(long)]
65 pub pattern: Option<String>,
66}
67
68/// A listing narrowed by a name pattern.
69#[derive(Debug, Clone, Args)]
70pub struct PatternArgs {
71 /// Keep only names matching this pattern.
72 ///
73 /// Published as `--like`, which is the name the manual carries, with
74 /// `--pattern` kept as an alias for the form this build served first.
75 #[arg(long = "like", alias = "pattern")]
76 pub pattern: Option<String>,
77}
78
79/// Listing active connections.
80#[derive(Debug, Clone, Args)]
81pub struct ProcessesArgs {
82 /// Keep only connections of this user.
83 #[arg(long)]
84 pub user: Option<String>,
85 /// Keep only connections busy for at least this many seconds.
86 #[arg(long)]
87 pub min_seconds: Option<u64>,
88 /// Keep only connections in this state.
89 #[arg(long, value_name = "STATE")]
90 pub state: Option<ConnectionState>,
91}
92
93/// Ending the work of another connection.
94///
95/// Ending a connection of another user cannot be undone and takes away work
96/// that is not yours, so it needs a mark of its own beyond the usual
97/// confirmation.
98#[derive(Debug, Clone, Args)]
99pub struct KillArgs {
100 /// Connection identifier to end.
101 ///
102 /// The argument layer no longer demands it, so publishing the contract of
103 /// this command costs nothing. Zero stands for absence, because no server
104 /// hands out a connection under that number, and the refusal is raised
105 /// where the connection would actually be ended.
106 ///
107 /// Published as `--connection`, which is the name the manual carries, with
108 /// `--id` kept as an alias for the form this build served first.
109 #[arg(long = "connection", alias = "id", default_value_t = 0)]
110 pub id: u64,
111 /// End only the running statement, keeping the connection open.
112 ///
113 /// Published as `--query` for the same reason, with `--query-only` kept.
114 #[arg(long = "query", alias = "query-only")]
115 pub query_only: bool,
116 /// Allow ending a connection that belongs to another user.
117 #[arg(long)]
118 pub kill_other: bool,
119}
120
121/// What a ranking of statements is ordered by.
122///
123/// A closed domain rather than free text, and the reason is the defect this
124/// repairs (FR-127): the manual promised a criterion, the command had none, and
125/// the global output ordering silently accepted a field the answer never
126/// carried. A no-op that ends in success is worse than a refusal, because the
127/// caller reads the ranking as though it had been ordered.
128///
129/// Every name is ONE word, so the spelling on the command line and the spelling
130/// in the answer cannot drift apart. The pair that was already wrong here —
131/// `total-time` in the manual against `total_time` in the answer — is exactly
132/// what two-word names cost, and the product has no third convention to fall
133/// back on.
134#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
135pub enum QueryRanking {
136 /// Time the signature accounts for in total.
137 Total,
138 /// How many times the signature was called.
139 Calls,
140 /// Time one call of the signature costs on average.
141 Average,
142 /// Rows the server examined for the signature.
143 Rows,
144}
145
146impl QueryRanking {
147 /// The column of the server's own collection this orders by.
148 ///
149 /// Named here rather than built where the statement is, so the statement
150 /// can only ever carry one of these four and never anything a caller wrote.
151 #[must_use]
152 pub const fn column(self) -> &'static str {
153 match self {
154 Self::Total => "SUM_TIMER_WAIT",
155 Self::Calls => "COUNT_STAR",
156 Self::Average => "AVG_TIMER_WAIT",
157 Self::Rows => "SUM_ROWS_EXAMINED",
158 }
159 }
160
161 /// The name the answer declares this ranking under.
162 ///
163 /// The same word the command line accepts, which is the whole point: a
164 /// caller reading `sorted_by` back learns the value it would have to write
165 /// to ask for the same ranking again.
166 #[must_use]
167 pub const fn as_str(self) -> &'static str {
168 match self {
169 Self::Total => "total",
170 Self::Calls => "calls",
171 Self::Average => "average",
172 Self::Rows => "rows",
173 }
174 }
175}
176
177/// Ranking the costliest statements.
178#[derive(Debug, Clone, Args)]
179pub struct TopArgs {
180 /// How many signatures to return.
181 #[arg(long)]
182 pub top: Option<usize>,
183 /// What the ranking is ordered by; defaults to total time.
184 ///
185 /// Deliberately not spelled `--sort`, which is the GLOBAL ordering of the
186 /// output and a different thing: this one orders on the SERVER, inside the
187 /// statement, so the ceiling on rows keeps the costliest signatures by the
188 /// criterion asked for. Ordering afterwards would return the ten costliest
189 /// by time, merely rearranged.
190 #[arg(long, value_enum, default_value_t = QueryRanking::Total)]
191 pub rank_by: QueryRanking,
192}