migratrom 0.2.0

Declarative, self-verifying database migrations (core engine).
Documentation
//! Error taxonomy for planning, verifying, and applying migrations.
//!
//! Variants distinguish graph/configuration failures, self-verification
//! failures, checksum drift, unsupported dialect features, and adapter errors.

use thiserror::Error;

/// Everything that can go wrong while planning or applying migrations.
#[derive(Debug, Error)]
pub enum MigratromError {
    /// Invalid configuration (missing handle, malformed checksum, bad `rawSql`, …).
    #[error("{0}")]
    Config(String),

    /// Two migrations share the same id.
    #[error("duplicate migration id: {0}")]
    DuplicateMigrationId(i64),

    /// An empty history has no root migration (`parent_id == None`).
    #[error("no root migration (parent_id = None) in an empty history")]
    MissingRoot,

    /// More than one root migration was found (or a new root on a non-empty history).
    #[error("multiple root migrations: {0:?}")]
    MultipleRoots(Vec<i64>),

    /// A migration references a parent that is neither in the batch nor in history.
    #[error("migration {id} references missing parent {parent}")]
    MissingParent {
        /// Migration whose parent cannot be resolved.
        id: i64,
        /// Missing parent migration id.
        parent: i64,
    },

    /// The migration graph contains a cycle (printed as the offending path).
    #[error("cycle detected in migration graph: {0:?}")]
    CycleDetected(Vec<i64>),

    /// A precheck returned `false`, so the operation cannot run safely.
    #[error("precheck failed for operation \"{operation}\": {description}")]
    PrecheckFailed {
        /// Stable id of the operation whose check failed.
        operation: String,
        /// Description of the failed check.
        description: String,
    },

    /// A postcheck returned `false` after execution, so the change did not take effect.
    #[error("postcheck failed for operation \"{operation}\": {description}")]
    PostcheckFailed {
        /// Stable id of the operation whose check failed.
        operation: String,
        /// Description of the failed check.
        description: String,
    },

    /// An operation declared no postcheck; self-verification is impossible.
    #[error("operation \"{0}\" has no postcheck")]
    EmptyPostcheck(String),

    /// A migration failed; wraps the underlying cause.
    #[error("migration {id} failed: {cause}")]
    MigrationFailed {
        /// Id of the migration that failed.
        id: i64,
        #[source]
        /// Underlying failure that aborted the migration.
        cause: Box<MigratromError>,
    },

    /// An already-applied migration's body was edited (stored checksum no longer matches).
    #[error(
        "migration {id} checksum mismatch (applied body was edited): expected {expected}, got {actual}"
    )]
    ChecksumMismatch {
        /// Id of the edited migration.
        id: i64,
        /// Checksum read from migration history.
        expected: String,
        /// Checksum computed from the current migration body.
        actual: String,
    },

    /// A check query did not return exactly one row / one column / boolean.
    #[error("{message}{}", .row_preview.as_deref().map(|r| format!(" — row: {r}")).unwrap_or_default())]
    CheckShape {
        /// Explanation of the unexpected query result shape.
        message: String,
        /// Optional textual representation of the received row.
        row_preview: Option<String>,
    },

    /// The chosen dialect does not support the requested feature.
    #[error("{feature} is not supported by the {dialect} dialect")]
    Unsupported {
        /// Requested database feature.
        feature: String,
        /// Dialect that does not support the feature.
        dialect: String,
    },

    /// A driver-level failure surfaced by an adapter.
    #[error("database error: {0}")]
    Db(String),
}

/// Convenient result alias used throughout the crate.
pub type Result<T> = std::result::Result<T, MigratromError>;