mariadb_cli/cli/schema.rs
1//! Structure discovery: the nineteen commands that read server metadata.
2//!
3//! Discovery is metadata reading and never changes the server, so a profile
4//! marked read-only still answers every command here.
5
6use clap::{Args, Subcommand, ValueEnum};
7
8/// How deep a listing goes.
9///
10/// A level with a published domain rather than a bare truth value, because the
11/// manual publishes both `--detail summary` and `--detail full` and publishes a
12/// refusal for a level outside the domain. A truth value cannot carry that
13/// refusal: an unknown word beside it is not a level at all, and the argument
14/// layer would reject it as an unexpected value rather than as a level nobody
15/// offers.
16///
17/// Two levels and not three. The catalogue entries carry exactly two depths,
18/// the short field list and the short one plus its extras, so a third name
19/// would promise a depth that does not exist behind it.
20#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
21pub enum Detail {
22 /// The fields every form of the listing returns.
23 Summary,
24 /// Those fields and every extra the catalogue holds.
25 Full,
26}
27
28impl Detail {
29 /// Whether this level asks for the extras as well.
30 #[must_use]
31 pub const fn is_full(self) -> bool {
32 matches!(self, Self::Full)
33 }
34
35 /// The level a command asked for, or the one that command defaults to.
36 ///
37 /// The default belongs to the command and not to the argument type, because
38 /// the same type serves a listing whose extras a requirement demands and one
39 /// whose extras cost an extra read nobody asked for.
40 #[must_use]
41 pub fn or_default(asked: Option<Self>, fallback: Self) -> bool {
42 asked.unwrap_or(fallback).is_full()
43 }
44}
45
46/// The nineteen structure commands.
47#[derive(Debug, Clone, Subcommand)]
48pub enum SchemaCommand {
49 /// Compact map of the whole database.
50 Map(MapArgs),
51 /// List databases.
52 Databases,
53 /// List tables.
54 Tables(TablesArgs),
55 /// Describe the columns of a table.
56 Columns(DetailedTableArgs),
57 /// List foreign keys, optionally flagging those without a supporting index.
58 Keys(AdvisableTableArgs),
59 /// List indexes, optionally flagging those already covered by another.
60 Indexes(AdvisableTableArgs),
61 /// List the value restrictions a table imposes, with each condition.
62 Checks(DetailedTableArgs),
63 /// List views, with a cut for the materialised ones.
64 Views(ViewsArgs),
65 /// List routines and functions.
66 Routines(ScopeArgs),
67 /// List triggers.
68 Triggers(ScopeArgs),
69 /// List scheduled events.
70 Events(ScopeArgs),
71 /// List sequences.
72 Sequences(ScopeArgs),
73 /// List partitions.
74 Partitions(DetailedTableArgs),
75 /// Find an object by name pattern.
76 Search(SearchArgs),
77 /// Table statistics.
78 Stats(DetailedTableArgs),
79 /// Textual, re-creatable definition of an object.
80 Ddl(DdlArgs),
81 /// Exact row count, on demand.
82 Count(TableArgs),
83 /// Space per database and ranking of the largest objects.
84 Size(SizeArgs),
85 /// Effective permissions of the connected user.
86 Grants,
87}
88
89/// How wide and how deep the compact map goes.
90#[derive(Debug, Clone, Args)]
91pub struct MapArgs {
92 /// Include column comments in the map.
93 #[arg(long)]
94 pub with_comments: bool,
95}
96
97/// Listing scoped to a database.
98#[derive(Debug, Clone, Args)]
99pub struct ScopeArgs {
100 /// How deep the listing goes.
101 #[arg(long, value_name = "LEVEL")]
102 pub detail: Option<Detail>,
103}
104
105/// Table listing, with physical metadata on demand.
106#[derive(Debug, Clone, Args)]
107pub struct TablesArgs {
108 /// How deep the listing goes; the full level adds engine, collation, size
109 /// and comment.
110 #[arg(long, value_name = "LEVEL")]
111 pub detail: Option<Detail>,
112 /// Read every database the credential can see.
113 #[arg(long)]
114 pub all_databases: bool,
115}
116
117/// A command addressing one table.
118#[derive(Debug, Clone, Args)]
119pub struct TableArgs {
120 /// Table name.
121 ///
122 /// Optional to the argument layer and required to the command. Publishing
123 /// the contract must cost nothing, and a caller asking what this command
124 /// answers should not have to name a table first. Absence is refused where
125 /// the reading is actually run, and carries a code.
126 #[arg(long)]
127 pub table: Option<String>,
128}
129
130/// A command addressing one table, at a depth the caller may choose.
131#[derive(Debug, Clone, Args)]
132pub struct DetailedTableArgs {
133 /// Table name.
134 ///
135 /// Optional to the argument layer and required to the command, for the
136 /// reason given on [`TableArgs::table`].
137 #[arg(long)]
138 pub table: Option<String>,
139 /// How deep the description goes.
140 #[arg(long, value_name = "LEVEL")]
141 pub detail: Option<Detail>,
142}
143
144/// A table command that can also report structural advice.
145#[derive(Debug, Clone, Args)]
146pub struct AdvisableTableArgs {
147 /// Table name.
148 #[arg(long)]
149 pub table: Option<String>,
150 /// How deep the listing goes.
151 #[arg(long, value_name = "LEVEL")]
152 pub detail: Option<Detail>,
153 /// Report structure without supporting index; costs extra analysis.
154 ///
155 /// Asks for this one invocation. A host that wants it on every listing
156 /// stores `schema.index_advice` instead, and then this mark adds nothing.
157 ///
158 /// Published as `--warn`, which is the name the manual carries, with
159 /// `--advise` kept as an alias for the form this build served first.
160 #[arg(long = "warn", alias = "advise")]
161 pub advise: bool,
162}
163
164/// View listing, with a cut for materialised views.
165#[derive(Debug, Clone, Args)]
166pub struct ViewsArgs {
167 /// How deep the listing goes.
168 #[arg(long, value_name = "LEVEL")]
169 pub detail: Option<Detail>,
170 /// Return only materialised views.
171 #[arg(long)]
172 pub materialized: bool,
173}
174
175/// Object search across several kinds.
176#[derive(Debug, Clone, Args)]
177pub struct SearchArgs {
178 /// Name pattern, written as a bare word.
179 ///
180 /// Optional to the argument layer and required to the command, for the
181 /// reason given on [`TableArgs::table`].
182 pub pattern: Option<String>,
183 /// Name pattern, written as a flag.
184 ///
185 /// The manual publishes the pattern this way and this build served it as a
186 /// bare word, so both are accepted and the flag wins when the two disagree.
187 /// A caller who writes the manual's own example must not be refused.
188 #[arg(long, value_name = "PATTERN")]
189 pub like: Option<String>,
190 /// Restrict to these object kinds.
191 ///
192 /// Published as `--type`, which is the name the manual carries. `--kind` is
193 /// accepted as well, because that is the name this build served before the
194 /// two were reconciled and an argv that already worked must go on working.
195 #[arg(long = "type", alias = "kind", value_delimiter = ',')]
196 pub kind: Vec<String>,
197 /// How deep each match goes.
198 #[arg(long, value_name = "LEVEL")]
199 pub detail: Option<Detail>,
200}
201
202/// The definition of one named object.
203#[derive(Debug, Clone, Args)]
204pub struct DdlArgs {
205 /// Object name.
206 ///
207 /// Optional to the argument layer and required to the command, for the
208 /// reason given on [`TableArgs::table`].
209 pub object: Option<String>,
210 /// Object kind.
211 #[arg(long)]
212 pub kind: Option<String>,
213}
214
215/// Space report.
216#[derive(Debug, Clone, Args)]
217pub struct SizeArgs {
218 /// How many of the largest objects to rank.
219 #[arg(long)]
220 pub top: Option<usize>,
221}