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
//! Cutting a file of statements into the statements it carries.
//!
//! # The cut is made over the blanked text, never over the raw one
//!
//! A separator inside a text literal, a quoted name or a comment is not a
//! separator. [`crate::sql::strip()`] replaces every such region with as many
//! spaces as it had bytes, so the blanked text keeps the offsets of the
//! original: the search runs over the blanked text, the cut is applied to the
//! original, and every byte the caller wrote survives.
//!
//! # Why the separator can be redefined
//!
//! A routine body carries separators of its own. Without a way to redefine the
//! separator, such a file would be cut in the middle of the body and each
//! fragment sent as a statement of its own. The redefinition is a directive of
//! the file, is never sent to the server, and applies only inside the file it
//! appears in. It never relaxes the rule that one call carries one statement.
//!
//! Running the statements this module produces is [`super::script`]. Cutting a
//! file and running it are different jobs: the cut is pure and provable without
//! a server, and everything here is tested that way.

use crate::error::{Failure, Result};
use crate::sql::strip::strip;

/// The directive that redefines the separator inside a file.
const DIRECTIVE: &str = "delimiter";

/// One statement taken out of a file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Piece {
    /// Its position in the file, counted from one.
    pub index: usize,
    /// The line the statement starts on, counted from one.
    pub line: usize,
    /// The statement itself, exactly as the caller wrote it.
    pub sql: String,
}

/// Refuses a separator that could never separate anything.
///
/// # Errors
///
/// Returns a usage failure for an empty separator, before any file is read.
pub fn validate_delimiter(delimiter: &str) -> Result<()> {
    if delimiter.trim().is_empty() {
        return Err(Failure::usage(
            "usage.empty_delimiter",
            "the statement separator is empty, so it could never separate anything",
        )
        .with_hint("give a separator such as ; or $$"));
    }
    Ok(())
}

/// Cuts a file into the statements it carries, one at a time.
///
/// The statements are produced as they are asked for, so what a run of a long
/// file costs is its longest statement and never the whole file cut up. Every
/// refusal the file can earn is still decided here, before the first statement
/// is handed out: a caller that gets a walk has a file that will not be refused
/// halfway through, once part of it has already reached the server.
///
/// # Errors
///
/// Returns a usage failure for an empty separator, and a validation failure
/// when a region of the file is left open or when a redefined separator is
/// never restored.
pub fn split<'a>(text: &'a str, delimiter: &str) -> Result<Statements<'a>> {
    validate_delimiter(delimiter)?;
    let blanked = strip(text);
    blanked.refuse_if_unterminated()?;

    let mut cut = Cut::new(text, blanked.text().to_owned(), delimiter);
    // The refusal a redefined separator earns belongs to the file as a whole,
    // so it is decided by a walk that keeps no statement rather than by the
    // walk the caller consumes. Deciding it lazily would let the statements
    // before the offending line reach the server and only then refuse the file.
    while cut.next_piece().is_some() {}
    if let Some(line) = cut.redefined_at {
        return Err(Failure::validation(
            "script.delimiter_not_restored",
            format!("the separator was redefined on line {line} and never restored"),
        )
        .with_detail("detail", format!("L{line}"))
        .with_hint("add a line restoring the separator before the file ends"));
    }
    cut.rewind();
    Ok(Statements { cut })
}

/// The statements of one file, produced one at a time.
///
/// Holding this holds the file's text and its blanked twin, both of which the
/// cut reads without copying. What it never holds is the statements: each one
/// is built when it is asked for and dropped when the caller is done with it.
#[derive(Debug)]
pub struct Statements<'a> {
    cut: Cut<'a>,
}

impl Iterator for Statements<'_> {
    type Item = Piece;

    fn next(&mut self) -> Option<Piece> {
        self.cut.next_piece()
    }
}

