migratex 0.2.2

Agnostic migration toolkit library.
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

// This file is part of "Migratex - A Migrations Toolkit".
//
// This source code is licensed under the MIT license, please view the LICENSE
// file distributed with this source code. For the full
// information and documentation: https://github.com/nicolab/migratex
// -----------------------------------------------------------------------------

use okerr::Result;

use crate::BoxMigration;
use crate::Metadata;

/// Migratex manages the migrations, this is the main struct.
/// Think of it as a "migration manager", "migrator", "runner").
/// It can be used to migrate database / data / files / binaries, etc from one version to another.
pub struct Migratex<'m, 'c, MigContext, M: Metadata> {
    /// The migration context, passed to each migration.
    ctx: &'c mut MigContext,
    /// The metadata, passed to each migration.
    meta: &'m mut M,
    /// The migrations list.
    migrations: Vec<BoxMigration<MigContext>>,
}

impl<'m, 'c, MigContext, M: Metadata> Migratex<'m, 'c, MigContext, M> {
    /// Create a new Migratex.
    pub fn new(
        ctx: &'c mut MigContext,
        meta: &'m mut M,
        migrations: Vec<BoxMigration<MigContext>>,
    ) -> Self {
        Self {
            ctx,
            meta,
            migrations,
        }
    }

    /// Get the current metadata.
    pub fn metadata(&self) -> &M {
        self.meta
    }

    /// Get the migration context.
    pub fn context(&self) -> &MigContext {
        self.ctx
    }

    /// Get the most recent migration version.
    pub fn latest_version(&self) -> i32 {
        self.migrations.last().map(|m| m.version()).unwrap_or(0)
    }

    /// Migrate from current metadata.version up to the latest migration version
    pub async fn migrate_to_latest(&mut self) -> Result<()> {
        let target = self.latest_version();
        self.migrate_to(target).await
    }

    /// Rollback everything (migrate to version 0, before the first migration).
    pub async fn migrate_to_zero(&mut self) -> Result<()> {
        self.migrate_to(0).await
    }

    /// Migrate to the next version (up)
    pub async fn migrate_next(&mut self) -> Result<()> {
        let current = self.meta.version();

        if current >= self.latest_version() {
            return Ok(());
        }

        self.migrate_to(current + 1).await
    }

    /// Migrate to the previous version (down)
    pub async fn migrate_prev(&mut self) -> Result<()> {
        let current = self.meta.version();

        if current <= 0 {
            return Ok(());
        }

        self.migrate_to(current - 1).await
    }

    /// Migrate to a specific target version (up or down)
    pub async fn migrate_to(&mut self, target: i32) -> Result<()> {
        let current = self.meta.version();

        if target == current {
            return Ok(());
        }

        self.meta.mark_migrating();

        let result = if target > current {
            // UP:  current+1 ..= target
            self.migrate_up(current, target).await
        } else {
            // DOWN: current ..> target
            self.migrate_down(current, target).await
        };

        match result {
            Ok(()) => {
                self.meta.mark_clean();
                Ok(())
            }
            Err(e) => {
                self.meta.mark_failed();
                Err(e)
            }
        }
    }

    /// Migrate up to a specific target version.
    async fn migrate_up(&mut self, current: i32, target: i32) -> Result<()> {
        for m in &self.migrations {
            let v = m.version();
            if v > current && v <= target {
                m.up(self.ctx).await?;
                self.meta.set_version(v);
            }
        }
        Ok(())
    }

    /// Migrate down to a specific target version.
    async fn migrate_down(&mut self, current: i32, target: i32) -> Result<()> {
        let mut sorted: Vec<_> = self.migrations.iter().collect();
        sorted.sort_by_key(|m| m.version());
        sorted.reverse(); // highest → lowest

        for m in sorted {
            let v = m.version();
            if v <= current && v > target {
                m.down(self.ctx).await?;
                // convention: after down of v, highest applied = v - 1
                self.meta.set_version(v - 1);
            }
        }
        Ok(())
    }
}