lenso-postgres-kit 0.1.0

Module-owned PostgreSQL schema lifecycle kit for Lenso applications
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

use thiserror::Error;

use crate::PlanError;

/// A `PostgreSQL` schema lifecycle operation failed without applying a fallback.
#[derive(Debug, Error)]
pub enum PostgresKitError {
    /// The authored schema plan is invalid.
    #[error(transparent)]
    InvalidPlan(#[from] PlanError),
    /// Connection setup or a database operation failed.
    #[error("PostgreSQL operation `{operation}` failed")]
    Database {
        operation: &'static str,
        #[source]
        source: sqlx::Error,
    },
    /// The schema exists, but was not created by this lifecycle protocol.
    #[error("schema `{schema}` exists without the Lenso migration ledger")]
    UnmanagedSchema { schema: String },
    /// The configured database role does not own the Module schema.
    #[error("schema `{schema}` is owned by `{owner}`, not current role `{current_role}`")]
    OwnershipMismatch {
        schema: String,
        owner: String,
        current_role: String,
    },
    /// Runtime preparation requires an explicit setup operation first.
    #[error("schema `{schema}` has not been set up")]
    SetupRequired { schema: String },
    /// Runtime preparation never applies pending migrations.
    #[error(
        "schema `{schema}` is at version {current}; explicit upgrade to {expected} is required"
    )]
    UpgradeRequired {
        schema: String,
        current: u64,
        expected: u64,
    },
    /// Applied migration history no longer matches the immutable authored plan.
    #[error("schema `{schema}` migration history diverged at version {version}")]
    HistoryDiverged { schema: String, version: u64 },
    /// The database is newer than the linked Module implementation.
    #[error("schema `{schema}` is at version {actual}, newer than supported version {expected}")]
    SchemaAhead {
        schema: String,
        actual: u64,
        expected: u64,
    },
}

impl PostgresKitError {
    pub(crate) const fn database(operation: &'static str, source: sqlx::Error) -> Self {
        Self::Database { operation, source }
    }
}

/// Result of explicitly setting up an owned schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum SetupOutcome {
    /// A new schema was created at the current authored version.
    Created { version: u64, applied: usize },
    /// The existing managed schema already matched the authored plan.
    AlreadyCurrent { version: u64 },
}

/// Result of explicitly upgrading an owned schema.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum UpgradeOutcome {
    /// Pending migrations were applied atomically.
    Applied { from: u64, to: u64, applied: usize },
    /// The existing managed schema already matched the authored plan.
    AlreadyCurrent { version: u64 },
}