mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
//! The compact map: the skeleton of a database in the least text possible.
//!
//! A caller that is about to write a query needs to know what tables exist,
//! which columns identify a row and how the tables join. It does not need the
//! full type of every column, and it certainly does not need the content of a
//! byte column, so neither is here.
//!
//! Indexes are left out on purpose. They roughly double the size of the map
//! and none of them helps decide what to select or how to join, which is the
//! only question this map answers.
//!
//! The map is read in a fixed, small number of set-based readings rather than
//! one reading per table, so its cost does not grow with the number of tables.

use super::kinds::Kind;
use super::query::{self, Scope};
use crate::error::Result;
use crate::output::envelope::{Gap, Row};
use indexmap::IndexMap;
use mysql_async::Conn;
use serde_json::{json, Value};

/// What the map is allowed to cost.
///
/// Every ceiling arrives from the caller, because the right ceiling depends on
/// how much room the caller has and this module cannot know that.
#[derive(Debug, Clone, Copy)]
pub struct Budget {
    /// Most tables the map may describe.
    pub tables: usize,
    /// Most rows any single reading may bring back.
    pub rows: usize,
}

/// Reads the compact map of a database.
///
/// # Errors
///
/// Returns a validation failure when the database name is not writable, and
/// the mapped driver failure when a reading cannot be answered.
pub async fn compact(
    connection: &mut Conn,
    database: Option<&str>,
    with_comments: bool,
    budget: Budget,
) -> Result<(Value, Vec<Gap>)> {
    let scope = Scope::in_database(database.map(ToOwned::to_owned))
        .detailed(with_comments)
        .limited(Some(budget.rows));

    let tables = query::read(connection, Kind::Table.descriptor(), &scope).await?;
    let columns = query::read(
        connection,
        Kind::Column.descriptor(),
        &scope.clone().detailed(true),
    )
    .await?;
    let links = query::read(
        connection,
        Kind::ForeignKey.descriptor(),
        &scope.clone().detailed(false),
    )
    .await?;

    Ok(compose(&tables, &columns, &links, with_comments, budget))
}

/// Builds the map from readings already made.
///
/// Kept apart from the round trips so the shape of the map is provable without
/// a server: it is the shape, and not the network, that has to stay small.
#[must_use]
pub fn compose(
    tables: &[Row],
    columns: &[Row],
    links: &[Row],
    with_comments: bool,
    budget: Budget,
) -> (Value, Vec<Gap>) {
    let mut gaps = Vec::new();
    let mut by_table: IndexMap<String, Entry> = IndexMap::new();

    for table in tables.iter().take(budget.tables) {
        let Some(name) = qualified(table, "name") else {
            continue;
        };
        by_table.insert(
            name.clone(),
            Entry::new(name, comment_of(table, with_comments)),
        );
    }
    if tables.len() > budget.tables {
        gaps.push(Gap::new(
            "map",
            "ceiling",
            format!(
                "{} tables were read and the map describes {}",
                tables.len(),
                budget.tables
            ),
        ));
    }

    for column in columns {
        let Some(owner) = qualified(column, "table") else {
            continue;
        };
        let Some(entry) = by_table.get_mut(&owner) else {
            continue;
        };
        entry.absorb_column(column, with_comments);
    }
    for link in links {
        let Some(owner) = qualified(link, "table") else {
            continue;
        };
        if let Some(entry) = by_table.get_mut(&owner) {
            entry.absorb_link(link);
        }
    }

    let rows: Vec<Value> = by_table.into_values().map(Entry::into_value).collect();
    (json!({ "rows": rows }), gaps)
}

/// One table as the map describes it.
#[derive(Debug)]
struct Entry {
    name: String,
    comment: Option<String>,
    keys: Vec<String>,
    links: Vec<String>,
}

impl Entry {
    /// An empty entry for one table.
    fn new(name: String, comment: Option<String>) -> Self {
        Self {
            name,
            comment,
            keys: Vec::new(),
            links: Vec::new(),
        }
    }

    /// Keeps a column only when it identifies or joins a row.
    ///
    /// A column with no role in a key tells a caller nothing it could not read
    /// from the full description, and there are far more of them than there
    /// are key columns, so keeping them all is what would make the map big.
    fn absorb_column(&mut self, column: &Row, with_comments: bool) {
        let (Some(name), Some(role)) = (text(column, "name"), text(column, "key")) else {
            return;
        };
        if role.is_empty() {
            return;
        }
        let mut rendered = format!("{name}:{role}");
        if with_comments {
            if let Some(comment) = text(column, "comment").filter(|text| !text.is_empty()) {
                rendered.push_str(" — ");
                rendered.push_str(&comment);
            }
        }
        self.keys.push(rendered);
    }

