Skip to main content

mariadb_cli/exec/
change.rs

1//! Statements that alter data, and every ceiling that guards them.
2//!
3//! # The ceiling on affected rows is checked before the change, always
4//!
5//! The obvious implementation runs the change inside an atomic block, counts
6//! what it touched and undoes the block when the count is too high. That works
7//! only while a block exists, and a statement that defines an object confirms
8//! itself on this server, so no block can undo it. Worse, without a block there
9//! is nothing to undo at all, which is precisely when a caller most needs a
10//! ceiling.
11//!
12//! So the count is derived from the statement's own restriction by
13//! [`crate::exec::plan::estimate`], run first, and the change is refused before
14//! it is sent. That costs one extra round trip on every change. The cost was
15//! accepted deliberately, because a ceiling that only works inside a block is a
16//! ceiling that fails in the case it exists for.
17//!
18//! When no count can be derived, the answer declares a gap rather than
19//! pretending the ceiling was applied.
20//!
21//! # A table with no unique key
22//!
23//! A row of such a table cannot be named again afterwards, so the change cannot
24//! be repeated safely. That makes a repeat unsafe; it does not make this change
25//! wrong. The absence is therefore reported on the auxiliary channel and the
26//! change proceeds, unless `sql.require_unique_key` asks for the stricter rule.
27
28use super::plan::{self, Estimate, Target};
29use super::prepare::{self, Gated};
30use super::{ChangeCounts, Policy, WriteState};
31use crate::conn::OrFailure;
32use crate::error::{Failure, Result};
33use crate::output::envelope::Gap;
34use mysql_async::prelude::Queryable;
35use mysql_async::Conn;
36use serde_json::{json, Value};
37use sqlparser::ast::Statement;
38
39/// Refuses a change that would reach every row of its table.
40///
41/// The decision comes from the syntax tree and never from the text, so a
42/// restriction hidden behind a comment still counts as one.
43///
44/// # Errors
45///
46/// Returns a validation failure naming the table the change would have reached
47/// in full.
48pub fn refuse_without_restriction(gated: &Gated) -> Result<()> {
49    let Some(statement) = gated.admission().analysis().statements().first() else {
50        return Ok(());
51    };
52    if !matches!(statement, Statement::Delete(_) | Statement::Update(_))
53        || plan::restriction_of(statement).is_some()
54    {
55        return Ok(());
56    }
57    let named =
58        plan::target_of(statement).map_or_else(|| "the target table".to_owned(), |t| t.table);
59    Err(Failure::validation(
60        "safety.no_restriction",
61        format!("this change would reach every row of `{named}`"),
62    )
63    .with_detail("detail", named)
64    .with_hint("add a restriction, or set sql.require_where to false to allow the whole table"))
65}
66
67/// The refusal a change over the ceiling produces, before it is sent.
68#[must_use]
69pub fn over_ceiling(would_affect: u64, ceiling: u64) -> Failure {
70    Failure::limit(
71        "limit.affected_rows",
72        format!("this change would affect {would_affect} rows and the ceiling is {ceiling}"),
73    )
74    .with_detail("detail", format!("{would_affect} > {ceiling}"))
75    .with_hint("narrow the restriction, or raise --max-affected")
76}
77
78/// Decides, before the change is sent, whether the ceiling admits it.
79///
80/// Returns the predicted count when one could be established, and a declared
81/// gap when none could.
82///
83/// # Errors
84///
85/// Returns a limit failure when the prediction exceeds the ceiling, and the
86/// mapped driver failure when the derived count could not be run.
87pub async fn admit_scale(
88    conn: &mut Conn,
89    gated: &Gated,
90    ceiling: u64,
91) -> Result<(Option<u64>, Option<Gap>)> {
92    let Some(statement) = gated.admission().analysis().statements().first() else {
93        return Ok((None, None));
94    };
95
96    let predicted = match plan::estimate(statement) {
97        Estimate::Known(rows) => rows,
98        Estimate::Unavailable(reason) => return Ok((None, Some(plan::undecidable_gap(reason)))),
99        Estimate::Derived(count_sql) => {
100            let values = plan::count_values(&count_sql, gated.values());
101            prepare::exec_count(conn, &count_sql, prepare::bind(values)).await?
102        }
103    };
104
105    if predicted > ceiling {
106        return Err(over_ceiling(predicted, ceiling));
107    }
108    Ok((Some(predicted), None))
109}
110
111/// Whether the target table can name a row again afterwards.
112///
113/// Answers `None` when the question itself could not be asked, which is not the
114/// same as a table without a key and is never reported as one.
115///
116/// # Errors
117///
118/// Returns the mapped driver failure when the channel is lost.
119pub async fn has_unique_key(conn: &mut Conn, target: &Target) -> Result<Option<bool>> {
120    const QUERY: &str = "SELECT COUNT(*) FROM information_schema.table_constraints \
121         WHERE table_schema = COALESCE(NULLIF(?, ''), DATABASE()) \
122           AND table_name = ? \
123           AND constraint_type IN ('PRIMARY KEY', 'UNIQUE')";
124    let values = vec![
125        target.database.clone().unwrap_or_default(),
126        target.table.clone(),
127    ];
128    match prepare::exec_count(conn, QUERY, prepare::bind(&values)).await {
129        Ok(count) => Ok(Some(count > 0)),
130        // The question itself failing must not be read as an answer of "no".
131        Err(failure) if failure.category() == crate::error::Category::Server => Ok(None),
132        Err(other) => Err(other),
133    }
134}
135
136/// Applies the rule for a table that cannot name its rows again.
137///
138/// # Errors
139///
140/// Returns a validation failure only when the stricter rule was asked for.
141pub fn report_missing_unique_key(target: &Target, policy: &Policy) -> Result<()> {
142    if policy.require_unique_key {
143        return Err(Failure::validation(
144            "safety.no_unique_key",
145            format!(
146                "`{}` has no primary or unique key, so this change cannot be repeated safely",
147                target.table
148            ),
149        )
150        .with_detail("detail", target.table.clone())
151        .with_hint("set sql.require_unique_key to false to proceed with a warning instead"));
152    }
153    crate::i18n::report::safety_no_unique_key(&target.table);
154    Ok(())
155}
156
157/// Every condition the server reported for the statement, not only the first.
158///
159/// The server may report several conditions for one statement, and returning
160/// only the first hides from the caller the very one they have to fix. When the
161/// conditions cannot be read at all, an empty list is returned: inventing one
162/// would be worse than reporting none.
163pub async fn conditions(conn: &mut Conn) -> Vec<String> {
164    let Ok(result) = conn.query_iter("SHOW WARNINGS").await else {
165        return Vec::new();
166    };
167    let collected: std::result::Result<Vec<(String, u32, String)>, _> =
168        result.collect_and_drop().await;
169    collected.map_or_else(
170        |_| Vec::new(),
171        |rows| {
172            rows.into_iter()
173                .map(|(level, code, text)| format!("{level} {code}: {text}"))
174                .collect()
175        },
176    )
177}
178
179/// Attaches every condition beyond the first to a failure.
180///
181/// The first one is already the failure's own message, so repeating it would
182/// make the caller read the same line twice.
183#[must_use]
184pub fn with_conditions(failure: Failure, conditions: &[String]) -> Failure {
185    conditions
186        .iter()
187        .skip(1)
188        .fold(failure, |carried, condition| {
189            carried.with_extra_condition(condition.clone())
190        })
191}
192
193/// What one change produced.
194#[derive(Debug, Default)]
195pub struct ChangeOutcome {
196    /// The two counts and the mark of which was asked for.
197    pub counts: Option<ChangeCounts>,
198    /// The rows the change was predicted to touch, before it was sent.
199    pub predicted: Option<u64>,
200    /// The identifier the server generated, when it generated one.
201    pub last_insert_id: Option<u64>,
202    /// Every condition the server reported.
203    pub conditions: Vec<String>,
204    /// What the caller asked for and did not get.
205    pub gaps: Vec<Gap>,
206    /// Whether the change was described rather than caused.
207    pub simulated: bool,
208}
209
210impl ChangeOutcome {
211    /// The answer this outcome carries.
212    ///
213    /// A simulation carries the prediction and no measured count, because it
214    /// measured nothing; claiming otherwise would be inventing a result.
215    #[must_use]
216    pub fn as_value(&self) -> Value {
217        let mut data = json!({ "simulated": self.simulated });
218        if let Some(counts) = self.counts {
219            data["rows"] = counts.as_value();
220        }
221        if let Some(predicted) = self.predicted {
222            data["predicted_rows"] = json!(predicted);
223        }
224        if let Some(identifier) = self.last_insert_id {
225            data["generated_id"] = json!(identifier);
226        }
227        if !self.conditions.is_empty() {
228            data["conditions"] = json!(self.conditions);
229        }
230        data
231    }
232}
233
234/// Puts one change through every ceiling that guards it, then applies it.
235///
236/// The order is the design: refuse outright, then confirm, then ask the
237/// destination whether it accepts a change at all, then the restriction, then
238/// the key, then the scale. Only the last two cost a round trip, and they are
239/// asked last so every refusal that costs nothing comes first.
240///
241/// # Errors
242///
243/// Returns the first refusal any of those layers produced, or the mapped driver
244/// failure when the change itself was refused by the server.
245pub async fn apply(
246    gated: &Gated,
247    conn: &mut Conn,
248    policy: &Policy,
249    write_state: &mut WriteState,
250    server_read_only: bool,
251) -> Result<ChangeOutcome> {
252    policy.admit_change(gated.kind())?;
253    write_state.admit(server_read_only)?;
254    if policy.require_where {
255        refuse_without_restriction(gated)?;
256    }
257
258    let mut gaps = Vec::new();
259    if let Some(target) = gated
260        .admission()
261        .analysis()
262        .statements()
263        .first()
264        .and_then(plan::target_of)
265    {
266        match has_unique_key(conn, &target).await? {
267            Some(false) => report_missing_unique_key(&target, policy)?,
268            Some(true) => {}
269            None => gaps.push(Gap::new(
270                "unique_key_check",
271                "unreadable",
272                "whether the target table can name a row again could not be established",
273            )),
274        }
275    }
276
277    let (predicted, gap) = admit_scale(conn, gated, policy.max_affected).await?;
278    gaps.extend(gap);
279
280    if policy.dry_run {
281        return Ok(ChangeOutcome {
282            predicted,
283            gaps,
284            simulated: true,
285            ..ChangeOutcome::default()
286        });
287    }
288
289    let mut outcome = send(conn, gated, policy).await?;
290    outcome.predicted = predicted;
291    outcome.gaps.extend(gaps);
292    Ok(outcome)
293}
294
295/// Describes what one change did, with any notice the invocation earned.
296///
297/// The notice about state that dies with the process is raised only where the
298/// statement actually created such state, so a plain change carries none.
299#[must_use]
300pub fn describe(gated: &Gated, outcome: &ChangeOutcome) -> Value {
301    let mut data = outcome.as_value();
302    if let Some(state) = super::Ephemeral::detect(gated.kind(), gated.admission().stripped().text())
303    {
304        data["ephemeral"] = json!({"state": state.as_str(), "notice": state.notice()});
305        crate::i18n::report::ephemeral_state(state.as_str());
306    }
307    data
308}
309
310/// Raises the notice about session state on an answer that carries none.
311///
312/// The notice a statement earned by actually creating state is more precise
313/// than this one and is never overwritten by it. This is the blanket form, for
314/// the caller who asked to be reminded on every invocation that opens a
315/// session rather than only on the ones that left something behind.
316pub fn note_session_is_ephemeral(data: &mut Value) {
317    let Some(map) = data.as_object_mut() else {
318        return;
319    };
320    if map.contains_key("ephemeral") {
321        return;
322    }
323    map.insert(
324        "ephemeral".to_owned(),
325        json!({
326            "state": "session",
327            "notice": "this invocation holds its own session, and every piece of \
328                       state in it dies when the process ends",
329        }),
330    );
331}
332
333/// Sends one change and reads back everything the server said about it.
334///
335/// # Errors
336///
337/// Returns the mapped driver failure, carrying every condition the server
338/// reported rather than only the first.
339pub async fn send(conn: &mut Conn, gated: &Gated, policy: &Policy) -> Result<ChangeOutcome> {
340    // Said here because this is the one place that holds all three: the text
341    // that leaves, how many values travel with it, and what the statement was
342    // admitted as. The diagnostic was written and published and nothing ever
343    // called it, which made it a promise to a caller reading the auxiliary
344    // channel that the channel never kept.
345    crate::i18n::report::statement_sending(
346        gated.sql(),
347        gated.values().len(),
348        gated.classification().as_str(),
349    );
350
351    // The prepared protocol, so the server itself refuses a multiple command.
352    let outcome = conn.exec_iter(gated.sql(), gated.params()).await;
353    let result = match outcome {
354        Ok(result) => result,
355        Err(error) => {
356            let failure = crate::conn::map_driver_error(&error);
357            let reported = conditions(conn).await;
358            return Err(with_conditions(failure, &reported));
359        }
360    };
361    result.drop_result().await.or_failure()?;
362
363    let counts = ChangeCounts::read(conn.affected_rows(), &conn.info(), policy.row_count_mode);
364    let last_insert_id = conn.last_insert_id();
365    Ok(ChangeOutcome {
366        counts: Some(counts),
367        last_insert_id,
368        conditions: conditions(conn).await,
369        ..ChangeOutcome::default()
370    })
371}
372
373#[cfg(test)]
374mod tests {
375    use super::*;
376    use crate::cli::globals::RowCountMode;
377    use crate::exec::prepare;
378    use crate::sql::ParseLimits;
379    use std::time::Duration;
380
381    fn policy() -> Policy {
382        let mut policy = Policy::new(
383            ParseLimits::default(),
384            100,
385            50,
386            RowCountMode::Changed,
387            ";".to_owned(),
388            Duration::from_secs(30),
389        );
390        policy.read_only = false;
391        policy.confirmed = true;
392        policy
393    }
394
395    fn gated(sql: &str) -> Gated {
396        prepare::gate(sql, &[], &policy()).expect("admitted")
397    }
398
399    /// A change with no restriction reaches every row, and one hidden behind a
400    /// comment is still a restriction, because the decision comes from the tree
401    /// and never from the text.
402    #[test]
403    fn a_change_reaching_every_row_is_refused_and_the_table_is_named() {
404        for sql in ["DELETE FROM pedidos", "UPDATE pedidos SET pago = 1"] {
405            let failure = refuse_without_restriction(&gated(sql)).expect_err("must refuse");
406            assert_eq!(failure.code(), "safety.no_restriction", "input {sql:?}");
407            assert!(failure.message().contains("pedidos"), "input {sql:?}");
408            assert_eq!(failure.exit_number().code(), 3);
409        }
410        for sql in [
411            "DELETE FROM pedidos WHERE id = 7",
412            "INSERT INTO t (a) VALUES (1)",
413            "DELETE /* note */ FROM t WHERE a = 1",
414        ] {
415            assert!(
416                refuse_without_restriction(&gated(sql)).is_ok(),
417                "input {sql:?}"
418            );
419        }
420    }
421
422    #[test]
423    fn a_change_over_the_ceiling_is_a_limit_failure_naming_both_numbers() {
424        let failure = over_ceiling(5000, 100);
425        assert_eq!(failure.code(), "limit.affected_rows");
426        assert_eq!(failure.exit_number().code(), 10);
427        assert!(failure.message().contains("5000") && failure.message().contains("100"));
428    }
429
430    #[test]
431    fn a_table_without_a_unique_key_warns_by_default_and_refuses_only_on_request() {
432        let target = Target {
433            database: None,
434            table: "eventos".to_owned(),
435        };
436        assert!(
437            report_missing_unique_key(&target, &policy()).is_ok(),
438            "the default warns, so a legitimate change is not blocked"
439        );
440
441        let mut strict = policy();
442        strict.require_unique_key = true;
443        let failure =
444            report_missing_unique_key(&target, &strict).expect_err("the stricter rule refuses");
445        assert_eq!(failure.code(), "safety.no_unique_key");
446        assert!(failure.message().contains("eventos"));
447    }
448
449    /// Reporting only the first condition hides the one the caller must fix.
450    #[test]
451    fn every_condition_the_server_reported_reaches_the_caller() {
452        let reported = vec![
453            "Warning 1264: out of range for column `a`".to_owned(),
454            "Warning 1264: out of range for column `b`".to_owned(),
455            "Warning 1265: data truncated for column `c`".to_owned(),
456        ];
457        let failure = with_conditions(
458            Failure::server("server.condition", reported[0].clone()),
459            &reported,
460        );
461        assert_eq!(failure.extra_conditions().len(), 2);
462        assert!(failure.extra_conditions()[1].contains("1265"));
463
464        // The first condition is already the failure's own message, so it is
465        // never repeated as an extra one.
466        let only = vec!["Warning 1264: out of range".to_owned()];
467        let single = with_conditions(Failure::server("server.condition", "x"), &only);
468        assert!(single.extra_conditions().is_empty());
469    }
470
471    /// The blanket notice never overwrites the precise one a statement earned,
472    /// and never lands on anything that is not an answer object.
473    #[test]
474    fn the_blanket_notice_yields_to_the_one_the_statement_earned() {
475        let mut plain = json!({"simulated": false});
476        note_session_is_ephemeral(&mut plain);
477        assert_eq!(plain["ephemeral"]["state"], "session");
478        assert!(plain["ephemeral"]["notice"]
479            .as_str()
480            .is_some_and(|notice| notice.contains("process ends")));
481
482        let mut earned = json!({"ephemeral": {"state": "temporary_table"}});
483        note_session_is_ephemeral(&mut earned);
484        assert_eq!(earned["ephemeral"]["state"], "temporary_table");
485
486        let mut not_an_object = json!([1, 2]);
487        note_session_is_ephemeral(&mut not_an_object);
488        assert_eq!(not_an_object, json!([1, 2]));
489    }
490
491    /// A simulation measured nothing, so it must never report a measurement; a
492    /// completed change reports both counts and anything the server generated.
493    #[test]
494    fn a_simulation_reports_its_prediction_and_a_change_reports_its_measurement() {
495        let simulated = ChangeOutcome {
496            simulated: true,
497            predicted: Some(12),
498            ..ChangeOutcome::default()
499        }
500        .as_value();
501        assert_eq!(simulated["simulated"], true);
502        assert_eq!(simulated["predicted_rows"], 12);
503        assert!(simulated.get("rows").is_none());
504
505        let applied = ChangeOutcome {
506            counts: Some(ChangeCounts::read(
507                1,
508                "Rows matched: 2  Changed: 1  Warnings: 0",
509                RowCountMode::Changed,
510            )),
511            last_insert_id: Some(77),
512            ..ChangeOutcome::default()
513        }
514        .as_value();
515        assert_eq!(applied["rows"]["matched"], 2);
516        assert_eq!(applied["rows"]["changed"], 1);
517        assert_eq!(applied["generated_id"], 77);
518        assert_eq!(applied["simulated"], false);
519    }
520}