mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
//! The continuous path: rows leave as they arrive, never gathered first.
//!
//! A shape that carries one record per line lets a reader consume a result set
//! larger than memory. The whole-answer path cannot: it has to hold every row
//! to serialise them together.

use crate::cli::globals::OutputFormat;
use crate::cli::query::QueryCommand;
use crate::cli::Cli;
use crate::error::Result;
use crate::output::envelope::Target;
use crate::output::Envelope;
use std::io::Write;

/// Whether this invocation should stream instead of answering all at once.
///
/// Only a shape whose payload can be written as it arrives can stream, and only
/// a command with rows to stream has anything to write. Everything else takes
/// the whole-answer path.
///
/// The output operations are stages of the flow, so asking for a ceiling, a
/// filter, a projection or a deduplication no longer abandons the flow. What
/// still does is a request whose answer is a property of the whole set: an
/// order over every row, a count of every row, or a signature over every row.
/// Those are gathered, and the answer says so.
///
/// # Why the single document is here, and why not for every command
///
/// A shape that carries one record per line can stream anything, because any
/// prefix of its output is still a sequence of lines. The single document can
/// stream too, but only when the payload it declares is the payload the flow
/// really writes: a set of columns and a set of rows. A plain read answers with
/// exactly that.
///
/// A run of a file does not. It answers with one record per statement and a
/// count of the statements, and the count is known only at the end, so a
/// document opened before the first record could not declare it. Streaming that
/// as a document would describe the answer with a payload it does not have, and
/// the caller would meet a different answer depending on which path served it.
/// That is why the built-in shape streams a read and gathers a run of a file.
#[must_use]
pub fn applies(cli: &Cli, config: &crate::config::Config) -> bool {
    // The shape is the resolved one, not the mark on the command line. Reading
    // the mark, as this once did, meant a caller who had stored a line-oriented
    // shape and gave no mark was answered in that shape by the path that holds
    // every row first — the setting reported as being in force while the one
    // thing it promises, that a set larger than memory can be read, did not
    // hold.
    let Ok(shape) = crate::output_shape(cli, config) else {
        return false;
    };

    // A plain read has rows to stream, and a run of a file has one record per
    // statement, which FR-028 requires it to publish and Proof 5 requires it to
    // publish without holding them all.
    let streamable = match (shape, &cli.command) {
        (
            OutputFormat::Ndjson | OutputFormat::Tsv,
            crate::cli::Command::Query(QueryCommand::File(_)),
        ) => true,
        (
            OutputFormat::Ndjson | OutputFormat::Tsv | OutputFormat::Json,
            crate::cli::Command::Query(QueryCommand::Run(args)),
        ) => only_reads(args, config),
        // The one shape meant for a person is an aligned table, and a width is
        // a property of every cell in a column.
        _ => false,
    };

    // A signature covers the set as one object, so it cannot be decided before
    // the last row has arrived.
    let signed = cli.globals.output.checksum;

    // A volume ceiling used to send the single document down the gathered path
    // instead, so that the ceiling would be met by dropping whole elements from
    // a set already in hand. It closed the document, and it cost the flow:
    // measured on two hundred thousand rows cut to two thousand bytes, the
    // gathered path peaked at 88 MiB against 26 MiB for the flow, to produce
    // the same two thousand bytes. The argument for it — that a caller asking
    // for few bytes wants a small answer — was about the ANSWER and was used
    // to justify the PATH, and the two are not the same thing.
    //
    // The document is closed where it is cut instead, in `exec::read`, which
    // costs nothing and keeps the flow a flow.

    // A malformed filter is refused before any work starts, so the whole-answer
    // path is the one that reports it.
    streamable && !signed && cli.globals.pipeline(config).is_ok_and(|p| !p.accumulates())
}

/// Whether the call wrote down a statement that only reads.
///
/// `query run` runs a read OR a change, and only a read has rows to stream.
/// The flow refuses a change on arrival, which was reached by nobody while the
/// shapes that stream were the ones a change is rarely written in: the caller
/// met a refusal telling it to use the very command it had used. The gate is
/// the right place to keep a change out, because the whole-answer path serves
/// it correctly and always has.
///
/// A statement the call did not write down cannot be classified here, because
/// reading it would consume the standard input the work itself has to read.
/// Such a call is gathered. That costs the flow for one way of writing a
/// statement and never answers a change with a refusal that makes no sense; the
/// two ways still answer with the same bytes, which is what the caller was
/// promised.
///
/// A statement that cannot be parsed is not streamed either, so the refusal
/// comes from the whole-answer path, which is where every other malformed
/// request is reported.
fn only_reads(args: &crate::cli::query::RunArgs, config: &crate::config::Config) -> bool {
    let Some(text) = args.statement.statement.as_deref() else {
        return false;
    };
    let Ok(limits) = crate::sql::ParseLimits::from_server(config) else {
        return false;
    };
    crate::sql::classify::classify(text, limits)
        .is_ok_and(crate::sql::classify::Classification::is_read)
}