    /// Keeps one join, as the pair of columns that make it.
    fn absorb_link(&mut self, link: &Row) {
        let (Some(column), Some(target), Some(target_column)) = (
            text(link, "column"),
            qualified(link, "referenced_table"),
            text(link, "referenced_column"),
        ) else {
            return;
        };
        self.links
            .push(format!("{column}->{target}.{target_column}"));
    }

    /// The entry as it is published, carrying no empty field.
    ///
    /// The subject sits under `name`, which is where every other listing in
    /// this product puts the thing its row is about. It used to sit under
    /// `table`, and `table` everywhere else names the table an object BELONGS
    /// to — so the one key meant two things, and which one depended on the
    /// command that wrote the row.
    ///
    /// The name stays qualified here, and that is the point of the map: it
    /// carries no `database` field of its own, so the name has to stand alone.
    /// Adding one costs about a fifth of the whole answer, and the answer
    /// existing to be small is the reason this command exists.
    fn into_value(self) -> Value {
        let mut value = json!({ "name": self.name });
        if !self.keys.is_empty() {
            value["keys"] = json!(self.keys);
        }
        if !self.links.is_empty() {
            value["links"] = json!(self.links);
        }
        if let Some(comment) = self.comment.filter(|text| !text.is_empty()) {
            value["comment"] = json!(comment);
        }
        value
    }
}

/// The full name of the object a row names under this key.
fn qualified(row: &Row, key: &str) -> Option<String> {
    let name = text(row, key)?;
    let database = text(row, "database").or_else(|| text(row, "referenced_database"));
    Some(database.map_or(name.clone(), |database| format!("{database}.{name}")))
}

/// One text field of a row, when it carries one.
fn text(row: &Row, key: &str) -> Option<String> {
    row.get(key).and_then(Value::as_str).map(ToOwned::to_owned)
}

/// The comment of a table, only when comments were asked for.
fn comment_of(row: &Row, with_comments: bool) -> Option<String> {
    with_comments.then(|| text(row, "comment")).flatten()
}

#[cfg(test)]
mod tests {
    use super::*;

    const ROOM: Budget = Budget {
        tables: 100,
        rows: 10_000,
    };

    fn table_row(name: &str, comment: &str) -> Row {
        let mut row = Row::new();
        row.insert("database".to_owned(), json!("shop"));
        row.insert("name".to_owned(), json!(name));
        row.insert("comment".to_owned(), json!(comment));
        row
    }

    fn column_row(table: &str, name: &str, role: &str, kind: &str) -> Row {
        let mut row = Row::new();
        row.insert("database".to_owned(), json!("shop"));
        row.insert("table".to_owned(), json!(table));
        row.insert("name".to_owned(), json!(name));
        row.insert("key".to_owned(), json!(role));
        row.insert("type".to_owned(), json!(kind));
        row.insert("comment".to_owned(), json!("who placed it"));
        row
    }

    fn link_row(table: &str, column: &str) -> Row {
        let mut row = Row::new();
        row.insert("database".to_owned(), json!("shop"));
        row.insert("table".to_owned(), json!(table));
        row.insert("column".to_owned(), json!(column));
        row.insert("referenced_database".to_owned(), json!("shop"));
        row.insert("referenced_table".to_owned(), json!("customers"));
        row.insert("referenced_column".to_owned(), json!("id"));
        row
    }

    fn sample() -> (Vec<Row>, Vec<Row>, Vec<Row>) {
        let tables = vec![
            table_row("orders", "one per purchase"),
            table_row("customers", ""),
        ];
        let columns = vec![
            column_row("orders", "id", "PRI", "bigint(20) unsigned"),
            column_row("orders", "customer_id", "MUL", "bigint(20) unsigned"),
            column_row("orders", "note", "", "varchar(255)"),
            column_row("orders", "receipt", "", "longblob"),
            column_row("customers", "id", "PRI", "bigint(20) unsigned"),
        ];
        let links = vec![link_row("orders", "customer_id")];
        (tables, columns, links)
    }

    fn rows_of(value: &Value) -> Vec<Value> {
        value["rows"].as_array().expect("array payload").clone()
    }

