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
//! What the product learns the moment a connection opens.
//!
//! Five different things need to be known before any real work starts: which
//! server this is, whether it refuses changes of its own accord, how it will
//! interpret the statements sent to it, which of its optional abilities are
//! present, and how large a command it will accept at all. Asking five times
//! would cost five round trips on every invocation of a one-shot tool, so all
//! five are read in a single query and carried together in [`ServerFacts`].

use super::OrFailure;
use crate::error::{Failure, Result};
use mysql_async::prelude::Queryable;
use mysql_async::Conn;
use serde::Serialize;
use serde_json::{json, Value};
use std::sync::atomic::{AtomicU64, Ordering};

/// The oldest server release this product is written against.
///
/// This is a contract, not a tuning knob: the product uses structures that
/// older releases do not have, so an older server is reported rather than
/// silently half-served.
pub const MINIMUM_SERVER_VERSION: (u16, u16) = (10, 11);

/// The single query that answers everything the invocation needs to know.
///
/// One statement, one round trip. Splitting it would multiply the cost of every
/// invocation by four for no gain.
const PROBE: &str = "SELECT \
     @@version, \
     @@version_comment, \
     @@read_only, \
     @@sql_mode, \
     @@autocommit, \
     DATABASE(), \
     CONNECTION_ID(), \
     @@max_allowed_packet";

/// The ceiling of a record built before any server answered one.
///
/// Zero rather than an absent value, because absence here is not a state a
/// caller has to handle: nothing measures a send against a record, and the one
/// place that does measure reads [`PacketCeiling`], which treats zero as "no
/// ceiling settled" for the same reason.
const CEILING_NOT_ANSWERED: u64 = 0;

/// The shape of one probe row, as the driver hands it over.
type ProbeRow = (String, String, i64, String, i64, Option<String>, u64, u64);

/// What the server said about itself when the connection opened.
// Allowed: each of these is a separate thing the server said about
// itself, and the record exists to carry the answers exactly as they
// were given. Grouping them would invent a category the server does
// not publish.
#[allow(clippy::struct_excessive_bools)]
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct ServerFacts {
    /// The version text the server reports.
    pub version: String,
    /// The version parts, for comparison.
    pub version_parts: (u16, u16, u16),
    /// The remark the server attaches to its version, naming the distribution.
    pub version_comment: String,
    /// Whether this is a MariaDB server rather than another server of the family.
    pub is_mariadb: bool,
    /// Whether the server refuses changes of its own accord.
    pub read_only: bool,
    /// How the server will interpret the statements sent to it.
    pub sql_mode: String,
    /// Whether the session confirms every statement by itself.
    pub autocommit: bool,
    /// The database in force, when one is.
    pub database: Option<String>,
    /// The identifier the server knows this connection by.
    pub connection_id: u64,
    /// The largest command, in bytes, this server will accept in one piece.
    ///
    /// Read here rather than probed on its own, because a command that does not
    /// fit has to be refused before it is sent and a second round trip to find
    /// that out would be paid by every invocation, including all the ones whose
    /// commands fit easily.
    pub max_allowed_packet: u64,
    /// Whether the server is new enough for everything this product does.
    pub meets_minimum_version: bool,
    /// The optional abilities present on this server.
    pub capabilities: Capabilities,
}

/// The optional abilities whose presence depends on the server.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
pub struct Capabilities {
    /// Tables can keep a version history.
    pub system_versioning: bool,
    /// Number generators exist as objects of their own.
    pub sequences: bool,
    /// Structured documents are checked rather than stored as plain text.
    pub checked_documents: bool,
}

impl Capabilities {
    /// Derives the optional abilities from the version and the distribution.
    ///
    /// Derivation is used rather than a probe of each ability, because probing
    /// would cost one round trip per ability on a tool that lives for one call.
    #[must_use]
    pub const fn derive(parts: (u16, u16, u16), is_mariadb: bool) -> Self {
        Self {
            system_versioning: is_mariadb && at_least(parts, 10, 3),
            sequences: is_mariadb && at_least(parts, 10, 3),
            checked_documents: is_mariadb && at_least(parts, 10, 4),
        }
    }
}

