mariadb_cli/exec/script.rs
1//! Running a file of statements, and the atomic block.
2//!
3//! Cutting a file into its statements is [`super::script_split`]; this module
4//! takes the pieces it produced and runs them.
5//!
6//! # What escapes an atomic block
7//!
8//! A statement that defines an object confirms itself on this server, so a
9//! block cannot undo it. Such a statement therefore always produces a notice of
10//! escape: the caller asked for all or nothing, and this part is neither.
11
12pub use super::script_split::{split, validate_delimiter, Piece, Statements};
13
14use super::prepare::{self, Gated};
15use super::{change, read, Policy, WriteState};
16use crate::error::Result;
17use crate::sql::classify::Classification;
18use mysql_async::Conn;
19use serde_json::{json, Value};
20
21/// Whether a statement escapes an atomic block.
22///
23/// A statement that defines an object confirms itself on this server, so the
24/// block cannot undo it. Reporting that is the whole point: the caller asked
25/// for all or nothing, and this part is neither.
26#[must_use]
27pub const fn escapes_block(classification: Classification) -> bool {
28 matches!(
29 classification,
30 Classification::Definition | Classification::Administration
31 )
32}
33
34/// The notice one escaping statement produces.
35#[must_use]
36pub fn escape_notice(
37 piece: &Piece,
38 classification: Classification,
39) -> crate::output::envelope::Gap {
40 crate::output::envelope::Gap::new(
41 format!("statement_{}", piece.index),
42 "escapes_atomic_block",
43 format!(
44 "the statement on line {} is a {} and confirms itself, so the block cannot undo it",
45 piece.line,
46 classification.as_str()
47 ),
48 )
49}
50
51/// Everything running one statement of a file takes.
52///
53/// The five describe one thing, which is how a statement is to be run: on which
54/// connection, under which policy, against which record of what has already
55/// been written, on a destination that may refuse change of its own, and with
56/// which reading of the server's types. Carried apart, every function that runs
57/// a statement had to repeat the same list, and every new one had to repeat it
58/// again in the same order.
59pub struct Run<'a> {
60 /// The connection every statement is asked on.
61 pub conn: &'a mut Conn,
62 /// What this invocation admits.
63 pub policy: &'a Policy,
64 /// What has already been written, and what that now demands.
65 pub write_state: &'a mut WriteState,
66 /// Whether the destination itself refuses change.
67 pub server_read_only: bool,
68 /// How the server's own types are read back.
69 pub conversion: &'a crate::types::Conversion,
70 /// Whether a statement that failed ends the run.
71 ///
72 /// True everywhere but a file whose caller asked to carry on. A block is
73 /// never allowed to carry on, because a block that skipped a statement and
74 /// was then confirmed is precisely the half-applied script FR-029 forbids.
75 pub stop_on_failure: bool,
76}
77
78/// Confirms changes this invocation already sent, so they outlive the process.
79///
80/// # Why this has to exist at all
81///
82/// Every connection opens with `SET autocommit = 0`, and the reason written
83/// beside that statement is a good one: a read must never persist anything, and
84/// a statement the caller did not mean to commit is discarded when the process
85/// ends. What was missing is the other half. A caller who DID mean it — who
86/// passed the confirmation mark and received `affected: 1` — also had the change
87/// discarded, because nothing ever sent this.
88///
89/// Measured against a real server before the fix: `query run` inserting one row
90/// ended in zero, reported one row changed, and a second process counted none.
91/// The same insert through `query tx`, which confirms its own block, persisted.
92/// The report was never false about the statement; it was silent about the
93/// transaction the statement was still sitting in.
94///
95/// It survived because no proof read a change back from a SECOND process. A
96/// proof that reads the count reported by the process that just wrote it is
97/// reading the inside of the open transaction, and everything looks right in
98/// there.
99///
100/// # Errors
101///
102/// Returns the driver failure when the server refuses the confirmation, which
103/// is the one moment a caller has to be told the change is not there.
104pub async fn confirm_changes(conn: &mut Conn) -> Result<()> {
105 prepare::exec_drop(conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await
106}
107
108/// The statement that opens an atomic block.
109pub const BEGIN_BLOCK: &str = "START TRANSACTION";
110/// The statement that confirms an atomic block.
111pub const CONFIRM_BLOCK: &str = "COMMIT";
112/// The statement that undoes an atomic block.
113pub const UNDO_BLOCK: &str = "ROLLBACK";
114
115/// Runs one statement of a file or a block and says what it did.
116///
117/// # Errors
118///
119/// Returns the failure the statement produced, which is what stops the file or
120/// undoes the block.
121pub async fn one_of_many(gated: &Gated, run: &mut Run<'_>) -> Result<Value> {
122 if gated.classification().is_read() {
123 let result = read::collect(run.conn, gated, run.policy.max_rows, run.conversion).await?;
124 return Ok(json!({"read": true, "row_count": result.rows.len()}));
125 }
126 let outcome = change::apply(
127 gated,
128 run.conn,
129 run.policy,
130 run.write_state,
131 run.server_read_only,
132 )
133 .await?;
134 Ok(change::describe(gated, &outcome))
135}
136
137/// The columns a run of a file announces, one record per statement.
138pub const FILE_COLUMNS: [&str; 3] = ["statement", "line", "outcome"];
139
140/// Runs one statement of a file and builds the record FR-028 publishes.
141///
142/// The record carries where the statement was and what it did, and never the
143/// statement's own text, which is dropped before the server is asked.
144///
145/// # Errors
146///
147/// Returns the failure the statement produced, carrying its position.
148async fn record_of(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
149 let (index, line) = (piece.index, piece.line);
150 let stop = run.stop_on_failure;
151 match attempt(piece, run).await {
152 Ok(record) => Ok(record),
153 Err(failure) if stop => Err(failure),
154 Err(failure) => Ok(refused(index, line, &failure)),
155 }
156}
157
158/// The record of one statement that failed, for a run told to carry on.
159///
160/// The record keeps the three published columns, so a caller reading the file
161/// as a continuous flow sees the same shape whether the statement worked or
162/// not, and learns which it was from the outcome rather than from the shape.
163fn refused(index: usize, line: usize, failure: &crate::error::Failure) -> crate::output::Row {
164 let mut record = crate::output::Row::new();
165 record.insert("statement".to_owned(), json!(index));
166 record.insert("line".to_owned(), json!(line));
167 record.insert(
168 "outcome".to_owned(),
169 json!({
170 "failed": true,
171 "code": failure.code(),
172 "message": failure.message(),
173 "exit": failure.exit_number().code(),
174 }),
175 );
176 record
177}
178
179/// Runs one statement and builds its record, failing as it always did.
180async fn attempt(piece: Piece, run: &mut Run<'_>) -> Result<crate::output::Row> {
181 let where_it_is = format!("statement {}, line {}", piece.index, piece.line);
182 let gated = prepare::gate(&piece.sql, &[], run.policy)
183 .map_err(|failure| failure.with_cause(where_it_is.clone()))?;
184 // Nothing after this point needs the text, so it is not kept alive across
185 // the round trip to the server.
186 drop(piece.sql);
187 let outcome = one_of_many(&gated, run)
188 .await
189 .map_err(|failure| failure.with_cause(where_it_is))?;
190
191 let mut record = crate::output::Row::new();
192 record.insert("statement".to_owned(), json!(piece.index));
193 record.insert("line".to_owned(), json!(piece.line));
194 record.insert("outcome".to_owned(), outcome);
195 Ok(record)
196}
197
198/// Runs a file of statements, stopping at the first one that fails.
199///
200/// Stopping is not a preference: a statement that failed may well be the one
201/// the rest depended on, so carrying on would apply a script whose first half
202/// never happened.
203///
204/// This is the whole-answer path, so it gathers the records it produces. The
205/// promise that memory does not follow volume is made for a run consumed as a
206/// continuous flow, which is [`stream_file`].
207///
208/// # Errors
209///
210/// Returns the failure of the first statement that produced one, carrying the
211/// position of that statement in the file.
212pub async fn run_file<S: IntoIterator<Item = Piece>>(
213 statements: S,
214 run: &mut Run<'_>,
215) -> Result<Value> {
216 let mut answers = Vec::new();
217 for piece in statements {
218 let record = record_of(piece, run).await?;
219 answers.push(Value::Object(record.into_iter().collect()));
220 }
221 // A file that only read has nothing to confirm and confirming costs it a
222 // round trip; a file that changed anything has everything to confirm.
223 if !run.policy.dry_run {
224 confirm_changes(run.conn).await?;
225 }
226 Ok(json!({"statement_count": answers.len(), "rows": answers}))
227}
228
229/// Runs a file of statements, writing each record as its statement finishes.
230///
231/// This is the second clause of Proof 5: a long command file holds no more at
232/// its last statement than at its first. The statements arrive one at a time
233/// from the cut and each record leaves as it is made, so nothing here grows
234/// with the count of statements.
235///
236/// # Why a cut answer does not cut the run
237///
238/// The output operations decide records, not statements. A ceiling reached
239/// part way through stops the records leaving; it must never stop the file
240/// being applied, because a statement not run is a different thing from a row
241/// not printed, and a script half applied is exactly what FR-028 forbids. The
242/// run therefore carries on to the end, and the answer that was cut simply
243/// closes without the record that would declare it whole.
244///
245/// `sink` carries the channel, the shape and the tail the closing record
246/// declares besides the count: the command that produced the records and the
247/// destination they came from, which a flow has no envelope of its own to carry
248/// (FR-143).
249///
250/// # Errors
251///
252/// Returns the failure of the first statement that produced one, and a limit
253/// failure when the reader closed the output channel.
254pub async fn stream_file<W: std::io::Write, S: IntoIterator<Item = Piece>>(
255 statements: S,
256 run: &mut Run<'_>,
257 sink: crate::output::stream::Sink<'_, W>,
258 pipeline: &crate::output::Pipeline,
259 token: &tokio_util::sync::CancellationToken,
260) -> Result<u64> {
261 let crate::output::stream::Sink {
262 writer,
263 formatter,
264 tail,
265 } = sink;
266 let columns: Vec<String> = FILE_COLUMNS.iter().map(|name| (*name).to_owned()).collect();
267 // FR-039. The volume ceiling covers the frame this shape writes around the
268 // records, not the records alone, so the frame is measured before the first
269 // record is offered and charged against the ceiling here.
270 let mut formatter = formatter;
271 let mut stage = pipeline.flow_framed(&mut *formatter, tail, &columns, 0, &[])?;
272 let mut flow = crate::output::stream::Stream::open(writer, formatter, tail, &columns)?;
273 let mut still_emitting = true;
274
275 for piece in statements {
276 // Between statements, never inside one. A statement already sent is
277 // seen through so the file's record says what really happened to it,
278 // and the next one is simply not begun. A long file used to run to its
279 // last statement after the signal, because the check lived above this
280 // loop and nothing here asked again.
281 if token.is_cancelled() {
282 return Err(crate::error::Failure::interrupted(
283 "interrupted.between_statements",
284 "the invocation was stopped between two statements of the file",
285 ));
286 }
287 let record = record_of(piece, run).await?;
288 if !still_emitting {
289 continue;
290 }
291 match stage.offer(record) {
292 crate::output::ops::Step::Emit(shaped) => flow.write(&shaped)?,
293 crate::output::ops::Step::Skip => {}
294 crate::output::ops::Step::Stop => still_emitting = false,
295 }
296 }
297
298 // Confirmed before the closing record is written, because the record is
299 // what tells the caller the file was applied and it must not say so while
300 // the work is still inside a transaction nobody closed. A ceiling that cut
301 // the OUTPUT never cuts the RUN, which is the paragraph above this
302 // function, so the statements are all sent by here either way.
303 if !run.policy.dry_run {
304 confirm_changes(run.conn).await?;
305 }
306
307 // Reaching the end of the file is what makes the answer whole, and a
308 // ceiling that cut it is what makes it not, so the closing record is
309 // written here and only when both hold.
310 if stage.is_whole() {
311 // A run of a file has no ceiling on rows to reach, so it closes
312 // declaring nothing left out.
313 return flow.finish(tail, &[], stage.applied().as_ref());
314 }
315 Ok(flow.emitted())
316}
317
318/// Admits every statement of a block and declares the ones that escape it.
319///
320/// The escape is declared before the block opens, so the caller reads which
321/// part of the promise the server will not keep even if the block itself never
322/// gets that far.
323///
324/// # Errors
325///
326/// Returns the refusal the first inadmissible statement earned.
327pub fn gate_block(
328 statements: &[String],
329 policy: &Policy,
330) -> Result<(Vec<Gated>, Vec<crate::output::envelope::Gap>)> {
331 let mut gaps = Vec::new();
332 let mut gated = Vec::new();
333 for (position, text) in statements.iter().enumerate() {
334 let one = prepare::gate(text, &[], policy)?;
335 if escapes_block(one.classification()) {
336 let piece = Piece {
337 index: position + 1,
338 line: position + 1,
339 sql: text.clone(),
340 };
341 gaps.push(escape_notice(&piece, one.classification()));
342 }
343 gated.push(one);
344 }
345 Ok((gated, gaps))
346}
347
348/// Runs statements together, so they are confirmed or undone as one.
349///
350/// A statement that confirms itself escapes the block. That is a property of
351/// the server and not a choice made here, so each such statement is declared as
352/// a gap rather than silently counted inside the promise.
353///
354/// # Errors
355///
356/// Returns the failure of the first statement that produced one, after asking
357/// the server to undo everything the block had done.
358pub async fn run_block(gated: &[Gated], run: &mut Run<'_>) -> Result<Value> {
359 prepare::exec_drop(run.conn, BEGIN_BLOCK, mysql_async::Params::Empty).await?;
360 let mut answers = Vec::new();
361 for one in gated {
362 match one_of_many(one, run).await {
363 Ok(answer) => answers.push(answer),
364 Err(failure) => {
365 // The undo is attempted whatever happens, and its own outcome
366 // never replaces the failure that made the caller stop.
367 let _ = prepare::exec_drop(run.conn, UNDO_BLOCK, mysql_async::Params::Empty).await;
368 return Err(failure);
369 }
370 }
371 }
372 prepare::exec_drop(run.conn, CONFIRM_BLOCK, mysql_async::Params::Empty).await?;
373 Ok(json!({"rows": answers, "confirmed": true, "statement_count": gated.len()}))
374}
375
376#[cfg(test)]
377mod tests {
378 use super::*;
379
380 /// A statement that confirms itself is exactly what an atomic block cannot
381 /// undo, so it always produces a notice.
382 #[test]
383 fn a_statement_that_confirms_itself_always_escapes_the_block() {
384 assert!(escapes_block(Classification::Definition));
385 assert!(escapes_block(Classification::Administration));
386 assert!(!escapes_block(Classification::Change));
387 assert!(!escapes_block(Classification::Read));
388
389 let piece = Piece {
390 index: 3,
391 line: 12,
392 sql: "CREATE TABLE t (a INT)".to_owned(),
393 };
394 let notice = escape_notice(&piece, Classification::Definition);
395 assert_eq!(notice.object, "statement_3");
396 assert_eq!(notice.cause, "escapes_atomic_block");
397 assert!(notice.detail.contains("12") && notice.detail.contains("definition"));
398 }
399}