Skip to main content

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}