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
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
//! Sending a file's rows to a table, one committed batch at a time.
//!
//! # Who opens the file
//!
//! This process does, always. The server has an ability to open a file on the
//! client's behalf, and that ability is a way for a server to ask for any file
//! the client can read. It stays off, and nothing here asks for it. Reading
//! the bytes is [`super::import_rows`]; this file only sends what it produced.
//!
//! # Why the load commits as it goes
//!
//! A load of a million rows inside one transaction either finishes or leaves
//! nothing at all, after an hour of work. Committing in batches keeps the work
//! already done, and each committed batch publishes the offset it reached, so
//! a load interrupted at row eight hundred thousand resumes from there.
//!
//! # Why a refused row does not stop the load
//!
//! One row of a million that does not match the column types is a fact about
//! that row. Every refusal carries its own reason and its own position,
//! because "nine hundred rows were refused" tells the caller nothing.

use super::import_rows::{self, Batch, Rejection};
use crate::conn::{map_driver_error, OrFailure};
use crate::error::{Failure, Result};
use crate::sql::ident;
use mysql_async::prelude::Queryable;
use mysql_async::{Conn, Params, Value as Wire};
use std::path::PathBuf;
use tokio_util::sync::CancellationToken;

/// What the caller asked to be loaded, and where.
#[derive(Debug, Clone)]
pub struct ImportRequest {
    /// The file to read.
    pub file: PathBuf,
    /// The table the rows go into.
    pub table: String,
    /// The database holding that table; absent means the session's own.
    pub database: Option<String>,
    /// How many rows one committed batch carries.
    pub batch_size: usize,
    /// The offset a previous run reached, to continue from.
    pub resume_from: u64,
    /// What separates one field from the next.
    pub separator: u8,
    /// Whether the first line names the columns.
    pub header: bool,
    /// Whether a refused row stops the whole load.
    pub stop_on_refusal: bool,
}

/// What the load turned out to be.
#[derive(Debug, Clone)]
pub struct ImportReport {
    /// How many rows were read out of the file.
    pub rows_read: u64,
    /// How many rows the table now holds that it did not before.
    pub rows_written: u64,
    /// Every refused row, with its own reason.
    pub rejected: Vec<Rejection>,
    /// The offset a later run resumes from.
    pub offset: u64,
    /// The columns the rows were written into.
    pub columns: Vec<String>,
}

/// The statement one batch is sent as.
///
/// Values travel as parameters and never inside the statement text, so nothing
/// a file happens to contain can become part of the statement.
///
/// # Errors
///
/// Returns a validation failure when a name has no quotable form.
pub fn statement(table: &str, columns: &[String], rows: usize, width: usize) -> Result<String> {
    let quoted = ident::quote(table)?;
    let names = if columns.is_empty() {
        String::new()
    } else {
        let quoted_columns = columns
            .iter()
            .map(|name| ident::quote(name))
            .collect::<Result<Vec<_>>>()?;
        format!(" ({})", quoted_columns.join(", "))
    };

    let placeholders = vec!["?"; width].join(", ");
    let tuples = vec![format!("({placeholders})"); rows].join(", ");
    Ok(format!("INSERT INTO {quoted}{names} VALUES {tuples}"))
}