/// Streams one read, closing with the record that declares the set whole.
///
/// The closing record is written only when the flow reached its end, so a
/// reader that sees no closing record knows the set was cut.
///
/// # What the closing record has to carry, and why it is built here
///
/// The whole-answer path names its command and its destination because it
/// answers with an envelope, and the envelope carries both. A flow answers with
/// no envelope at all, so it used to close with a record that named neither: the
/// one shape meant to be read while the work is still running was the one shape
/// that never said where its rows had come from, which FR-143 forbids.
///
/// The tail below is that missing envelope, and it is built here because this is
/// the first point that holds both halves of it — the command this invocation
/// names and the destination the dispatch resolved before the session opened.
/// Nothing further down knows either.
///
/// # Errors
///
/// Returns a validation failure when the statement is refused, the mapped
/// driver failure when the channel is lost, and a limit failure when the
/// reader closed the output channel.
pub async fn run<W: Write>(
    cli: &Cli,
    config: &crate::config::Config,
    session: &mut crate::conn::session::Session,
    context: &mut crate::commands::query::Context,
    writer: W,
    target: &Target,
) -> Result<u64> {
    // No rows: the payload of a flow is the rows themselves, which travel one
    // per line and never inside this.
    let tail = Envelope::new(cli.command.published_name(), serde_json::json!({}))
        .from_destination(target.clone(), cli.globals.destination.source());

    match &cli.command {
        crate::cli::Command::Query(QueryCommand::Run(args)) => {
            read_as_a_flow(cli, config, session, context, writer, &tail, args).await
        }
        crate::cli::Command::Query(QueryCommand::File(args)) => {
            file_as_a_flow(cli, config, session, context, writer, &tail, args).await
        }
        // A command with nothing to stream never reaches this, because the
        // gate decided that before the connection was used. The refusal stays
        // because reaching it would mean the gate and this dispatch disagree.
        _ => Err(crate::error::Failure::usage(
            "usage.not_a_flow",
            "this command has no rows to stream",
        )),
    }
}

/// Streams one read, closing with the record that declares the set whole.
async fn read_as_a_flow<W: Write>(
    cli: &Cli,
    config: &crate::config::Config,
    session: &mut crate::conn::session::Session,
    context: &crate::commands::query::Context,
    writer: W,
    tail: &Envelope,
    args: &crate::cli::query::RunArgs,
) -> Result<u64> {
    // The same three guards the whole-answer path applies: nothing is relaxed
    // just because the rows leave one at a time.
    let text = crate::commands::query::statement_text(
        &args.statement,
        crate::settings::no_input(&cli.globals),
        context.policy.max_input_bytes,
    )?;
    let gated = crate::exec::gate(&text, &args.statement.params, &context.policy)?;
    // The exact statement reaches the auxiliary channel here, as it does on the
    // whole-answer path. It did not, and nobody noticed while the shapes that
    // stream were the ones a diagnostic is rarely read in: asking for the echo
    // and receiving nothing is the same silence as not asking.
    crate::exec::prepare::echo(&gated);
    crate::exec::read::refuse_if_not_a_read(&gated)?;

    // The resolved shape, so a stored line-oriented shape reaches the flow it
    // promises rather than being written by the path that gathers first.
    let format = crate::output_shape(cli, config)?;
    // The operations travel with the flow rather than waiting for a gathered
    // payload, so the ceiling stops the pull instead of trimming a set that was
    // already read into memory.
    let pipeline = cli.globals.pipeline(config)?;

    // The rows the resume mark passes over still have to arrive, because the
    // flow passes over them here rather than the server skipping them. This is
    // the same reach the gathered path is given, and giving the two different
    // reaches would answer one request two different ways.
    let reach = context
        .policy
        .max_rows
        .saturating_add(pipeline.cursor.unwrap_or(0));

    // Both sides are given the same reach on purpose: the statement asks for
    // one row beyond it and the flow stops at it, so the extra row can only
    // ever be read as the witness that the answer was cut.
    let widened = crate::exec::read::with_ceiling(gated, reach, context.policy.parse)?;

    crate::exec::read::stream(
        session.connection(),
        &widened,
        crate::output::stream::Sink {
            writer,
            formatter: crate::output::format::for_format(format),
            tail,
        },
        &pipeline,
        &context.conversion,
        reach,
        &context.token,
    )
    .await
}

