Skip to main content

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}