/// Whether these version parts reach the given release.
const fn at_least(parts: (u16, u16, u16), major: u16, minor: u16) -> bool {
    parts.0 > major || (parts.0 == major && parts.1 >= minor)
}

impl ServerFacts {
    /// Assembles the facts from the values the probe returned.
    ///
    /// Kept apart from the round trip so the whole derivation is testable
    /// without a server.
    #[must_use]
    pub fn from_probe(
        version: String,
        version_comment: String,
        read_only: bool,
        sql_mode: String,
        autocommit: bool,
        database: Option<String>,
        connection_id: u64,
    ) -> Self {
        let version_parts = parse_version(&version);
        let is_mariadb = version.to_ascii_lowercase().contains("mariadb")
            || version_comment.to_ascii_lowercase().contains("mariadb");
        Self {
            capabilities: Capabilities::derive(version_parts, is_mariadb),
            meets_minimum_version: meets_minimum(version_parts),
            version,
            version_parts,
            version_comment,
            is_mariadb,
            read_only,
            sql_mode,
            autocommit,
            database,
            connection_id,
            // Left unknown here and filled in by the caller that has the
            // probe's answer. This constructor is what derives one fact from
            // another — the distribution from the version, the abilities from
            // both — and the ceiling is derived from nothing: it is a number
            // the server states outright.
            max_allowed_packet: CEILING_NOT_ANSWERED,
        }
    }

    /// The facts as they appear in an answer.
    #[must_use]
    pub fn as_value(&self) -> Value {
        json!({
            "version": self.version,
            "version_comment": self.version_comment,
            "is_mariadb": self.is_mariadb,
            "read_only": self.read_only,
            "sql_mode": self.sql_mode,
            "autocommit": self.autocommit,
            "database": self.database,
            "connection_id": self.connection_id,
            "max_allowed_packet": self.max_allowed_packet,
            "meets_minimum_version": self.meets_minimum_version,
            "minimum_server_version": format!(
                "{}.{}",
                MINIMUM_SERVER_VERSION.0, MINIMUM_SERVER_VERSION.1
            ),
            "capabilities": self.capabilities,
        })
    }

    /// The warning an older server deserves, when it is one.
    ///
    /// A warning rather than a refusal: much of the surface works on an older
    /// server, and refusing outright would deny the caller the part that does.
    #[must_use]
    pub fn version_warning(&self) -> Option<String> {
        (!self.meets_minimum_version).then(|| {
            format!(
                "the server reports version {} and this product is written against {}.{} or newer; \
                 some commands may find structures this server does not have",
                self.version, MINIMUM_SERVER_VERSION.0, MINIMUM_SERVER_VERSION.1
            )
        })
    }
}

/// Reads everything the invocation needs to know, in one round trip.
///
/// # Errors
///
/// Returns the mapped driver failure when the query cannot be run, and a server
/// failure when the server answers nothing at all, which no working server does.
pub async fn probe(connection: &mut Conn) -> Result<ServerFacts> {
    let row: Option<ProbeRow> = connection.exec_first(PROBE, ()).await.or_failure()?;

    let (version, comment, read_only, sql_mode, autocommit, database, connection_id, packet) = row
        .ok_or_else(|| {
            Failure::server(
                "server.silent_handshake",
                "the server returned no answer when asked to describe itself",
            )
            .with_hint("confirm the destination points at a server of the MariaDB family")
        })?;

    // Recorded as the connection opens, because the ceiling has to be known
    // where a command is admitted and that happens with no session in hand.
    PacketCeiling::observe(packet);

    Ok(ServerFacts {
        max_allowed_packet: packet,
        ..ServerFacts::from_probe(
            version,
            comment,
            read_only != 0,
            sql_mode,
            autocommit != 0,
            database,
            connection_id,
        )
    })
}