/// The walk over one file, carrying where it is and nothing it has passed.
#[derive(Debug)]
struct Cut<'a> {
    original: &'a str,
    masked: String,
    initial: String,
    active: String,
    /// Where the directive last changed the separator, when it did.
    redefined_at: Option<usize>,
    /// Where the statement being cut begins.
    start: usize,
    /// Where the line being read begins.
    offset: usize,
    /// Where the search for a separator resumes, once a line is being read.
    cursor: Option<usize>,
    /// Where the line being read ends.
    line_end: usize,
    /// How many statements have been handed out, which is the next index.
    handed_out: usize,
    /// Whether the tail has been reached.
    spent: bool,
    /// How many line breaks lie before [`Self::counted_upto`].
    breaks_before: usize,
    /// How far the count of line breaks has been carried.
    counted_upto: usize,
}

impl<'a> Cut<'a> {
    fn new(original: &'a str, masked: String, delimiter: &str) -> Self {
        Self {
            original,
            masked,
            initial: delimiter.to_owned(),
            active: delimiter.to_owned(),
            redefined_at: None,
            start: 0,
            offset: 0,
            cursor: None,
            line_end: 0,
            handed_out: 0,
            spent: false,
            breaks_before: 0,
            counted_upto: 0,
        }
    }

    /// Puts the walk back at the start of the file.
    fn rewind(&mut self) {
        self.active.clone_from(&self.initial);
        self.redefined_at = None;
        self.start = 0;
        self.offset = 0;
        self.cursor = None;
        self.line_end = 0;
        self.handed_out = 0;
        self.spent = false;
        self.breaks_before = 0;
        self.counted_upto = 0;
    }

    /// The next statement, or nothing once the file is spent.
    ///
    /// The walk is line by line, because the directive is line-shaped, and it
    /// resumes inside a line, because a line may end more than one statement.
    fn next_piece(&mut self) -> Option<Piece> {
        loop {
            if self.spent {
                return None;
            }
            if self.offset >= self.masked.len() {
                // A last statement written without a separator is not lost.
                self.spent = true;
                return self.take(self.start..self.original.len());
            }
            let Some(cursor) = self.cursor else {
                self.line_end = self.masked[self.offset..]
                    .find('\n')
                    .map_or(self.masked.len(), |found| self.offset + found);
                if self.take_directive(self.offset, self.line_end) {
                    self.offset = self.line_end + 1;
                } else {
                    self.cursor = Some(self.offset);
                }
                continue;
            };
            let Some(found) = self.masked[cursor..self.line_end].find(self.active.as_str()) else {
                self.cursor = None;
                self.offset = self.line_end + 1;
                continue;
            };
            let at = cursor + found;
            let region = self.start..at;
            self.cursor = Some(at + self.active.len());
            self.start = at + self.active.len();
            if let Some(piece) = self.take(region) {
                return Some(piece);
            }
        }
    }

    /// Consumes a separator directive, when this line is one.
    ///
    /// The directive counts only where a statement could begin, so the same
    /// word inside a statement is left alone.
    fn take_directive(&mut self, from: usize, to: usize) -> bool {
        if !self.masked[self.start..from].trim().is_empty() {
            return false;
        }
        let line = self.masked[from..to].trim_start();
        let leading = to - from - line.len();
        if line.len() < DIRECTIVE.len()
            || !line[..DIRECTIVE.len()].eq_ignore_ascii_case(DIRECTIVE)
            || !line[DIRECTIVE.len()..].starts_with(char::is_whitespace)
        {
            return false;
        }

        let declared = self.original[from + leading + DIRECTIVE.len()..to].trim();
        if declared.is_empty() {
            return false;
        }
        self.active = declared.to_owned();
        self.redefined_at = (self.active != self.initial).then(|| self.line_of(from));
        self.start = to.min(self.masked.len());
        true
    }