/// Runs the load from start to finish.
///
/// # Errors
///
/// Returns a configuration failure when the file cannot be read, an
/// interrupted failure when the invocation is told to stop between batches,
/// and a validation failure when a row was refused and the caller asked to
/// stop at the first. Batches committed before that point stay committed, and
/// the offset says where they ended.
pub async fn run(
    connection: &mut Conn,
    request: &ImportRequest,
    token: &CancellationToken,
) -> Result<ImportReport> {
    // Opened rather than read: the file is walked one batch at a time, so a
    // file larger than memory loads under the ceiling `batch_size` names. The
    // walk is also why refusals surface as they are met instead of all at once
    // before the first row goes in, which is what the paragraph above always
    // described and what the reading finally does.
    let mut batches = import_rows::Batches::open(&request.file, request)?;
    let columns: Vec<String> = batches.columns().to_vec();
    let mut report = ImportReport {
        rows_read: 0,
        rows_written: 0,
        rejected: Vec::new(),
        offset: request.resume_from,
        columns: columns.clone(),
    };

    while let Some(batch) = batches.next_batch() {
        // Named as they are met, so a person watching a long load learns of a
        // malformed file while there is still time to stop it.
        for rejection in batches.take_rejected() {
            crate::i18n::report::load_row_rejected(rejection.row, &rejection.reason);
            if request.stop_on_refusal {
                report.rows_read = batches.rows_read();
                let failure = refused(&rejection);
                report.rejected.push(rejection);
                return Err(failure);
            }
            report.rejected.push(rejection);
        }

        if token.is_cancelled() {
            report.rows_read = batches.rows_read();
            return Err(stopped(&report));
        }
        commit_batch(connection, request, &columns, &batch, &mut report).await?;
    }

    // The tail: rows refused after the last full batch, which no round above
    // reached because there was no batch left to carry them.
    for rejection in batches.take_rejected() {
        crate::i18n::report::load_row_rejected(rejection.row, &rejection.reason);
        if request.stop_on_refusal {
            report.rows_read = batches.rows_read();
            let failure = refused(&rejection);
            report.rejected.push(rejection);
            return Err(failure);
        }
        report.rejected.push(rejection);
    }
    report.rows_read = batches.rows_read();

    crate::i18n::report::load_finished(report.rows_written, report.rejected.len() as u64);
    Ok(report)
}

/// The failure an interrupted load produces.
///
/// The offset is in the message because it is the one thing the caller needs
/// to carry into the next run, and losing it would mean starting again.
fn stopped(report: &ImportReport) -> Failure {
    Failure::interrupted(
        "interrupted.during_load",
        format!(
            "the invocation was stopped after {} rows; resume from offset {}",
            report.rows_written, report.offset
        ),
    )
    .with_detail("detail", report.offset.to_string())
}

/// Sends one batch and confirms it, or records why it was refused.
async fn commit_batch(
    connection: &mut Conn,
    request: &ImportRequest,
    columns: &[String],
    batch: &Batch,
    report: &mut ImportReport,
) -> Result<()> {
    let Some(width) = batch.rows.first().map(Vec::len) else {
        return Ok(());
    };
    let text = statement(&request.table, columns, batch.rows.len(), width)?;
    let values: Vec<Wire> = batch
        .rows
        .iter()
        .flat_map(|row| row.iter().map(|field| Wire::from(field.as_str())))
        .collect();

    match connection
        .exec_drop(&text, Params::Positional(values))
        .await
    {
        Ok(()) => {
            report.rows_written += batch.rows.len() as u64;
            report.offset = batch.end;
            let committed = confirm(connection).await;
            if committed.is_ok() {
                crate::i18n::report::load_batch_committed(report.rows_written, report.offset);
            }
            committed
        }
        Err(error) => {
            let failure = map_driver_error(&error);
            if !is_about_the_rows(&failure) {
                return Err(failure);
            }
            if request.stop_on_refusal {
                // Told as a refused row, not as the server's raw condition.
                //
                // A row the reader caught before sending ends in 3 as
                // `datamove.row_refused`, and FR-115 publishes 3. The same row
                // caught by the server used to end in 11 as a server condition,
                // so one kind of refusal was told two ways, decided by which
                // side of the wire noticed it first.
                //
                // The batch is what the server named, so the position given is
                // where the batch began rather than the row itself. That is
                // less than the reader's own refusal can say, and it is what is
                // knowable without sending the rows again one at a time — which
                // was tried, and cost a file of refused rows being impossible
                // to load at all.
                let rejection = Rejection {
                    row: batch.start,
                    reason: failure.message().to_owned(),
                };
                report.offset = batch.start;
                let refusal = refused(&rejection);
                report.rejected.push(rejection);
                return Err(refusal);
            }
            note_lost_batch(batch, failure.message(), report);
            Ok(())
        }
    }
}