/// The largest command this invocation may send, and where it is kept.
///
/// The number is learned when a connection opens and is needed where a command
/// is admitted, and those two points share nothing: admission takes the
/// caller's text and the policy built from the settings, and that policy is
/// built before any server has been reached. Threading the number through would
/// mean changing the shape every one of the seventeen callers of the admission
/// gate depends on, so it is recorded here instead. This is a one-shot process
/// serving one invocation, so there is exactly one value to keep.
///
/// Two numbers are kept apart on purpose. What the server said is one fact, and
/// what applies to this invocation is a decision: the stored key wins when it
/// was written, and the server's own answer applies when it was not. Keeping
/// only the second would leave nothing able to say where the ceiling came from.
///
/// A run across several destinations observes several servers, and the smallest
/// of them is the one kept: a ceiling taken from the most generous destination
/// would admit a command the others cannot carry, which is the failure this
/// exists to prevent.
pub struct PacketCeiling;

/// The smallest ceiling any destination reached in this invocation reported.
///
/// Zero means no server has been reached yet, which is the state every
/// invocation starts in and the state an offline refusal stays in.
static OBSERVED: AtomicU64 = AtomicU64::new(0);

/// The ceiling that applies to this invocation, once it has been settled.
static IN_FORCE: AtomicU64 = AtomicU64::new(0);

impl PacketCeiling {
    /// Records what one server said its ceiling is.
    pub fn observe(bytes: u64) {
        if bytes == 0 {
            return;
        }
        let mut known = OBSERVED.load(Ordering::Relaxed);
        loop {
            if known != 0 && known <= bytes {
                return;
            }
            match OBSERVED.compare_exchange_weak(known, bytes, Ordering::Relaxed, Ordering::Relaxed)
            {
                Ok(_) => return,
                Err(seen) => known = seen,
            }
        }
    }

    /// What the servers reached so far said, when one has been reached.
    #[must_use]
    pub fn observed() -> Option<usize> {
        usize::try_from(OBSERVED.load(Ordering::Relaxed))
            .ok()
            .filter(|bytes| *bytes > 0)
    }

    /// Settles the ceiling this invocation admits commands against.
    ///
    /// Absence is meaningful and is recorded as such: an invocation that never
    /// reached a server and stored no key has no ceiling to measure against,
    /// and inventing one would refuse a command no server ever objected to.
    pub fn declare(bytes: Option<usize>) {
        let settled = bytes.map_or(0, |bytes| u64::try_from(bytes).unwrap_or(u64::MAX));
        IN_FORCE.store(settled, Ordering::Relaxed);
    }

    /// The ceiling in force, when one has been settled.
    #[must_use]
    pub fn in_force() -> Option<usize> {
        usize::try_from(IN_FORCE.load(Ordering::Relaxed))
            .ok()
            .filter(|bytes| *bytes > 0)
    }
}

/// Reads the leading numeric parts of a version text.
///
/// A version text carries a distribution suffix as often as not, so the parts
/// are read up to the first thing that is not a number.
fn parse_version(version: &str) -> (u16, u16, u16) {
    let mut parts = version
        .split(|character: char| !character.is_ascii_digit())
        .filter(|part| !part.is_empty())
        .map(|part| part.parse::<u16>().unwrap_or_default());
    (
        parts.next().unwrap_or_default(),
        parts.next().unwrap_or_default(),
        parts.next().unwrap_or_default(),
    )
}

