kasl/commands/
migrations.rs

1//! Database migration management command (debug builds only).
2//!
3//! Provides database schema management utilities for development and debugging purposes.
4//!
5//! ## Features
6//!
7//! - **Version Tracking**: Maintains current database schema version
8//! - **Migration History**: Records all applied migrations with timestamps
9//! - **Debug Only**: Available only in debug builds for production safety
10//! - **Status Inspection**: View current migration status and history
11//! - **Integrity Checking**: Validates database schema consistency
12//!
13//! ## Usage
14//!
15//! ```bash
16//! # Check migration status (debug builds only)
17//! kasl migrations status
18//!
19//! # View migration history (debug builds only)
20//! kasl migrations history
21//! ```
22
23#[cfg(debug_assertions)]
24use crate::{
25    db::{
26        db::Db,
27        migrations::{MigrationManager, get_db_version, needs_migration},
28    },
29    libs::messages::Message,
30    msg_info, msg_print,
31};
32#[cfg(debug_assertions)]
33use anyhow::Result;
34#[cfg(debug_assertions)]
35use clap::{Args, Subcommand};
36
37/// Command-line arguments for database migration management.
38///
39/// This command provides essential tools for database schema inspection
40/// and management during development. All operations are read-only or
41/// carefully controlled to prevent accidental data loss.
42#[cfg(debug_assertions)]
43#[derive(Debug, Args)]
44pub struct MigrationsArgs {
45    #[command(subcommand)]
46    command: MigrationsCommand,
47}
48
49/// Available migration management operations.
50///
51/// Each subcommand provides specific functionality for database schema
52/// inspection and management. Operations are designed to be safe and
53/// informative for development workflows.
54#[cfg(debug_assertions)]
55#[derive(Debug, Subcommand)]
56enum MigrationsCommand {
57    /// Display current database schema version and migration status
58    ///
59    /// Shows the current database version and indicates whether any
60    /// pending migrations need to be applied. This is useful for
61    /// understanding the current state of the database schema during
62    /// development and troubleshooting.
63    Status,
64
65    /// Show complete migration history with timestamps
66    ///
67    /// Displays a chronological list of all migrations that have been
68    /// applied to the database, including version numbers, migration
69    /// names, and application timestamps. Useful for understanding
70    /// how the database schema has evolved over time.
71    History,
72}
73
74/// Executes database migration management operations.
75///
76/// Provides essential database schema inspection capabilities for development
77/// and debugging. All operations are designed to be safe and non-destructive.
78///
79/// # Arguments
80///
81/// * `args` - Parsed command-line arguments specifying the inspection operation
82///
83/// # Returns
84///
85/// Returns `Ok(())` on successful operation completion, or an error if
86/// database access fails or the requested operation encounters issues.
87///
88/// # Examples
89///
90/// ```bash
91/// # Check current database version and migration status
92/// kasl migrations status
93///
94/// # View complete migration history
95/// kasl migrations history
96/// ```
97///
98/// # Error Scenarios
99///
100/// - Database connection failures
101/// - Corrupted migration tracking tables
102/// - Inconsistent schema state
103/// - Permission issues accessing database files
104#[cfg(debug_assertions)]
105pub fn cmd(args: MigrationsArgs) -> Result<()> {
106    // Create direct database connection without running migrations
107    // This ensures we can inspect the current state without modifying it
108    let conn = Db::new_without_migrations()?;
109
110    match args.command {
111        MigrationsCommand::Status => {
112            // Get current database version from migration tracking table
113            let version = get_db_version(&conn)?;
114
115            // Check if any migrations are pending application
116            let needs_update = needs_migration(&conn)?;
117
118            // Display current version information
119            msg_print!(Message::DatabaseVersion(version));
120
121            // Provide clear status about migration needs
122            if needs_update {
123                msg_info!(Message::DatabaseNeedsUpdate);
124            } else {
125                msg_info!(Message::DatabaseUpToDate);
126            }
127        }
128        MigrationsCommand::History => {
129            // Create migration manager for history access
130            let manager = MigrationManager::new();
131
132            // Retrieve complete migration history from database
133            let history = manager.get_migration_history(&conn)?;
134
135            // Display formatted migration history
136            msg_print!(Message::MigrationHistory, true);
137            for (version, name, applied_at) in history {
138                println!("  v{}: {} (applied: {})", version, name, applied_at);
139            }
140        }
141    }
142
143    Ok(())
144}
kasl/commands/migrations.rs

kasl/commands/
migrations.rs
