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};
#[derive(Debug, Clone, Copy)]
pub struct Budget {
pub tables: usize,
pub rows: usize,
}
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))
}
#[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)
}
#[derive(Debug)]
struct Entry {
name: String,
comment: Option<String>,
keys: Vec<String>,
links: Vec<String>,
}
impl Entry {
fn new(name: String, comment: Option<String>) -> Self {
Self {
name,
comment,
keys: Vec::new(),
links: Vec::new(),
}
}
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);
}
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}"));
}
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
}
}
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}")))
}
fn text(row: &Row, key: &str) -> Option<String> {
row.get(key).and_then(Value::as_str).map(ToOwned::to_owned)
}
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()
}
#[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"]));
}
#[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}");
}
#[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}"
);
}
#[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()
);
}
#[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'));
}
#[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}");
}
#[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");
}
#[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"));
}
}