    /// Builds one statement, unless the region holds nothing but blank space.
    ///
    /// The line reported is the one the statement starts on, not the one the
    /// region does: a region begins right after the previous separator, so its
    /// own line is the line the predecessor ended on.
    fn take(&mut self, region: std::ops::Range<usize>) -> Option<Piece> {
        let whole = &self.original[region.clone()];
        let text = whole.trim();
        if text.is_empty() {
            return None;
        }
        let leading = whole.len() - whole.trim_start().len();
        let sql = text.to_owned();
        let line = self.line_of(region.start + leading);
        self.handed_out += 1;
        Some(Piece {
            index: self.handed_out,
            line,
            sql,
        })
    }

    /// The line one offset falls on, counted from one.
    ///
    /// The count is carried forward rather than made from the start of the
    /// file each time, or a file of many statements would cost the square of
    /// its length to cut. The walk only ever moves forward, and the guard is
    /// there so that a caller who rewinds it still gets the right line.
    fn line_of(&mut self, offset: usize) -> usize {
        if offset < self.counted_upto {
            self.counted_upto = 0;
            self.breaks_before = 0;
        }
        self.breaks_before += self.original[self.counted_upto..offset]
            .matches('\n')
            .count();
        self.counted_upto = offset;
        self.breaks_before + 1
    }
}

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

    fn pieces(text: &str, delimiter: &str) -> Vec<Piece> {
        split(text, delimiter)
            .expect("the file must split")
            .collect()
    }

    fn statements(text: &str, delimiter: &str) -> Vec<String> {
        pieces(text, delimiter).into_iter().map(|p| p.sql).collect()
    }

    #[test]
    fn a_file_is_cut_at_every_separator_and_each_piece_knows_its_position() {
        let cut = pieces("SELECT 1;\nSELECT 2;\n", ";");
        assert_eq!(cut.len(), 2);
        assert_eq!(
            cut[0],
            Piece {
                index: 1,
                line: 1,
                sql: "SELECT 1".to_owned()
            }
        );
        assert_eq!(
            cut[1],
            Piece {
                index: 2,
                line: 2,
                sql: "SELECT 2".to_owned()
            }
        );

        assert_eq!(
            statements("SELECT 1;\nSELECT 2", ";"),
            vec!["SELECT 1".to_owned(), "SELECT 2".to_owned()],
            "a last statement written without a separator is not lost"
        );
        for nothing in ["", "\n\n  \n", ";;;"] {
            assert!(pieces(nothing, ";").is_empty(), "input {nothing:?}");
        }
    }

    /// A separator inside a literal, a quoted name or a comment is not a
    /// separator, or a legitimate file would be cut in the middle.
    #[test]
    fn a_separator_that_is_not_one_never_cuts_the_file() {
        for (file, whole) in [
            ("SELECT 'a;b' AS note;\n", "SELECT 'a;b' AS note"),
            ("SELECT 1 AS `a;b`;\n", "SELECT 1 AS `a;b`"),
            ("SELECT 1 -- ; not a cut\n;\n", "SELECT 1 -- ; not a cut"),
            ("SELECT /* ; */ 1;\n", "SELECT /* ; */ 1"),
        ] {
            assert_eq!(
                statements(file, ";"),
                vec![whole.to_owned()],
                "input {file:?}"
            );
        }
    }

    /// The reason the directive exists: a routine body carries separators of
    /// its own and must reach the server whole.
    #[test]
    fn a_routine_body_with_inner_separators_reaches_the_server_whole() {
        let file = "DELIMITER $$\n\
                    CREATE PROCEDURE p()\n\
                    BEGIN\n\
                      SELECT 1;\n\
                      SELECT 2;\n\
                    END$$\n\
                    DELIMITER ;\n\
                    SELECT 3;\n";
        let cut = statements(file, ";");
        assert_eq!(cut.len(), 2, "the body is one statement, got {cut:?}");
        assert!(cut[0].starts_with("CREATE PROCEDURE p()"));
        assert!(
            cut[0].contains("SELECT 1;") && cut[0].contains("SELECT 2;"),
            "the inner separators survive: {}",
            cut[0]
        );
        assert_eq!(cut[1], "SELECT 3");

        // Redefined and never restored, the file is refused with its line.
        //
        // The refusal is earned by the whole file and is decided before the
        // walk is handed over, so no statement of a file that will be refused
        // can reach the server first. That is what `expect_err` proves here:
        // there is no walk at all to take a statement from.
        let unrestored = "SELECT 1;\nDELIMITER $$\nCREATE PROCEDURE p() BEGIN SELECT 1; END$$\n";
        let failure = split(unrestored, ";").expect_err("must refuse");
        assert_eq!(failure.code(), "script.delimiter_not_restored");
        assert!(failure.message().contains('2'), "the line is named");
    }

    /// The walk is asked twice for the same file and answers the same way.
    ///
    /// The refusal a redefined separator earns is decided by a walk of its own,
    /// so the walk the caller consumes is the second one over the same text.
    /// A position or an index carried over from the first would show here.
    #[test]
    fn the_walk_handed_to_the_caller_starts_where_the_file_does() {
        let file = "-- a note\nSELECT 1;\n\n\nDELIMITER $$\nSELECT 2$$\nDELIMITER ;\nSELECT 3;\n";
        let once = pieces(file, ";");
        let twice = pieces(file, ";");
        assert_eq!(once, twice, "the same file cut twice is the same cut");
        assert_eq!(
            once.iter().map(|p| (p.index, p.line)).collect::<Vec<_>>(),
            vec![(1, 1), (2, 6), (3, 8)],
            "got {once:?}"
        );
    }

    /// The directive belongs to the file and is never a statement; the same
    /// word inside a statement is not a directive at all.
    #[test]
    fn the_directive_is_never_sent_and_the_same_word_inside_a_statement_is_not_one() {
        for statement in statements("DELIMITER $$\nSELECT 1$$\nDELIMITER ;\n", ";") {
            assert!(
                !statement.to_lowercase().starts_with(DIRECTIVE),
                "the directive leaked into a statement: {statement}"
            );
        }
        assert_eq!(
            statements("SELECT a\nFROM delimiter x;\n", ";"),
            vec!["SELECT a\nFROM delimiter x".to_owned()]
        );
        assert_eq!(
            statements("SELECT 1$$SELECT 2$$", "$$"),
            vec!["SELECT 1".to_owned(), "SELECT 2".to_owned()],
            "a file may use a separator of its own from the start"
        );
    }

    #[test]
    fn a_file_that_could_never_be_split_is_refused_rather_than_cut_into_nonsense() {
        let failure = validate_delimiter("").expect_err("must refuse");
        assert_eq!(failure.code(), "usage.empty_delimiter");
        assert_eq!(failure.exit_number().code(), 2);
        assert_eq!(
            split("SELECT 1", "  ").expect_err("must refuse").code(),
            "usage.empty_delimiter"
        );
        assert_eq!(
            split("SELECT 'never closed;\n", ";")
                .expect_err("must refuse")
                .code(),
            "sql.unterminated_region"
        );
    }

    /// The line reported is the one the statement starts on, and a leading
    /// comment is part of the statement it introduces.
    #[test]
    fn the_positions_reported_survive_blank_lines_and_comments() {
        let file = "-- a note\n\n\nSELECT 1;\n\n-- another\nSELECT 2;\n";
        let cut = pieces(file, ";");
        assert_eq!(cut[0].line, 1, "a leading comment belongs to the statement");
        assert_eq!(cut[1].line, 6);
        assert!(cut[1].sql.starts_with("-- another"));

        // A statement is never reported on the line its predecessor ended on.
        let spaced = pieces("SELECT 1;\n\n\nSELECT 2;\n", ";");
        assert_eq!((spaced[0].line, spaced[1].line), (1, 4));
    }
}