    /// The map carries the tables, their key columns and their joins.
    #[test]
    fn the_map_carries_tables_key_columns_and_joins() {
        let (tables, columns, links) = sample();
        let (value, gaps) = compose(&tables, &columns, &links, false, ROOM);
        let rows = rows_of(&value);
        assert!(gaps.is_empty());
        assert_eq!(rows.len(), 2);
        assert_eq!(rows[0]["name"], json!("shop.orders"));
        assert_eq!(rows[0]["keys"], json!(["id:PRI", "customer_id:MUL"]));
        assert_eq!(rows[0]["links"], json!(["customer_id->shop.customers.id"]));
    }

    /// A column with no role in a key never reaches the map, which is what
    /// keeps the map small.
    #[test]
    fn a_column_with_no_key_role_never_reaches_the_map() {
        let (tables, columns, links) = sample();
        let text = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0)
            .expect("serialises");
        assert!(!text.contains("note"), "{text}");
    }

    /// Neither the full type nor the content of a byte column reaches the map.
    #[test]
    fn neither_full_types_nor_byte_content_reach_the_map() {
        let (tables, columns, links) = sample();
        let text = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0)
            .expect("serialises");
        assert!(
            !text.contains("bigint"),
            "a full type reached the map: {text}"
        );
        assert!(
            !text.contains("longblob"),
            "a byte column reached the map: {text}"
        );
    }

    /// The map is far smaller than the full description of the same database.
    /// Ten times is the published promise; the comparison is against the rows
    /// the full description would carry.
    #[test]
    fn the_map_is_at_least_ten_times_smaller_than_the_full_description() {
        let mut tables = Vec::new();
        let mut columns = Vec::new();
        let mut links = Vec::new();
        for table in 0..40 {
            let name = format!("table_{table:02}");
            tables.push(table_row(
                &name,
                "a table that carries a long explanatory comment",
            ));
            for column in 0..25 {
                let role = if column == 0 { "PRI" } else { "" };
                columns.push(column_row(
                    &name,
                    &format!("column_{column:02}"),
                    role,
                    "varchar(255)",
                ));
            }
            links.push(link_row(&name, "column_00"));
        }

        let map = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0)
            .expect("serialises");
        let full = serde_json::to_string(&json!({ "rows": columns })).expect("serialises");
        assert!(
            map.len() * 10 <= full.len(),
            "the map is {} bytes against {} for the full description",
            map.len(),
            full.len()
        );
    }

    /// Beyond the ceiling the map stops and says how much it left out, rather
    /// than shrinking in silence.
    #[test]
    fn beyond_the_ceiling_the_map_declares_what_it_left_out() {
        let tables: Vec<Row> = (0..5).map(|n| table_row(&format!("t{n}"), "")).collect();
        let budget = Budget {
            tables: 2,
            rows: 10,
        };
        let (value, gaps) = compose(&tables, &[], &[], false, budget);
        assert_eq!(rows_of(&value).len(), 2);
        assert_eq!(gaps.len(), 1);
        assert_eq!(gaps[0].cause, "ceiling");
        assert!(gaps[0].detail.contains('5'));
    }

    /// Comments appear only when they were asked for.
    #[test]
    fn comments_appear_only_when_they_were_asked_for() {
        let (tables, columns, links) = sample();
        let clean = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0)
            .expect("serialises");
        assert!(!clean.contains("one per purchase"), "{clean}");

        let annotated = serde_json::to_string(&compose(&tables, &columns, &links, true, ROOM).0)
            .expect("serialises");
        assert!(annotated.contains("one per purchase"), "{annotated}");
    }

    /// A table with no key and no join still appears, so the caller learns it
    /// exists.
    #[test]
    fn a_table_with_no_key_and_no_join_still_appears() {
        let (value, _) = compose(&[table_row("log", "")], &[], &[], false, ROOM);
        let rows = rows_of(&value);
        assert_eq!(rows[0]["name"], json!("shop.log"));
        assert!(rows[0].get("keys").is_none(), "no empty field is carried");
    }

    /// The same readings always produce the same bytes.
    #[test]
    fn the_same_readings_produce_the_same_bytes() {
        let (tables, columns, links) = sample();
        let first = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0);
        let second = serde_json::to_string(&compose(&tables, &columns, &links, false, ROOM).0);
        assert_eq!(first.expect("serialises"), second.expect("serialises"));
    }
}