/// Streams a run of a file, one record per statement as each one finishes.
///
/// FR-028 publishes a result for every command in the file, and Proof 5 asks
/// that a long file cost no more at its end than at its start. Both are kept
/// by emitting each record as its statement finishes rather than gathering
/// them: the file is cut as a walk, and nothing here holds a collection that
/// grows with the count of statements.
///
/// Every guard the whole-answer path applies is applied here, and by the same
/// code: the statements go through [`crate::exec::script::stream_file`], which
/// admits each one exactly as a gathered run does. Nothing is relaxed because
/// the records leave one at a time.
async fn file_as_a_flow<W: Write>(
    cli: &Cli,
    config: &crate::config::Config,
    session: &mut crate::conn::session::Session,
    context: &mut crate::commands::query::Context,
    writer: W,
    tail: &Envelope,
    args: &crate::cli::query::FileArgs,
) -> Result<u64> {
    let (text, delimiter) = crate::commands::query_change::script_to_run(args, &context.policy)?;
    let statements = crate::exec::script::split(&text, &delimiter)?;

    // The resolved shape, so a stored line-oriented shape reaches the flow it
    // promises rather than being written by the path that gathers first.
    let format = crate::output_shape(cli, config)?;
    let pipeline = cli.globals.pipeline(config)?;
    let server_read_only = session.facts().read_only;

    let mut run = crate::exec::script::Run {
        stop_on_failure: crate::commands::query_change::stops_at_the_first_failure(args),
        conn: session.connection(),
        policy: &context.policy,
        write_state: &mut context.write_state,
        server_read_only,
        conversion: &context.conversion,
    };

    crate::exec::script::stream_file(
        statements,
        &mut run,
        crate::output::stream::Sink {
            writer,
            formatter: crate::output::format::for_format(format),
            tail,
        },
        &pipeline,
        &context.token,
    )
    .await
}

#[cfg(test)]
mod tests {
    use super::*;
    use clap::Parser;

    fn parse(args: &[&str]) -> Cli {
        let command_line: Vec<String> = std::iter::once("mariadb-cli")
            .chain(args.iter().copied())
            .map(ToOwned::to_owned)
            .collect();
        Cli::try_parse_from(command_line).expect("the sample invocation parses")
    }

    /// A settings location with nothing stored, so what these tests measure is
    /// the shape asked for and never a value somebody left behind.
    fn empty() -> (tempfile::TempDir, crate::config::Config) {
        let scratch = tempfile::tempdir().expect("scratch directory");
        let config =
            crate::config::Config::load(Some(scratch.path())).expect("an empty location loads");
        (scratch, config)
    }

    #[test]
    fn a_line_oriented_read_streams() {
        assert!(applies(
            &parse(&["--output-format", "ndjson", "query", "run", "SELECT 1"]),
            &empty().1
        ));
        assert!(applies(
            &parse(&["--output-format", "tsv", "query", "run", "SELECT 1"]),
            &empty().1
        ));
    }

    /// The built-in shape is one document, and one document is exactly what a
    /// read can be written into as its rows arrive.
    ///
    /// This once asserted the opposite, because the single document was
    /// assembled from rows that had all been gathered first. That made the
    /// shape almost every caller reads the one shape that could not read a set
    /// larger than memory.
    #[test]
    fn the_single_document_streams_a_read() {
        assert!(applies(&parse(&["query", "run", "SELECT 1"]), &empty().1));
        assert!(applies(
            &parse(&["--output-format", "json", "query", "run", "SELECT 1"]),
            &empty().1
        ));
    }

