mariadb-cli 0.1.1

One-shot agent-native command line client for MariaDB servers
Documentation
//! Moving data in and out of the server.
//!
//! Two directions, and each has one rule that shapes everything else.
//!
//! Going out, the copy must be restorable, which means the tables in it must
//! agree with one another. That agreement comes from a consistent read inside
//! a transaction, so no reader and no writer is ever blocked while the copy
//! runs. When the engine cannot give one, the copy still runs and says so.
//!
//! Coming in, the file is opened by this process and never by the server. A
//! server that reads files on behalf of a client is a way to read files it was
//! never meant to read, so that ability stays switched off and this layer never
//! asks for it.
//!
//! Both directions write through [`AtomicWriter`], which never leaves a partial
//! file where a whole one belongs.

pub mod export;
pub mod import;
pub mod import_rows;
pub mod literal;

pub use export::{ExportReport, ExportRequest};
pub use import::{ImportReport, ImportRequest};
pub use import_rows::{Batch, Reading, Rejection};

use crate::error::{Failure, Result};
use std::io::Write as _;
use std::path::{Path, PathBuf};

/// What a finished file weighs and where it ended up.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Written {
    /// Where the file was placed.
    pub path: PathBuf,
    /// How many bytes it holds.
    pub bytes: usize,
}

/// A file that appears at its destination whole, or not at all.
///
/// Work is done on a temporary file beside the destination and moved over it in
/// one step at the end. Beside, rather than in a scratch directory, because a
/// move across two filesystems is a copy, and a copy can be interrupted halfway
/// through, which is the very thing this exists to prevent.
///
/// Reaching the volume ceiling is a failure and the temporary file is dropped
/// with it, so the destination is left exactly as it was.
#[derive(Debug)]
pub struct AtomicWriter {
    file: tempfile::NamedTempFile,
    destination: PathBuf,
    written: usize,
    ceiling: Option<usize>,
}

impl AtomicWriter {
    /// Opens a writer for the given destination.
    ///
    /// # Errors
    ///
    /// Returns a configuration failure when the destination has no directory
    /// to write beside, or when a temporary file cannot be created there.
    pub fn create(destination: &Path, ceiling: Option<usize>) -> Result<Self> {
        let directory = destination
            .parent()
            .filter(|parent| !parent.as_os_str().is_empty());
        let directory = directory.unwrap_or_else(|| Path::new("."));

        std::fs::create_dir_all(directory).map_err(|error| {
            Failure::config(
                "datamove.destination_unwritable",
                format!("`{}` cannot be written to", directory.display()),
            )
            .with_detail("detail", directory.display().to_string())
            .with_cause(error.to_string())
        })?;

        let file = tempfile::NamedTempFile::new_in(directory).map_err(|error| {
            Failure::config(
                "datamove.destination_unwritable",
                format!(
                    "no temporary file could be created in `{}`",
                    directory.display()
                ),
            )
            .with_detail("detail", directory.display().to_string())
            .with_hint("point the destination at a directory this process may write to")
            .with_cause(error.to_string())
        })?;

        Ok(Self {
            file,
            destination: destination.to_path_buf(),
            written: 0,
            ceiling,
        })
    }

    /// How many bytes have been written so far.
    #[must_use]
    pub const fn written(&self) -> usize {
        self.written
    }

    /// Appends one piece of the file.
    ///
    /// # Errors
    ///
    /// Returns a limit failure when the piece would take the file past the
    /// volume ceiling, and an input/output failure when the write itself fails.
    /// In both cases the destination still holds whatever it held before.
    pub fn write(&mut self, piece: &str) -> Result<()> {
        let bytes = piece.as_bytes();
        if let Some(ceiling) = self.ceiling {
            if self.written.saturating_add(bytes.len()) > ceiling {
                return Err(Failure::limit(
                    "datamove.volume_ceiling",
                    format!("the copy went past its volume ceiling of {ceiling} bytes"),
                )
                .with_detail(
                    "detail",
                    format!("{} > {ceiling}", self.written.saturating_add(bytes.len())),
                )
                .with_hint("raise the ceiling, or narrow the copy so it fits inside it"));
            }
        }

        // The failure is built outside the call so the destination may be read
        // for the detail without overlapping the write's borrow of the file.
        if let Err(error) = self.file.write_all(bytes) {
            return Err(Failure::config(
                "datamove.write_failed",
                "the copy could not be written to its temporary file",
            )
            .with_detail("detail", self.destination.display().to_string())
            .with_cause(error.to_string()));
        }
        self.written += bytes.len();
        Ok(())
    }