/// Whether a refusal could have been caused by the rows that were sent.
///
/// # Why the skip policy needs this
///
/// FR-115 scopes the choice between stopping and skipping to one condition: "a
/// row does not match a type". Everything the server refuses for some other
/// reason is a precondition that failed once, for the whole load, and has
/// nothing to do with any particular row.
///
/// Without this distinction the skip policy swallowed all of them. Loading into
/// a table that does not exist read every row, wrote none, recorded one
/// rejection per row saying "the named object does not exist", and ended in 0 —
/// so a caller reading the exit code was told the load succeeded. Its sibling
/// `data export` answers the same missing table with `datamove.table_absent`
/// and ends in 8. Two commands of one family gave opposite answers to one
/// condition, and only the quiet one was reachable by an agent.
///
/// # Why this names what may be skipped rather than what may not
///
/// The first form of this listed the structural categories and skipped
/// everything else. It read the same and fails the opposite way: a category
/// added to the enum later would land in the skipping branch by saying nothing,
/// and the defect above would come back without anybody deciding it should.
///
/// Named this way round, a new category propagates until somebody writes it
/// down here. The cost of being wrong is then a load that stops and reports a
/// real error, instead of one that reports success having written nothing.
///
/// Three may be skipped, and each is something one row genuinely does:
/// `Conflict` is the key another row already holds, `Limit` is a value past a
/// ceiling, and `Server` is a condition the server states without a category of
/// its own, which is where a type mismatch arrives. Everything else — the table
/// is absent, the grant is missing, the credential is refused, the channel
/// broke, the clock ran out — failed once for the whole load, and reporting it
/// once per row turns one structural failure into N data ones at a severity
/// that costs the exit code.
fn is_about_the_rows(failure: &Failure) -> bool {
    use crate::error::Category;
    // Asked first, because it cuts across the three below rather than sitting
    // beside them. `Conflict` is not one thing: a duplicate key is the row's
    // own doing and is marked as not worth repeating, while a deadlock and a
    // wait for a lock are another session's doing and are marked as worth
    // repeating — the hint on a deadlock says, in the product's own words, to
    // repeat the call. `Server` splits the same way: a condition stated without
    // a category of its own is permanent, and having no free connection is not.
    //
    // Recording any of those as a refused row throws away work the product has
    // just said to retry, permanently, and reports success while doing it. So
    // whatever the category, a failure the product marks as repeatable belongs
    // to the caller and not to a row.
    if failure.is_retryable() {
        return false;
    }
    matches!(
        failure.category(),
        Category::Conflict | Category::Limit | Category::Server
    )
}

/// Records a batch the server would not take, row by row.
///
/// Each row is named with the reason the server gave rather than folded into a
/// single count, and the offset still moves past them so a later run does not
/// meet the same batch again.
///
/// # Why this is not per-row attribution
///
/// The server refuses a BATCH and names one condition, so every row here
/// carries a reason that is true of at most one of them. That is a known cost,
/// stated rather than hidden.
///
/// It was replaced once, by re-sending the refused range in halves to find the
/// row that was really refused, and that was reverted after measurement. The
/// replacement was right about the common case — one bad row in a thousand cost
/// 1,71 s against 0,52 s — and wrong about three others an independent audit
/// measured: a file of a thousand rows where every row is refused did not load
/// AT ALL under any batch size, hitting the thirty second phase ceiling and
/// coming back as a retryable timeout; nine hundred rows already accepted were
/// lost because the error path returns without committing; and a batch holding
/// a row the reader had rejected locally shifted every position after it, so a
/// refusal named a row that had been written and stayed silent about the one
/// that failed.
///
/// A file where most rows are refused is exactly what skipping exists for, so
/// making that file impossible to load is a worse trade than a shared reason.
fn note_lost_batch(batch: &Batch, reason: &str, report: &mut ImportReport) {
    // Walked over the rows that were SENT, not over the span of file positions
    // the batch covers. The two are not the same: a line the reader refused —
    // too few fields for the header — never reaches `rows`, and counting the
    // span instead invented a refusal for it. An audit measured the result:
    // four lines read, FIVE refusals reported, one position named twice with
    // two reasons that contradicted each other, and one of them a reason from a
    // server that had never seen the line.
    //
    // The position comes from the row itself, not from arithmetic on where the
    // batch began, so a hole shifts nothing: `Batch::positions` records where
    // each row it carries really came from.
    for &position in &batch.positions {
        crate::i18n::report::load_row_rejected(position, reason);
        report.rejected.push(Rejection {
            row: position,
            reason: reason.to_owned(),
        });
    }
    report.offset = batch.end;
}