    /// A run of a file answers with a record per statement and a count of the
    /// statements, and the count is known only at the end. A document opened
    /// before the first record could not declare it, so the single document
    /// gathers that one rather than describing it with a payload it lacks.
    #[test]
    fn the_single_document_gathers_a_run_of_a_file() {
        assert!(!applies(
            &parse(&["--output-format", "json", "query", "file", "script.sql"]),
            &empty().1
        ));
        assert!(
            applies(
                &parse(&["--output-format", "ndjson", "query", "file", "script.sql"]),
                &empty().1
            ),
            "a shape that carries one record per line still streams it"
        );
    }

    /// `query run` runs a read or a change, and only a read has rows. A change
    /// used to reach the flow and meet a refusal telling it to use the very
    /// command it had used, which nobody saw while the shapes that stream were
    /// the ones a change is rarely written in.
    #[test]
    fn a_statement_that_changes_the_server_is_gathered_and_never_refused() {
        for shape in ["json", "ndjson", "tsv"] {
            for statement in ["DELETE FROM t WHERE a = 1", "CREATE TABLE t (a INT)"] {
                assert!(
                    !applies(
                        &parse(&["--output-format", shape, "query", "run", statement]),
                        &empty().1
                    ),
                    "`{shape}` streamed `{statement}`, which has no rows to stream"
                );
            }
        }
    }

    /// A statement the call did not write down cannot be classified without
    /// consuming the standard input the work itself has to read, so it is
    /// gathered. The two ways of writing a statement still answer with the same
    /// bytes, which is what the caller was promised.
    #[test]
    fn a_statement_read_from_the_input_is_gathered() {
        assert!(!applies(
            &parse(&["--output-format", "ndjson", "query", "run", "--stdin"]),
            &empty().1
        ));
    }

    /// A statement nothing can parse must be refused by the path that reports
    /// every other malformed request, and never half-written as a flow.
    #[test]
    fn a_statement_that_cannot_be_parsed_is_never_streamed() {
        assert!(!applies(
            &parse(&["--output-format", "ndjson", "query", "run", "SELECT FROM"]),
            &empty().1
        ));
    }

    /// The one shape meant for a person is an aligned table, and a width is a
    /// property of every cell in a column.
    #[test]
    fn the_shape_meant_for_a_person_never_streams() {
        assert!(!applies(
            &parse(&["--output-format", "text", "query", "run", "SELECT 1"]),
            &empty().1
        ));
    }

    #[test]
    fn a_command_without_rows_never_streams() {
        assert!(!applies(
            &parse(&["--output-format", "ndjson", "schema", "tables"]),
            &empty().1
        ));
        assert!(!applies(
            &parse(&["--output-format", "ndjson", "meta", "version"]),
            &empty().1
        ));
    }

    /// An operation that decides one row on its own is a stage of the flow, so
    /// asking for it must not cost the whole set being gathered.
    #[test]
    fn a_per_row_operation_still_streams() {
        for operation in [
            vec!["--limit", "10"],
            vec!["--filter", "id=1"],
            vec!["--select", "id"],
            vec!["--dedupe-by", "id"],
            vec!["--truncate-cell", "20"],
            vec!["--max-output-bytes", "4096"],
        ] {
            let argv: Vec<&str> = vec!["--output-format", "ndjson"]
                .into_iter()
                .chain(operation.iter().copied())
                .chain(["query", "run", "SELECT 1"])
                .collect();
            assert!(
                applies(&parse(&argv), &empty().1),
                "`{argv:?}` must still stream"
            );
        }
    }

    /// An answer that is a property of the whole set cannot be decided row by
    /// row, so those requests are gathered instead.
    #[test]
    fn an_answer_over_the_whole_set_takes_the_whole_answer_path() {
        for operation in [
            vec!["--sort", "id"],
            vec!["--count-only"],
            vec!["--checksum"],
        ] {
            let argv: Vec<&str> = vec!["--output-format", "ndjson"]
                .into_iter()
                .chain(operation.iter().copied())
                .chain(["query", "run", "SELECT 1"])
                .collect();
            assert!(
                !applies(&parse(&argv), &empty().1),
                "`{argv:?}` must be gathered"
            );
        }
    }

    /// Combining a per-row stage with one that needs the whole set is decided
    /// by the one that needs the whole set, or the order would be wrong.
    #[test]
    fn one_gathering_operation_is_enough_to_gather() {
        assert!(!applies(
            &parse(&[
                "--output-format",
                "ndjson",
                "--limit",
                "10",
                "--sort",
                "id",
                "query",
                "run",
                "SELECT 1"
            ]),
            &empty().1
        ));
    }
}