    /// Puts the finished file at its destination in one step.
    ///
    /// # Errors
    ///
    /// Returns a configuration failure when the file cannot be flushed to the
    /// disk or moved over the destination. The destination is untouched in
    /// either case.
    pub fn commit(mut self) -> Result<Written> {
        let destination = self.destination.display().to_string();

        self.file.flush().map_err(|error| {
            Failure::config("datamove.write_failed", "the copy could not be flushed")
                .with_detail("detail", destination.clone())
                .with_cause(error.to_string())
        })?;
        self.file.as_file().sync_all().map_err(|error| {
            Failure::config(
                "datamove.write_failed",
                "the copy could not be written to the disk",
            )
            .with_detail("detail", destination.clone())
            .with_cause(error.to_string())
        })?;

        self.file.persist(&self.destination).map_err(|error| {
            Failure::config(
                "datamove.destination_unwritable",
                format!("the copy could not be placed at `{destination}`"),
            )
            .with_detail("detail", destination.clone())
            .with_cause(error.error.to_string())
        })?;

        Ok(Written {
            path: self.destination,
            bytes: self.written,
        })
    }
}

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

    fn scratch() -> tempfile::TempDir {
        tempfile::tempdir().expect("scratch directory")
    }

    #[test]
    fn a_finished_file_appears_whole_at_its_destination() {
        let directory = scratch();
        let destination = directory.path().join("copy.sql");

        let mut writer = AtomicWriter::create(&destination, None).expect("opens");
        writer.write("CREATE TABLE `a`;\n").expect("writes");
        writer
            .write("INSERT INTO `a` VALUES (1);\n")
            .expect("writes");
        let written = writer.commit().expect("commits");

        assert_eq!(written.path, destination);
        assert_eq!(written.bytes, 46);
        let content = std::fs::read_to_string(&destination).expect("readable");
        assert!(content.starts_with("CREATE TABLE"));
        assert!(content.ends_with("VALUES (1);\n"));
    }

    #[test]
    fn nothing_appears_at_the_destination_until_the_file_is_whole() {
        let directory = scratch();
        let destination = directory.path().join("copy.sql");

        let mut writer = AtomicWriter::create(&destination, None).expect("opens");
        writer.write("half of a file").expect("writes");
        assert!(!destination.exists(), "the destination must stay untouched");
        drop(writer);
        assert!(!destination.exists(), "an abandoned copy leaves nothing");
    }

    #[test]
    fn reaching_the_volume_ceiling_leaves_no_partial_file_behind() {
        let directory = scratch();
        let destination = directory.path().join("copy.sql");

        let mut writer = AtomicWriter::create(&destination, Some(16)).expect("opens");
        writer.write("0123456789").expect("fits");
        let failure = writer
            .write("and this does not fit")
            .expect_err("must refuse");

        assert_eq!(failure.code(), "datamove.volume_ceiling");
        assert_eq!(failure.exit_number().code(), 10);
        drop(writer);
        assert!(
            !destination.exists(),
            "a partial copy must never take the place of a whole one"
        );
    }

    #[test]
    fn a_copy_that_fits_exactly_inside_the_ceiling_is_written() {
        let directory = scratch();
        let destination = directory.path().join("copy.sql");

        let mut writer = AtomicWriter::create(&destination, Some(10)).expect("opens");
        writer.write("0123456789").expect("exactly fits");
        assert_eq!(writer.commit().expect("commits").bytes, 10);
    }

    #[test]
    fn an_existing_file_is_only_replaced_once_the_new_one_is_whole() {
        let directory = scratch();
        let destination = directory.path().join("copy.sql");
        std::fs::write(&destination, b"the previous copy").expect("writes");

        let mut writer = AtomicWriter::create(&destination, Some(4)).expect("opens");
        writer.write("too long for this").expect_err("must refuse");
        drop(writer);

        assert_eq!(
            std::fs::read_to_string(&destination).expect("readable"),
            "the previous copy",
            "the previous copy survives a failed replacement"
        );
    }

    #[test]
    fn a_destination_with_no_directory_of_its_own_writes_beside_itself() {
        let directory = scratch();
        let destination = directory.path().join("nested").join("copy.sql");
        let mut writer = AtomicWriter::create(&destination, None).expect("opens");
        writer.write("x").expect("writes");
        assert!(writer.commit().is_ok());
    }
}