/// Confirms the batch just sent.
async fn confirm(connection: &mut Conn) -> Result<()> {
    connection.query_drop("COMMIT").await.or_failure()
}

/// The failure a refused row produces when the caller asked to stop at the first.
fn refused(rejection: &Rejection) -> Failure {
    Failure::validation(
        "datamove.row_refused",
        format!("row {} was refused: {}", rejection.row, rejection.reason),
    )
    .with_detail("detail", rejection.row.to_string())
    .with_hint("ask for refused rows to be skipped instead, to load the rest")
}

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

    fn report() -> ImportReport {
        ImportReport {
            rows_read: 4,
            rows_written: 2,
            rejected: Vec::new(),
            offset: 2,
            columns: Vec::new(),
        }
    }

    #[test]
    fn the_statement_carries_placeholders_and_never_the_values() {
        let text = statement("customers", &["id".to_owned(), "name".to_owned()], 2, 2)
            .expect("legal names");
        assert_eq!(
            text,
            "INSERT INTO `customers` (`id`, `name`) VALUES (?, ?), (?, ?)"
        );
    }

    #[test]
    fn a_file_that_names_no_columns_writes_into_the_table_as_declared() {
        let text = statement("customers", &[], 1, 3).expect("legal names");
        assert_eq!(text, "INSERT INTO `customers` VALUES (?, ?, ?)");
    }

    #[test]
    fn a_name_this_product_will_not_write_is_refused_before_any_row_is_sent() {
        assert!(statement("", &[], 1, 1).is_err(), "a nameless table");
        assert!(
            statement("customers", &["with\u{0}a control".to_owned()], 1, 1).is_err(),
            "a column name with no quotable form"
        );
    }

    #[test]
    fn a_delimiter_inside_a_name_cannot_end_the_name_early() {
        let text = statement("odd`name", &[], 1, 1).expect("quotable");
        assert_eq!(text, "INSERT INTO `odd``name` VALUES (?)");
    }

    #[test]
    fn stopping_at_the_first_refusal_ends_in_the_published_number() {
        let failure = refused(&Rejection {
            row: 7,
            reason: "the line carries 1 field where the header names 2".to_owned(),
        });
        assert_eq!(failure.exit_number().code(), 3);
        assert!(failure.message().contains('7'));
    }

    /// Only what a row can cause may be skipped, and never what may be retried.
    ///
    /// # Why this replaced a proof of the opposite
    ///
    /// A proof stood here that a refused batch named every row in it. That was
    /// the behaviour, and it was the defect: the batch is how the rows travel,
    /// so writing one condition against all of them said something false about
    /// every row but one, and with the stored batch size at a thousand it did
    /// so up to nine hundred and ninety nine times, ending in 0.
    ///
    /// What is worth proving is the decision that replaced it, and the case an
    /// audit could not reach from the outside: a deadlock and a wait for a lock
    /// are `Conflict`, exactly like a duplicate key, and the category alone
    /// cannot tell them apart. The product already marks the difference — it
    /// says a deadlock is worth repeating and tells the caller to repeat the
    /// call — so recording one as a permanently refused row throws away work
    /// the product has just said to try again, and reports success doing it.
    #[test]
    fn only_a_refusal_a_row_can_cause_and_nobody_should_retry_is_skipped() {
        let constraint =
            Failure::conflict("conflict.constraint", "a key is held").with_retryable(false);
        let too_long = Failure::limit("limit.value", "past a ceiling");
        let stated = Failure::server("server.condition", "the value will not go in");
        assert!(
            is_about_the_rows(&constraint),
            "a held key is the row's own"
        );
        assert!(is_about_the_rows(&too_long), "a ceiling is the row's own");
        assert!(
            is_about_the_rows(&stated),
            "a stated condition may be the row"
        );

        let deadlock = Failure::conflict("conflict.deadlock", "the change hit a deadlock")
            .with_retryable(true);
        let no_room = Failure::server("server.too_many_connections", "no room right now")
            .with_retryable(true);
        let absent = Failure::absence("absence.unknown_object", "there is no such table");
        assert!(
            !is_about_the_rows(&deadlock),
            "a deadlock is another session's doing, and the product says to repeat it"
        );
        assert!(
            !is_about_the_rows(&no_room),
            "having no free connection is not a property of any row"
        );
        assert!(
            !is_about_the_rows(&absent),
            "a table that is not there failed once, for the whole load"
        );
    }

    /// Every category states, by name, which side of the decision it falls on.
    ///
    /// # Why the proof above does not settle this
    ///
    /// The proof above names six failures and reaches four of the thirteen
    /// categories. A mutation measured on 2026-08-14 added `Permission` to the
    /// list this function matches on, and the whole suite stayed green while
    /// the binary reproduced the very defect the list exists to prevent: a
    /// credential that may not insert came back as two refused rows and an exit
    /// of zero, when the load had no permission to begin.
    ///
    /// Naming what may be skipped guards against a category added to the enum.
    /// It does not guard against a category added to the *list*, because
    /// membership is the thing under test, and a proof that names three members
    /// says nothing about the other ten. So this walks all thirteen and states a
    /// verdict for each. The match is exhaustive on purpose: a category added to
    /// the enum stops the compilation here until somebody decides which side it
    /// falls on, rather than defaulting to whichever side is written first.
    ///
    /// Every failure here is built as not worth repeating, so that what is
    /// measured is the membership alone. The guard that sends a repeatable
    /// failure back to the caller regardless of category is proved above.
    #[test]
    fn every_category_states_whether_a_row_can_cause_it() {
        use crate::error::Category;

        for category in Category::ALL {
            let a_row_can_cause_it = match category {
                // The value the row carries is the reason the server gave.
                Category::Conflict | Category::Limit | Category::Server => true,
                // None of these is a property of any one row: each one failed
                // once, for the whole load, and skipping past it would report
                // success for work that never happened.
                Category::Usage
                | Category::Validation
                | Category::Config
                | Category::Network
                | Category::Authentication
                | Category::Permission
                | Category::Absence
                | Category::Timeout
                | Category::Interrupted
                | Category::ChannelClosed => false,
            };
            let failure = Failure::new(category, "test.condition", "a stated condition")
                .with_retryable(false);
            assert_eq!(
                is_about_the_rows(&failure),
                a_row_can_cause_it,
                "{category:?} must be decided by name, not by whichever side the list happens to hold"
            );
        }
    }

    /// An interrupted load must hand back the mark, or the work already
    /// committed has to be done again.
    #[test]
    fn an_interrupted_load_says_where_to_resume_from() {
        let failure = stopped(&report());
        assert_eq!(failure.exit_number().code(), 130);
        assert!(
            failure.message().contains("offset 2"),
            "{}",
            failure.message()
        );
        assert!(failure.message().contains('2'));
    }
}