/// Whether these version parts reach the oldest release supported.
const fn meets_minimum(parts: (u16, u16, u16)) -> bool {
    at_least(parts, MINIMUM_SERVER_VERSION.0, MINIMUM_SERVER_VERSION.1)
}

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

    fn facts(version: &str, comment: &str) -> ServerFacts {
        ServerFacts::from_probe(
            version.to_owned(),
            comment.to_owned(),
            false,
            "STRICT_TRANS_TABLES".to_owned(),
            false,
            Some("sales".to_owned()),
            42,
        )
    }

    /// A version text is read past its distribution suffix.
    #[test]
    fn a_version_is_read_past_its_suffix() {
        assert_eq!(
            parse_version("11.4.2-MariaDB-1:11.4.2+maria~ubu2404"),
            (11, 4, 2)
        );
        assert_eq!(parse_version("10.11.8-MariaDB"), (10, 11, 8));
        assert_eq!(parse_version("nonsense"), (0, 0, 0));
    }

    /// The oldest supported release passes and anything older does not.
    #[test]
    fn the_minimum_version_is_the_published_one() {
        assert!(meets_minimum((10, 11, 0)));
        assert!(meets_minimum((11, 0, 0)));
        assert!(!meets_minimum((10, 6, 18)));
        assert!(!meets_minimum((8, 0, 36)));
    }

    /// An older server is warned about rather than refused, so the part of the
    /// surface that works on it stays usable.
    #[test]
    fn an_older_server_is_warned_about_and_not_refused() {
        let old = facts("10.6.18-MariaDB", "MariaDB Server");
        assert!(!old.meets_minimum_version);
        let warning = old.version_warning().expect("a warning is due");
        assert!(warning.contains("10.6.18"));
        assert!(warning.contains("10.11"));

        let current = facts("11.4.2-MariaDB", "MariaDB Server");
        assert!(current.meets_minimum_version);
        assert!(current.version_warning().is_none());
    }

    /// The distribution is recognised from either the version or its remark.
    #[test]
    fn the_distribution_is_recognised_from_either_field() {
        assert!(facts("11.4.2-MariaDB", "").is_mariadb);
        assert!(facts("11.4.2", "mariadb.org binary distribution").is_mariadb);
        assert!(!facts("8.0.36", "MySQL Community Server").is_mariadb);
    }

    /// Optional abilities follow the version and the distribution, so they are
    /// known without one round trip per ability.
    #[test]
    fn optional_abilities_follow_the_server() {
        let current = facts("11.4.2-MariaDB", "MariaDB Server").capabilities;
        assert!(current.system_versioning);
        assert!(current.sequences);
        assert!(current.checked_documents);

        let other_family = facts("8.0.36", "MySQL Community Server").capabilities;
        assert!(!other_family.system_versioning);
        assert!(!other_family.sequences);
    }

    /// The four things the invocation needs all come out of one probe.
    #[test]
    fn one_probe_answers_all_four_questions() {
        let answered = facts("11.4.2-MariaDB", "MariaDB Server").as_value();
        assert!(answered["version"].is_string());
        assert!(answered["read_only"].is_boolean());
        assert!(answered["sql_mode"].is_string());
        assert!(answered["capabilities"].is_object());
    }

    /// FR-084. The ceiling travels with the rest of the handshake, so the
    /// number a command is measured against costs no round trip of its own.
    #[test]
    fn the_packet_ceiling_is_part_of_what_the_handshake_answers() {
        let answered = ServerFacts {
            max_allowed_packet: 4 * 1024 * 1024,
            ..facts("11.4.2-MariaDB", "MariaDB Server")
        };
        assert_eq!(answered.as_value()["max_allowed_packet"], 4 * 1024 * 1024);
        assert_eq!(
            facts("11.4.2-MariaDB", "MariaDB Server").max_allowed_packet,
            CEILING_NOT_ANSWERED,
            "a record built without a probe states no ceiling of its own"
        );
    }

    /// FR-084. Across destinations the smallest ceiling is the one kept: taking
    /// the most generous would admit a command the other destinations cannot
    /// carry, which is exactly the send this refusal exists to stop.
    #[test]
    fn the_smallest_ceiling_observed_is_the_one_kept() {
        PacketCeiling::observe(8 * 1024 * 1024);
        assert_eq!(PacketCeiling::observed(), Some(8 * 1024 * 1024));
        PacketCeiling::observe(1024 * 1024);
        assert_eq!(PacketCeiling::observed(), Some(1024 * 1024));
        PacketCeiling::observe(16 * 1024 * 1024);
        assert_eq!(
            PacketCeiling::observed(),
            Some(1024 * 1024),
            "a more generous destination must never raise the ceiling"
        );
    }

    /// A server refusing changes of its own accord is reported as such.
    #[test]
    fn a_server_refusing_changes_is_reported() {
        let mut facts = facts("11.4.2-MariaDB", "MariaDB Server");
        facts.read_only = true;
        assert_eq!(facts.as_value()["read_only"], true);
    }
}