forge_runtime/migrations/
builtin.rs

1//! Built-in FORGE schema migrations.
2//!
3//! These migrations create all internal tables required by the FORGE runtime.
4//! They use a version-based naming scheme (`__forge_vXXX`) to avoid conflicts
5//! with user migrations.
6//!
7//! # Migration Naming
8//!
9//! - System migrations: `__forge_v001`, `__forge_v002`, etc.
10//! - User migrations: `0001_xxx`, `0002_xxx`, etc.
11//!
12//! System migrations are always applied before user migrations, regardless of
13//! naming. This allows new forge features to be added without conflicting with
14//! existing user migration numbering.
15
16use super::runner::Migration;
17
18/// System migration prefix. All forge internal migrations use this prefix.
19pub const SYSTEM_MIGRATION_PREFIX: &str = "__forge_v";
20
21/// Legacy migration name from older forge versions.
22/// If found, it will be considered equivalent to v001.
23pub const LEGACY_MIGRATION_NAME: &str = "0000_forge_internal";
24
25/// System migration v001: Initial FORGE schema.
26/// Creates all core tables for jobs, workflows, crons, observability, etc.
27const V001_INITIAL: &str = include_str!("../../migrations/system/v001_initial.sql");
28
29/// A system migration with a version number.
30#[derive(Debug, Clone)]
31pub struct SystemMigration {
32    /// Version number (1, 2, 3, ...)
33    pub version: u32,
34    /// The SQL to execute
35    pub sql: &'static str,
36    /// Description of what this migration does
37    pub description: &'static str,
38}
39
40impl SystemMigration {
41    /// Get the migration name used in the database (e.g., `__forge_v001`).
42    pub fn name(&self) -> String {
43        format!("{}{:03}", SYSTEM_MIGRATION_PREFIX, self.version)
44    }
45
46    /// Convert to a Migration struct.
47    pub fn to_migration(&self) -> Migration {
48        Migration::new(self.name(), self.sql)
49    }
50}
51
52/// Get all built-in FORGE system migrations in version order.
53///
54/// These are applied in order before any user migrations.
55pub fn get_system_migrations() -> Vec<SystemMigration> {
56    vec![SystemMigration {
57        version: 1,
58        sql: V001_INITIAL,
59        description: "Initial FORGE schema with jobs, workflows, crons, and observability",
60    }]
61}
62
63/// Get system migrations as Migration structs.
64pub fn get_builtin_migrations() -> Vec<Migration> {
65    get_system_migrations()
66        .into_iter()
67        .map(|m| m.to_migration())
68        .collect()
69}
70
71/// Check if a migration name is a system migration.
72pub fn is_system_migration(name: &str) -> bool {
73    name.starts_with(SYSTEM_MIGRATION_PREFIX) || name == LEGACY_MIGRATION_NAME
74}
75
76/// Extract version number from a system migration name.
77/// Returns None if not a valid system migration name.
78pub fn extract_version(name: &str) -> Option<u32> {
79    if name == LEGACY_MIGRATION_NAME {
80        return Some(1);
81    }
82    if let Some(suffix) = name.strip_prefix(SYSTEM_MIGRATION_PREFIX) {
83        return suffix.parse().ok();
84    }
85    None
86}
87
88#[cfg(test)]
89mod tests {
90    use super::*;
91
92    #[test]
93    fn test_get_system_migrations() {
94        let migrations = get_system_migrations();
95        assert!(!migrations.is_empty());
96        assert_eq!(migrations[0].version, 1);
97        assert_eq!(migrations[0].name(), "__forge_v001");
98    }
99
100    #[test]
101    fn test_migration_sql_not_empty() {
102        let migrations = get_system_migrations();
103        for m in migrations {
104            assert!(!m.sql.is_empty(), "Migration v{} has empty SQL", m.version);
105        }
106    }
107
108    #[test]
109    fn test_migration_sql_contains_tables() {
110        let migrations = get_system_migrations();
111        let sql = migrations[0].sql;
112
113        // Verify all core tables are defined
114        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_nodes"));
115        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_leaders"));
116        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_jobs"));
117        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_cron_runs"));
118        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_workflow_runs"));
119        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_workflow_steps"));
120        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_metrics"));
121        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_logs"));
122        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_traces"));
123        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_sessions"));
124        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_subscriptions"));
125        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_alert_rules"));
126        assert!(sql.contains("CREATE TABLE IF NOT EXISTS forge_alerts"));
127    }
128
129    #[test]
130    fn test_is_system_migration() {
131        assert!(is_system_migration("__forge_v001"));
132        assert!(is_system_migration("__forge_v002"));
133        assert!(is_system_migration("__forge_v100"));
134        assert!(is_system_migration("0000_forge_internal")); // Legacy
135        assert!(!is_system_migration("0001_create_users"));
136        assert!(!is_system_migration("user_migration"));
137    }
138
139    #[test]
140    fn test_extract_version() {
141        assert_eq!(extract_version("__forge_v001"), Some(1));
142        assert_eq!(extract_version("__forge_v002"), Some(2));
143        assert_eq!(extract_version("__forge_v100"), Some(100));
144        assert_eq!(extract_version("0000_forge_internal"), Some(1)); // Legacy
145        assert_eq!(extract_version("0001_create_users"), None);
146        assert_eq!(extract_version("invalid"), None);
147    }
148
149    #[test]
150    fn test_system_migration_to_migration() {
151        let sys = SystemMigration {
152            version: 1,
153            sql: "SELECT 1;",
154            description: "Test",
155        };
156        let m = sys.to_migration();
157        assert_eq!(m.name, "__forge_v001");
158        assert_eq!(m.up_sql, "SELECT 1;");
159    }
160}
forge_runtime/migrations/builtin.rs

forge_runtime/migrations/
builtin.rs
