mariadb_cli/exec/read.rs
1//! Statements that return rows.
2//!
3//! # A read never persists anything
4//!
5//! The session opens with automatic confirmation switched off, so anything a
6//! read touched is discarded when the connection closes at the end of the
7//! invocation. The guarantee therefore does not depend on the classification
8//! being right: even a change that escaped the classifier and travelled here
9//! would leave nothing behind. There is no flag that switches this off.
10//!
11//! # A row is never held longer than it takes to write it
12//!
13//! [`stream`] hands each row to the output flow and forgets it, so a million
14//! rows cost the same memory as one and the caller sees the first row while the
15//! server is still sending the last. The output operations run as stages of
16//! that flow, so a ceiling, a filter, a projection or a deduplication no longer
17//! costs the whole set being gathered first. The flow ends with the record that
18//! declares it complete, and a connection that drops mid-way leaves the output
19//! without that record, which is exactly how a cut set is told from a whole one.
20//!
21//! [`collect`] exists for the answer that travels inside a single envelope,
22//! where the whole set is the payload by definition. It obeys the row ceiling,
23//! and declares a gap when the ceiling cut the answer short.
24
25use super::prepare::Gated;
26use crate::conn::OrFailure;
27use crate::error::{Failure, Result};
28use crate::output::envelope::Gap;
29use crate::output::ops::Step;
30use crate::output::stream::Stream;
31use crate::output::Row;
32use crate::sql::classify::Classification;
33use crate::sql::{rewrite, ParseLimits};
34use crate::types::{value::convert, Conversion};
35use mysql_async::prelude::Queryable;
36use mysql_async::{Column, Conn, Row as WireRow};
37use std::io::Write;
38
39/// The rows of one read, together with what the ceiling did to them.
40#[derive(Debug, Default)]
41pub struct ReadResult {
42 /// The rows, in the order the server sent them.
43 pub rows: Vec<Row>,
44 /// The columns the server declared, in order.
45 pub columns: Vec<String>,
46 /// What the caller asked for and did not get, when the ceiling bit.
47 pub gap: Option<Gap>,
48}
49
50/// Converts one wire row into the shape the output pipeline carries.
51///
52/// The column order the server declared is preserved, so two runs of the same
53/// query produce the same bytes.
54///
55/// # Why the labels are handed in rather than worked out here
56///
57/// They are a function of the declared columns alone, so they are the same for
58/// every row of one result. Working them out here read well and cost a `Vec`, a
59/// `String` per column and two maps on every single row: a million rows of
60/// twenty columns paid for twenty million strings to arrive at the same twenty
61/// labels. The caller holds them across its loop instead, which is also what
62/// the header is built from, so a row still cannot carry a key the announced
63/// header does not name.
64///
65/// # Errors
66///
67/// Returns a limit failure when a byte value exceeds the ceiling for raw
68/// content.
69pub fn convert_row(
70 row: WireRow,
71 columns: &[Column],
72 labels: &[String],
73 conversion: &Conversion,
74) -> Result<Row> {
75 let mut converted = Row::with_capacity(columns.len());
76 let mut wire = row;
77 for ((index, column), label) in columns.iter().enumerate().zip(labels) {
78 let value = wire.take(index).unwrap_or(mysql_async::Value::NULL);
79 converted.insert(label.clone(), convert(&value, column, conversion)?);
80 }
81 Ok(converted)
82}
83
84/// The label a column with no declared name of its own falls back to.
85///
86/// A computed column written without a name still has to be addressable, and a
87/// row keyed by the empty string is not.
88const UNNAMED_COLUMN: &str = "column";
89
90/// Separates a label from the position that was appended to keep it distinct.
91const POSITION_MARK: char = '#';
92
93/// The labels the declared columns are carried under, in order.
94///
95/// A row is an ordered map, so two columns sharing one label would collapse
96/// into one and the second would be lost without a word. That is why a repeated
97/// name is not carried as it arrived: it is qualified with the table the server
98/// declared it under, which is the same convention the server uses to tell two
99/// homonymous columns apart. A qualification that still repeats — the same table
100/// joined to itself, or two unnamed computed columns — is settled by the
101/// column's position, the one thing that is always distinct and always the same
102/// between two runs of the same query.
103///
104/// Nothing outside the declared metadata is consulted, so the labels of a query
105/// never change from one run to the next.
106#[must_use]
107pub fn column_names(columns: &[Column]) -> Vec<String> {
108 let mut labels: Vec<String> = columns.iter().map(plain_label).collect();
109
110 // Only the labels that actually clash are rewritten, so a query without
111 // homonymous columns reads exactly as the server declared it.
112 for index in repeated(&labels) {
113 labels[index] = qualified_label(&columns[index]);
114 }
115 for index in repeated(&labels) {
116 labels[index] = format!("{}{POSITION_MARK}{index}", labels[index]);
117 }
118 labels
119}
120
121/// The name the server declared, or the fallback when it declared none.
122fn plain_label(column: &Column) -> String {
123 let name = column.name_str();
124 if name.is_empty() {
125 return UNNAMED_COLUMN.to_owned();
126 }
127 name.into_owned()
128}
129
130/// The label qualified with the table, and the schema, the server declared.
131///
132/// Parts the server left empty are dropped rather than written as an empty
133/// segment, because a leading dot would name a schema that does not exist.
134fn qualified_label(column: &Column) -> String {
135 let mut parts: Vec<String> = Vec::with_capacity(3);
136 for part in [column.schema_str(), column.table_str()] {
137 if !part.is_empty() {
138 parts.push(part.into_owned());
139 }
140 }
141 parts.push(plain_label(column));
142 parts.join(".")
143}
144
145/// The positions of the labels that occur more than once.
146fn repeated(labels: &[String]) -> Vec<usize> {
147 let mut seen: std::collections::HashMap<&str, usize> =
148 std::collections::HashMap::with_capacity(labels.len());
149 for label in labels {
150 *seen.entry(label.as_str()).or_insert(0) += 1;
151 }
152 labels
153 .iter()
154 .enumerate()
155 .filter(|(_, label)| seen.get(label.as_str()).is_some_and(|count| *count > 1))
156 .map(|(index, _)| index)
157 .collect()
158}
159
160/// Imposes this tool's own row ceiling on a statement that returns rows.
161///
162/// A statement that is not a plain query carries no ceiling, because appending
163/// one would change what it means. A query that already carries a ceiling of
164/// its own is left as the caller wrote it.
165///
166/// The server is asked for one row more than the ceiling allows. That extra row
167/// is never handed to the caller: it exists only so that a full answer can be
168/// told apart from a cut one. Asking for exactly the ceiling would make every
169/// cut answer indistinguishable from a complete one, and the answer would shrink
170/// in silence.
171///
172/// # Errors
173///
174/// Returns a validation failure when the query ends in a clause a ceiling
175/// cannot be appended after.
176pub fn with_ceiling(gated: Gated, ceiling: usize, parse: ParseLimits) -> Result<Gated> {
177 if gated.classification() != Classification::Read || gated.kind() != "select" {
178 return Ok(gated);
179 }
180 let widened = rewrite::with_limit(gated.sql(), witness_limit(ceiling), None, parse)?;
181 Ok(gated.with_sql(widened))
182}
183
184/// How many rows the server is asked for so that a cut answer announces itself.
185///
186/// The ceiling plus one, saturating, because a ceiling at the top of the range
187/// must not wrap around into a tiny one.
188fn witness_limit(ceiling: usize) -> usize {
189 ceiling.saturating_add(1)
190}
191
192/// Runs a read and collects its rows, obeying the ceiling.
193///
194/// # Errors
195///
196/// Returns the mapped driver failure when the server refuses the statement or
197/// the channel is lost, and a limit failure when a value exceeds its ceiling.
198pub async fn collect(
199 conn: &mut Conn,
200 gated: &Gated,
201 ceiling: usize,
202 conversion: &Conversion,
203) -> Result<ReadResult> {
204 let mut result = conn
205 .exec_iter(gated.sql(), gated.params())
206 .await
207 .or_failure()?;
208
209 let columns = result.columns_ref().to_vec();
210 // Worked out once for the whole result, because they depend on nothing the
211 // rows carry. The header below is built from this same list.
212 let labels = column_names(&columns);
213 let mut under = UnderCeiling::new(ceiling);
214 while let Some(row) = result.next().await.or_failure()? {
215 under.take(|| convert_row(row, &columns, &labels, conversion))?;
216 }
217
218 Ok(ReadResult {
219 columns: labels,
220 gap: under.gap(),
221 rows: under.rows,
222 })
223}
224
225/// The rows a ceiling admits, and the memory that more had arrived.
226#[derive(Debug)]
227struct UnderCeiling {
228 ceiling: usize,
229 rows: Vec<Row>,
230 overflowed: bool,
231}
232
233impl UnderCeiling {
234 /// An empty answer that will admit at most `ceiling` rows.
235 fn new(ceiling: usize) -> Self {
236 Self {
237 ceiling,
238 rows: Vec::new(),
239 overflowed: false,
240 }
241 }
242
243 /// Offers one arriving row to the answer.
244 ///
245 /// A row past the ceiling is a witness and nothing else, so it is never
246 /// produced: the caller's row is built only when there is room for it, which
247 /// also keeps a discarded row from failing conversion.
248 ///
249 /// # Errors
250 ///
251 /// Returns whatever building the row failed with.
252 fn take<F>(&mut self, produce: F) -> Result<()>
253 where
254 F: FnOnce() -> Result<Row>,
255 {
256 if self.rows.len() < self.ceiling {
257 self.rows.push(produce()?);
258 } else {
259 self.overflowed = true;
260 }
261 Ok(())
262 }
263
264 /// The gap the ceiling left, when a witness proved it cut the answer.
265 fn gap(&self) -> Option<Gap> {
266 self.overflowed.then(|| ceiling_gap(self.ceiling))
267 }
268}
269
270/// Refuses a projection that would keep no column of this answer.
271///
272/// # Errors
273///
274/// Returns a usage failure naming the fields asked for and the columns the
275/// answer really carries, which is what a mistyped name needs to be corrected.
276fn refuse_a_projection_that_keeps_nothing(
277 pipeline: &crate::output::Pipeline,
278 labels: &[String],
279 shown: &[String],
280) -> Result<()> {
281 if pipeline.select.is_empty() || labels.is_empty() || !shown.is_empty() {
282 return Ok(());
283 }
284 Err(Failure::usage(
285 "usage.projection_kept_nothing",
286 "no field named by the projection is carried by the answer",
287 )
288 .with_detail("asked", pipeline.select.join(","))
289 .with_detail("available", labels.join(","))
290 .with_hint("name a field the answer carries, or leave --select out"))
291}
292
293/// The gap a row ceiling leaves behind when it cuts an answer short.
294///
295/// A shrunken answer without a declared gap is a defect: the caller would read
296/// a partial set as a whole one.
297///
298/// The witness row proves only that at least one row was left behind, so the
299/// wording claims exactly that. Naming a count here would be inventing one.
300fn ceiling_gap(ceiling: usize) -> Gap {
301 Gap::new(
302 "rows",
303 "row_ceiling",
304 format!(
305 "the ceiling of {ceiling} rows was reached and at least one further row was not returned"
306 ),
307 )
308}
309
310/// Runs a read and writes each row straight onto the flow.
311///
312/// Nothing here holds a collection of rows: a row is shaped, written and
313/// forgotten, so the memory cost does not grow with the size of the result set.
314/// The output operations run as stages of that flow rather than over a gathered
315/// payload, so asking for a ceiling, a filter or a projection costs no memory
316/// either.
317///
318/// `sink` carries the channel, the shape and the tail the closing record
319/// declares besides the count: the command that produced the set and the
320/// destination it came from, which a flow has no envelope of its own to carry
321/// (FR-143).
322///
323/// The closing record is written only when the flow reached its end with
324/// everything it promised. A failure mid-way returns without it, and so does a
325/// flow the volume ceiling cut short, which is how the caller tells a cut set
326/// from a whole one.
327///
328/// # The row ceiling ends a flow without breaking it
329///
330/// `ceiling` is this tool's own ceiling on returned rows, and it is counted
331/// over the rows ARRIVING from the server rather than over the rows leaving,
332/// which is where the gathered path counts it too. Counting the ones leaving
333/// would answer one request two different ways the moment a filter dropped
334/// anything, because the gathered path cuts at the read and filters afterwards.
335///
336/// A flow the ceiling ended still closes with the record that declares it,
337/// carrying the gap the ceiling left. The set ended because this tool decided
338/// to end it, and a decision is not a loss: a flow cut by a dropped channel
339/// still leaves the output with no closing record at all, and that difference
340/// is the only thing a reader of the primary channel has to tell an interrupted
341/// set from a complete one.
342///
343/// # Errors
344///
345/// Returns the mapped driver failure when the channel is lost, and a limit
346/// failure when the reader closed the output channel.
347pub async fn stream<W: Write>(
348 conn: &mut Conn,
349 gated: &Gated,
350 sink: crate::output::stream::Sink<'_, W>,
351 pipeline: &crate::output::Pipeline,
352 conversion: &Conversion,
353 ceiling: usize,
354 token: &tokio_util::sync::CancellationToken,
355) -> Result<u64> {
356 let crate::output::stream::Sink {
357 writer,
358 formatter,
359 tail,
360 } = sink;
361 let mut result = conn
362 .exec_iter(gated.sql(), gated.params())
363 .await
364 .or_failure()?;
365
366 let columns = result.columns_ref().to_vec();
367 // The row labels and the header the reader sees are two different lists:
368 // projection can drop a column from the header while the row still has to
369 // be built whole before the pipeline decides. Both are worked out once
370 // here, because a million rows would otherwise pay for the same answer a
371 // million times.
372 let labels = column_names(&columns);
373 let shown = pipeline.columns_after_projection(&labels);
374 // FR-034. Refused here, before a single row is pulled, because this is the
375 // first place that knows both what was asked for and what the answer
376 // carries.
377 //
378 // A field the answer does not carry is skipped rather than emitted as null,
379 // and that is right for a caller naming five fields where four exist. When
380 // NONE of them exist the same rule leaves one empty object per row, and
381 // `row_count` still counts them — measured before this existed,
382 // `--select naoexiste` over four rows answered
383 // `{"columns":[],"rows":[{},{},{},{}],"row_count":4}` and ended in 0, so a
384 // mistyped field name was handed back as a full result of nothing.
385 refuse_a_projection_that_keeps_nothing(pipeline, &labels, &shown)?;
386 // FR-039. The volume ceiling covers the frame this shape writes around the
387 // rows, not the rows alone, so the frame is measured before the first row
388 // is offered and charged against the ceiling here.
389 let mut formatter = formatter;
390 let mut stage = pipeline.flow_framed(
391 &mut *formatter,
392 tail,
393 &shown,
394 ceiling,
395 &[ceiling_gap(ceiling)],
396 )?;
397 let mut flow = Stream::open(writer, formatter, tail, &shown)?;
398 let mut arrived = 0usize;
399 let mut cut = None;
400
401 while let Some(row) = result.next().await.or_failure()? {
402 // Asked once per row, which is the only place a flow can be stopped
403 // from. This is the longest loop the product has and it used to be the
404 // deafest: a million-row read carried on writing after the signal, all
405 // the way to the last row, because nothing between the signal and here
406 // ever looked. The check is a load of an atomic, which is nothing
407 // beside converting and writing the row it guards.
408 if token.is_cancelled() {
409 return Err(crate::error::Failure::interrupted(
410 "interrupted.during_flow",
411 "the invocation was stopped while the rows were still arriving",
412 ));
413 }
414 if arrived == ceiling {
415 // This row is the witness the ceiling was widened by, and nothing
416 // else. It is never converted and never written: it exists only so
417 // that a cut answer can be told from one that ended on its own.
418 cut = Some(ceiling_gap(ceiling));
419 break;
420 }
421 arrived += 1;
422
423 match stage.offer(convert_row(row, &columns, &labels, conversion)?) {
424 Step::Emit(shaped) => flow.write(&shaped)?,
425 Step::Skip => {}
426 Step::Stop => {
427 // Closed whether or not the set is whole. Leaving the channel
428 // unterminated used to be how a cut set was marked, and the
429 // mark is now the `output_truncated` field the `applied` block
430 // already carries: the primary channel stays parseable, which
431 // is the older and wider promise of the two.
432 //
433 // Closing here rather than gathering the rows first is what
434 // keeps this a flow. Measured, on two hundred thousand rows
435 // cut to two thousand bytes: flowing peaks at a quarter of
436 // what gathering peaks at, and the answer is the same.
437 return flow.finish(tail, &[], stage.applied().as_ref());
438 }
439 }
440 }
441
442 // Reaching this line is what makes the set whole, whether the server ran
443 // out of rows or this tool's ceiling ended the pull, so this is the only
444 // place the closing record is written.
445 flow.finish(tail, cut.as_slice(), stage.applied().as_ref())
446}
447
448/// Runs a read under the ceiling and shapes the payload it answers with.
449///
450/// # Errors
451///
452/// Returns a validation failure when the ceiling cannot be imposed, and the
453/// mapped driver failure when the server refuses the statement.
454pub async fn serve(
455 gated: Gated,
456 conn: &mut Conn,
457 parse: ParseLimits,
458 ceiling: usize,
459 conversion: &Conversion,
460 passed_over: usize,
461) -> Result<(serde_json::Value, Vec<Gap>)> {
462 // The rows the resume mark passes over still have to arrive, because the
463 // pipeline passes over them here rather than the server skipping them.
464 // Without this a caller asking for the second page of ten would ask the
465 // server for eleven rows and then discard all of them.
466 let reach = ceiling.saturating_add(passed_over);
467
468 // Both sides are given the same reach on purpose: the statement asks for
469 // one row beyond it and the collection stops at it, so the extra row can
470 // only ever be read as the witness that the answer was cut.
471 let widened = with_ceiling(gated, reach, parse)?;
472 let result = collect(conn, &widened, reach, conversion).await?;
473 Ok((
474 serde_json::json!({
475 "columns": result.columns,
476 "rows": result.rows,
477 "row_count": result.rows.len(),
478 }),
479 result.gap.into_iter().collect(),
480 ))
481}
482
483/// Builds the statement that returns the first rows of a table.
484///
485/// A table name is not a value and cannot be bound, so it goes through the one
486/// sanctioned way of putting a name into a statement, which refuses a name it
487/// cannot quote rather than producing text that means something else.
488///
489/// # Errors
490///
491/// Returns a limit failure when more rows are asked for than the ceiling
492/// allows, and a validation failure when the name cannot be quoted.
493pub fn sample_request(
494 table: &str,
495 database: Option<&str>,
496 wanted: usize,
497 ceiling: usize,
498) -> Result<String> {
499 if wanted > ceiling {
500 return Err(Failure::limit(
501 "limit.rows",
502 format!("{wanted} rows were asked for and the ceiling is {ceiling}"),
503 )
504 .with_detail("detail", format!("{wanted} > {ceiling}"))
505 .with_hint("ask for fewer rows, or raise output.max_rows"));
506 }
507 let name = match database {
508 Some(database) => crate::sql::ident::quote_qualified(&[database, table])?,
509 None => crate::sql::ident::quote(table)?,
510 };
511 Ok(format!("SELECT * FROM {name}"))
512}
513
514/// Refuses a statement asked to be read that does not read.
515///
516/// # Errors
517///
518/// Returns a validation failure naming what the statement actually does.
519pub fn refuse_if_not_a_read(gated: &Gated) -> Result<()> {
520 if gated.classification().is_read() {
521 return Ok(());
522 }
523 Err(Failure::validation(
524 "sql.not_a_read",
525 format!(
526 "this command only reads, and the statement is a {}",
527 gated.classification().as_str()
528 ),
529 )
530 .with_detail("detail", gated.classification().as_str())
531 .with_hint("use `query run` for a statement that changes the server"))
532}
533
534#[cfg(test)]
535mod tests {
536 use super::*;
537 use crate::cli::globals::RowCountMode;
538 use crate::exec::{prepare, Policy};
539 use crate::output::format::ndjson::Ndjson;
540 use crate::output::format::{END_OF_STREAM_KEY, ROW_COUNT_KEY};
541 use serde_json::json;
542 use std::time::Duration;
543
544 /// The tail a flow closes with, carrying no destination.
545 ///
546 /// These proofs measure the closing record itself, so nothing about a
547 /// destination is invented here.
548 fn tail() -> crate::output::Envelope {
549 crate::output::Envelope::new("query run", json!({}))
550 }
551
552 fn policy() -> Policy {
553 Policy::new(
554 ParseLimits::default(),
555 100,
556 50,
557 RowCountMode::Changed,
558 ";".to_owned(),
559 Duration::from_secs(30),
560 )
561 }
562
563 fn gated(sql: &str) -> Gated {
564 prepare::gate(sql, &[], &policy()).expect("admitted")
565 }
566
567 fn row(index: u64) -> Row {
568 let mut row = Row::new();
569 row.insert("id".to_owned(), json!(index));
570 row
571 }
572
573 /// Drives the ceiling exactly as [`collect`] does, with rows that need no
574 /// server behind them.
575 fn arriving(ceiling: usize, rows: u64) -> UnderCeiling {
576 let mut under = UnderCeiling::new(ceiling);
577 for index in 0..rows {
578 under.take(|| Ok(row(index))).expect("a row is built");
579 }
580 under
581 }
582
583 /// The statement asks for one row more than the ceiling allows, because
584 /// that extra row is the only thing that tells a full answer from a cut
585 /// one. It is a witness, never a result: the caller still gets five.
586 #[test]
587 fn a_query_receives_this_tools_ceiling_plus_the_witness_row() {
588 let widened = with_ceiling(gated("SELECT a FROM t"), 5, ParseLimits::default())
589 .expect("a query accepts a ceiling");
590 assert_eq!(widened.sql(), "SELECT a FROM t\nLIMIT 6");
591 }
592
593 /// A ceiling at the top of the range must not wrap around into a tiny one.
594 #[test]
595 fn a_ceiling_at_the_top_of_the_range_does_not_wrap_around() {
596 assert_eq!(witness_limit(usize::MAX), usize::MAX);
597 }
598
599 /// An answer that ends exactly at the ceiling was not cut, so declaring a
600 /// gap there would send the caller looking for rows that do not exist.
601 #[test]
602 fn an_answer_that_fills_the_ceiling_exactly_declares_no_gap() {
603 let under = arriving(3, 3);
604 assert_eq!(under.rows.len(), 3);
605 assert!(under.gap().is_none());
606 }
607
608 #[test]
609 fn the_witness_row_declares_the_gap_and_is_not_returned() {
610 let under = arriving(3, 4);
611 assert_eq!(under.rows.len(), 3, "the caller gets the ceiling, no more");
612 let gap = under.gap().expect("a cut answer declares its gap");
613 assert_eq!(gap.object, "rows");
614 assert_eq!(gap.cause, "row_ceiling");
615 }
616
617 /// The witness must never reach the caller as data, or the ceiling would be
618 /// exceeded by the very row that reports it.
619 #[test]
620 fn the_witness_row_never_appears_among_the_returned_rows() {
621 let under = arriving(3, 4);
622 let returned: Vec<_> = under.rows.iter().map(|row| row["id"].clone()).collect();
623 assert_eq!(returned, vec![json!(0), json!(1), json!(2)]);
624 }
625
626 /// A statement that is not a plain query must not be rewritten, because a
627 /// clause appended to it would change what it means.
628 #[test]
629 fn a_statement_that_is_not_a_query_is_left_exactly_as_written() {
630 for sql in ["SHOW TABLES", "DESCRIBE t"] {
631 let untouched =
632 with_ceiling(gated(sql), 5, ParseLimits::default()).expect("left as written");
633 assert_eq!(untouched.sql(), sql, "input {sql:?}");
634 }
635 }
636
637 #[test]
638 fn a_statement_that_changes_the_server_is_refused_by_a_read_command() {
639 let failure = refuse_if_not_a_read(&gated("DELETE FROM t WHERE a = 1"))
640 .expect_err("a change is not a read");
641 assert_eq!(failure.code(), "sql.not_a_read");
642 assert!(failure.message().contains("change"));
643 }
644
645 #[test]
646 fn a_read_passes_the_read_only_refusal() {
647 assert!(refuse_if_not_a_read(&gated("SELECT 1")).is_ok());
648 }
649
650 /// The witness proves only that something was left behind, so the wording
651 /// must name the ceiling and stop there rather than invent a count.
652 #[test]
653 fn a_ceiling_that_cuts_the_answer_declares_the_gap_it_left() {
654 let gap = ceiling_gap(10);
655 assert_eq!(gap.object, "rows");
656 assert_eq!(gap.cause, "row_ceiling");
657 assert!(gap.detail.contains("10"), "the ceiling is named");
658 assert!(
659 gap.detail.contains("at least one"),
660 "no count is invented: {}",
661 gap.detail
662 );
663 }
664
665 /// The closing record is the only mark that separates a whole set from a
666 /// cut one, so a completed flow must always carry it.
667 #[test]
668 fn a_completed_flow_ends_with_the_record_that_declares_it_whole() {
669 let mut out = Vec::new();
670 let mut flow =
671 Stream::open(&mut out, Box::new(Ndjson), &tail(), &["id".to_owned()]).expect("opens");
672 for index in 0..3 {
673 flow.write(&row(index)).expect("writes");
674 }
675 assert_eq!(flow.finish(&tail(), &[], None).expect("closes"), 3);
676
677 let text = String::from_utf8(out).expect("utf8");
678 let last = text.lines().next_back().expect("a last line");
679 let parsed: serde_json::Value = serde_json::from_str(last).expect("parses");
680 assert_eq!(parsed[END_OF_STREAM_KEY], true);
681 assert_eq!(parsed[ROW_COUNT_KEY], 3);
682 }
683
684 /// A connection lost mid-flow leaves the output without the closing record,
685 /// which is what the caller reads as "this set is not whole".
686 #[test]
687 fn a_flow_abandoned_mid_way_carries_no_closing_record() {
688 let mut out = Vec::new();
689 {
690 let mut flow = Stream::open(&mut out, Box::new(Ndjson), &tail(), &["id".to_owned()])
691 .expect("opens");
692 flow.write(&row(0)).expect("writes");
693 // The connection dropped here: `finish` is never reached.
694 }
695 let text = String::from_utf8(out).expect("utf8");
696 assert!(
697 !text.contains(END_OF_STREAM_KEY),
698 "a cut set must never look whole: {text}"
699 );
700 }
701
702 /// Builds one declared column the way the server would announce it.
703 fn declared(schema: &str, table: &str, name: &str) -> Column {
704 Column::new(mysql_async::consts::ColumnType::MYSQL_TYPE_LONG)
705 .with_schema(schema.as_bytes())
706 .with_table(table.as_bytes())
707 .with_name(name.as_bytes())
708 }
709
710 /// FR-102: a join of two tables that both declare `id` must return both
711 /// columns. Carrying them under one label would drop the second one, and
712 /// losing a column without a word is exactly the defect the requirement
713 /// forbids.
714 #[test]
715 fn fr_102_two_homonymous_columns_keep_two_distinct_labels() {
716 let labels = column_names(&[
717 declared("loja", "pedidos", "id"),
718 declared("loja", "clientes", "id"),
719 ]);
720 assert_eq!(labels, vec!["loja.pedidos.id", "loja.clientes.id"]);
721 }
722
723 /// FR-102: a name that repeats nowhere is carried exactly as the server
724 /// declared it, so qualifying only happens where it is needed.
725 #[test]
726 fn fr_102_a_name_that_repeats_nowhere_is_left_as_declared() {
727 let labels = column_names(&[
728 declared("loja", "pedidos", "total"),
729 declared("loja", "clientes", "nome"),
730 ]);
731 assert_eq!(labels, vec!["total", "nome"]);
732 }
733
734 /// FR-102: the same table joined to itself declares the same schema, table
735 /// and name twice, so qualification alone still collapses. The position is
736 /// the only thing left that is both distinct and stable.
737 #[test]
738 fn fr_102_a_self_join_falls_back_to_the_declared_position() {
739 let labels = column_names(&[
740 declared("loja", "pedidos", "id"),
741 declared("loja", "pedidos", "id"),
742 ]);
743 assert_eq!(labels, vec!["loja.pedidos.id#0", "loja.pedidos.id#1"]);
744 }
745
746 /// FR-102: a computed column written without a name declares no name at
747 /// all, and a row keyed by the empty string cannot be addressed.
748 #[test]
749 fn fr_102_a_column_with_no_declared_name_still_gets_one() {
750 let labels = column_names(&[declared("", "", ""), declared("", "", "")]);
751 assert_eq!(labels, vec!["column#0", "column#1"]);
752 }
753
754 /// FR-102 with FR-064: the labels are read from the declared metadata and
755 /// nothing else, so two runs of the same query agree.
756 #[test]
757 fn fr_102_the_labels_are_the_same_on_every_run() {
758 let columns = [
759 declared("loja", "pedidos", "id"),
760 declared("loja", "clientes", "id"),
761 declared("", "", ""),
762 ];
763 assert_eq!(column_names(&columns), column_names(&columns));
764 }
765
766 /// FR-102: a label produced by qualifying must not collide with a label
767 /// another column already carried as declared, or the collapse would come
768 /// back through the repair itself.
769 #[test]
770 fn fr_102_a_qualified_label_that_meets_a_plain_one_is_still_separated() {
771 let labels = column_names(&[
772 declared("", "pedidos", "id"),
773 declared("", "clientes", "id"),
774 declared("", "", "pedidos.id"),
775 ]);
776 assert_eq!(
777 labels,
778 vec!["pedidos.id#0", "clientes.id", "pedidos.id#2"],
779 "no two columns may share a label"
780 );
781 }
782
783 /// The flow must not grow its memory with the number of rows, or a large
784 /// result set would cost as much as holding it all.
785 #[test]
786 fn a_long_flow_does_not_grow_its_buffer_row_by_row() {
787 let mut out = Vec::new();
788 let mut flow =
789 Stream::open(&mut out, Box::new(Ndjson), &tail(), &["id".to_owned()]).expect("opens");
790 let before = flow.buffer_capacity();
791 for index in 0..20_000 {
792 flow.write(&row(index)).expect("writes");
793 }
794 assert_eq!(flow.buffer_capacity(), before);
795 assert_eq!(flow.finish(&tail(), &[], None).expect("closes"), 20_000);
796 }
797}