Skip to main content

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}