jetbase 0.7.0__py3-none-any.whl → 0.12.1__py3-none-any.whl

jetbase/cli/main.py

@@ -1,8 +1,17 @@
 import typer
 
-from jetbase.core.initialize import initialize_cmd
-from jetbase.core.rollback import rollback_cmd
-from jetbase.core.upgrade import upgrade_cmd
+from jetbase.commands.current import current_cmd
+from jetbase.commands.fix_checksums import fix_checksums_cmd
+from jetbase.commands.fix_files import fix_files_cmd
+from jetbase.commands.history import history_cmd
+from jetbase.commands.init import initialize_cmd
+from jetbase.commands.lock_status import lock_status_cmd
+from jetbase.commands.new import generate_new_migration_file_cmd
+from jetbase.commands.rollback import rollback_cmd
+from jetbase.commands.status import status_cmd
+from jetbase.commands.unlock import unlock_cmd
+from jetbase.commands.upgrade import upgrade_cmd
+from jetbase.commands.validators import validate_jetbase_directory
 
 app = typer.Typer(help="Jetbase CLI")
 
@@ -24,12 +33,31 @@ def upgrade(
     dry_run: bool = typer.Option(
         False, "--dry-run", "-d", help="Simulate the upgrade without making changes"
     ),
+    skip_validation: bool = typer.Option(
+        False,
+        "--skip-validation",
+        help="Skip both checksum and file version validation when running migrations",
+    ),
+    skip_checksum_validation: bool = typer.Option(
+        False,
+        "--skip-checksum-validation",
+        help="Skip checksum validation when running migrations",
+    ),
+    skip_file_validation: bool = typer.Option(
+        False,
+        "--skip-file-validation",
+        help="Skip file version validation when running migrations",
+    ),
 ):
     """Execute pending migrations"""
+    validate_jetbase_directory()
     upgrade_cmd(
         count=count,
         to_version=to_version.replace("_", ".") if to_version else None,
         dry_run=dry_run,
+        skip_validation=skip_validation,
+        skip_checksum_validation=skip_checksum_validation,
+        skip_file_validation=skip_file_validation,
     )
 
 
@@ -42,10 +70,11 @@ def rollback(
         None, "--to-version", "-t", help="Rollback to a specific version"
     ),
     dry_run: bool = typer.Option(
-        False, "--dry-run", "-d", help="Simulate the upgrade without making changes"
+        False, "--dry-run", "-d", help="Simulate the rollback without making changes"
     ),
 ):
     """Rollback migration(s)"""
+    validate_jetbase_directory()
     rollback_cmd(
         count=count,
         to_version=to_version.replace("_", ".") if to_version else None,
@@ -53,7 +82,120 @@ def rollback(
     )
 
 
+@app.command()
+def history():
+    """Show migration history"""
+    validate_jetbase_directory()
+    history_cmd()
+
+
+@app.command()
+def current():
+    """Show the latest version that has been migrated"""
+    validate_jetbase_directory()
+    current_cmd()
+
+
+@app.command()
+def unlock():
+    """
+    Unlock the migration lock to allow migrations to run again.
+
+    WARNING: Only use this if you're certain no migration is currently running.
+    Unlocking then running a migration during an active migration can cause database corruption.
+    """
+    validate_jetbase_directory()
+    unlock_cmd()
+
+
+@app.command()
+def lock_status() -> None:
+    """Checks if the database is currently locked for migrations or not."""
+    validate_jetbase_directory()
+    lock_status_cmd()
+
+
+@app.command()
+def fix_checksums() -> None:
+    """Updates all stored checksums to their current values."""
+    validate_jetbase_directory()
+    fix_checksums_cmd()
+
+
+@app.command()
+def fix() -> None:
+    """Repair migration files and versions."""
+    validate_jetbase_directory()
+    fix_files_cmd(audit_only=False)
+    fix_checksums_cmd(audit_only=False)
+    print("Fix completed successfully.")
+
+
+@app.command()
+def validate_checksums(
+    fix: bool = typer.Option(
+        False,
+        "--fix",
+        "-f",
+        help="Fix any detected checksum mismatches by updating the stored checksum to match any changes in its corresponding migration file",
+    ),
+) -> None:
+    """Audit migration checksums without making changes. Use --fix to update stored checksums to match current migration files."""
+    validate_jetbase_directory()
+    if fix:
+        fix_checksums_cmd(audit_only=False)
+    else:
+        fix_checksums_cmd(audit_only=True)
+
+
+@app.command()
+def validate_files(
+    fix: bool = typer.Option(
+        False,
+        "--fix",
+        "-f",
+        help="Fix any detected migration file issues",
+    ),
+) -> None:
+    """Check if any migration files are missing. Use --fix to clean up records of migrations whose files no longer exist."""
+    validate_jetbase_directory()
+    if fix:
+        fix_files_cmd(audit_only=False)
+    else:
+        fix_files_cmd(audit_only=True)
+
+
+@app.command()
+def fix_files() -> None:
+    """Stops jetbase from tracking migrations whose files no longer exist."""
+    validate_jetbase_directory()
+    fix_files_cmd(audit_only=False)
+
+
+@app.command()
+def status() -> None:
+    """Display migration status: applied migrations and pending migrations."""
+    validate_jetbase_directory()
+    status_cmd()
+
+
+# check if typer enforces enum types - if yes then create enum for migration type
+@app.command()
+def new(
+    description: str = typer.Argument(..., help="Description of the migration"),
+) -> None:
+    """Create a new migration file with a timestamp-based version and the provided description."""
+    validate_jetbase_directory()
+    generate_new_migration_file_cmd(description=description)
+
+
 def main() -> None:
+    """
+    Entry point for the Jetbase CLI application.
+
+    Initializes and runs the Typer application that handles all CLI commands
+    including migrations, rollbacks, and database management operations.
+    """
     app()
 
 

jetbase/commands/current.py

@@ -0,0 +1,20 @@
+from jetbase.models import MigrationRecord
+from jetbase.repositories.migrations_repo import fetch_latest_versioned_migration
+
+
+def current_cmd() -> None:
+    """
+    Display the current (latest applied) migration version.
+
+    Queries the database for the most recently applied versioned migration
+    and prints its version number. If no migrations have been applied,
+    displays a message indicating that.
+
+    Returns:
+        None: Prints the current migration version to stdout.
+    """
+    latest_migration: MigrationRecord | None = fetch_latest_versioned_migration()
+    if latest_migration:
+        print(f"Latest migration version: {latest_migration.version}")
+    else:
+        print("No migrations have been applied yet.")

jetbase/commands/fix_checksums.py

@@ -0,0 +1,172 @@
+import os
+
+from jetbase.constants import MIGRATIONS_DIR
+from jetbase.engine.checksum import calculate_checksum
+from jetbase.engine.file_parser import parse_upgrade_statements
+from jetbase.engine.lock import migration_lock
+from jetbase.engine.validation import run_migration_validations
+from jetbase.engine.version import get_migration_filepaths_by_version
+from jetbase.exceptions import (
+    MigrationVersionMismatchError,
+)
+from jetbase.repositories.migrations_repo import (
+    get_checksums_by_version,
+    update_migration_checksums,
+)
+
+
+def fix_checksums_cmd(audit_only: bool = False) -> None:
+    """
+    Fix or audit checksums for applied migrations.
+
+    Compares the checksums stored in the database against the current checksums
+    of migration files on disk. Detects drift where files have been modified
+    after being applied to the database.
+
+    Args:
+        audit_only (bool): If True, only reports checksum mismatches without
+            making any changes to the database. If False, updates the stored
+            checksums to match the current file contents. Defaults to False.
+
+    Returns:
+        None: Prints audit report or repair status to stdout.
+
+    Raises:
+        MigrationVersionMismatchError: If there is a mismatch between expected
+            and actual migration versions during processing.
+    """
+
+    migrated_versions_and_checksums: list[tuple[str, str]] = get_checksums_by_version()
+    if not migrated_versions_and_checksums:
+        print("No migrations have been applied; nothing to repair.")
+        return
+
+    latest_migrated_version: str = migrated_versions_and_checksums[-1][0]
+
+    run_migration_validations(
+        latest_migrated_version=latest_migrated_version,
+        skip_checksum_validation=True,
+    )
+
+    versions_and_checksums_to_repair: list[tuple[str, str]] = _find_checksum_mismatches(
+        migrated_versions_and_checksums=migrated_versions_and_checksums,
+        latest_migrated_version=latest_migrated_version,
+    )
+
+    if not versions_and_checksums_to_repair:
+        print(
+            "All migration checksums are valid - no altered upgrade statments detected."
+        )
+        return
+
+    if audit_only:
+        _print_audit_report(
+            versions_and_checksums_to_repair=versions_and_checksums_to_repair
+        )
+        return
+
+    _repair_checksums(versions_and_checksums_to_repair=versions_and_checksums_to_repair)
+
+
+def _print_audit_report(
+    versions_and_checksums_to_repair: list[tuple[str, str]],
+) -> None:
+    """
+    Print a formatted report of migrations with checksum drift.
+
+    Outputs a list of migration versions whose file contents have changed
+    since they were originally applied to the database.
+
+    Args:
+        versions_and_checksums_to_repair (list[tuple[str, str]]): List of tuples
+            containing (version, new_checksum) for migrations with detected drift.
+
+    Returns:
+        None: Prints the audit report to stdout.
+    """
+    print("\nJETBASE - Checksum Audit Report")
+    print("----------------------------------------")
+    print("Changes detected in the following files:")
+    for file_version, _ in versions_and_checksums_to_repair:
+        print(f" → {file_version}")
+
+
+def _repair_checksums(versions_and_checksums_to_repair: list[tuple[str, str]]) -> None:
+    """
+    Update checksums in the database for migrations with detected drift.
+
+    Acquires a migration lock and updates the stored checksums in the
+    jetbase_migrations table to match the current file contents.
+
+    Args:
+        versions_and_checksums_to_repair (list[tuple[str, str]]): List of tuples
+            containing (version, new_checksum) for migrations to update.
+
+    Returns:
+        None: Prints repair status for each version to stdout.
+    """
+    with migration_lock():
+        update_migration_checksums(
+            versions_and_checksums=versions_and_checksums_to_repair
+        )
+        for version, _ in versions_and_checksums_to_repair:
+            print(f"Repaired checksum for version: {version}")
+
+    print("Successfully repaired checksums")
+
+
+def _find_checksum_mismatches(
+    migrated_versions_and_checksums: list[tuple[str, str]], latest_migrated_version: str
+) -> list[tuple[str, str]]:
+    """
+    Find migrations where the file checksum differs from the stored checksum.
+
+    Compares the current checksum of each migration file against the checksum
+    stored in the database when the migration was originally applied.
+
+    Args:
+        migrated_versions_and_checksums (list[tuple[str, str]]): List of tuples
+            containing (version, stored_checksum) from the database.
+        latest_migrated_version (str): The most recent version that has been
+            migrated, used to limit the scope of files checked.
+
+    Returns:
+        list[tuple[str, str]]: List of (version, new_checksum) tuples for
+            migrations where the file has changed since being applied.
+
+    Raises:
+        MigrationVersionMismatchError: If the file versions do not match the
+            expected sequence of migrated versions.
+
+    Example:
+        >>> _find_checksum_mismatches([("1.0", "abc123")], "1.0")
+        [("1.0", "def456")]  # If file changed
+    """
+    migration_filepaths_by_version: dict[str, str] = get_migration_filepaths_by_version(
+        directory=os.path.join(os.getcwd(), MIGRATIONS_DIR),
+        end_version=latest_migrated_version,
+    )
+
+    versions_and_checksums_to_repair: list[tuple[str, str]] = []
+
+    for index, (file_version, filepath) in enumerate(
+        migration_filepaths_by_version.items()
+    ):
+        sql_statements: list[str] = parse_upgrade_statements(file_path=filepath)
+        checksum: str = calculate_checksum(sql_statements=sql_statements)
+
+        # this should never be hit because of the validation check above
+        if file_version != migrated_versions_and_checksums[index][0]:
+            raise MigrationVersionMismatchError(
+                f"Version mismatch123: expected {migrated_versions_and_checksums[index][0]}, found {file_version}."
+            )
+
+        if checksum != migrated_versions_and_checksums[index][1]:
+            versions_and_checksums_to_repair.append(
+                (
+                    file_version,
+                    checksum,
+                )
+            )
+
+    return versions_and_checksums_to_repair

jetbase/commands/fix_files.py

@@ -0,0 +1,133 @@
+import os
+
+from jetbase.engine.lock import migration_lock
+from jetbase.engine.repeatable import get_repeatable_filenames
+from jetbase.engine.version import (
+    get_migration_filepaths_by_version,
+)
+from jetbase.models import MigrationRecord
+from jetbase.repositories.lock_repo import create_lock_table_if_not_exists
+from jetbase.repositories.migrations_repo import (
+    create_migrations_table_if_not_exists,
+    delete_missing_repeatables,
+    delete_missing_versions,
+    fetch_repeatable_migrations,
+    get_migrated_versions,
+)
+
+
+def fix_files_cmd(audit_only: bool = False) -> None:
+    """
+    Remove database records for missing migration files.
+
+    Reconciles the migration state between the database and the filesystem
+    by identifying migrations whose corresponding files no longer exist.
+    Handles both versioned and repeatable migrations.
+
+    Args:
+        audit_only (bool): If True, only reports missing migration files
+            without making any changes to the database. If False, removes
+            database records for missing migrations. Defaults to False.
+
+    Returns:
+        None: Prints audit report or removal status to stdout.
+    """
+
+    create_lock_table_if_not_exists()
+    create_migrations_table_if_not_exists()
+
+    migrated_versions: list[str] = get_migrated_versions()
+    current_migration_filepaths_by_version: dict[str, str] = (
+        get_migration_filepaths_by_version(
+            directory=os.path.join(os.getcwd(), "migrations")
+        )
+    )
+    repeatable_migrations: list[MigrationRecord] = fetch_repeatable_migrations()
+    all_repeatable_filenames: list[str] = get_repeatable_filenames()
+
+    missing_versions: list[str] = []
+    missing_repeatables: list[str] = []
+
+    for migrated_version in migrated_versions:
+        if migrated_version not in current_migration_filepaths_by_version:
+            missing_versions.append(migrated_version)
+
+    for r_migration in repeatable_migrations:
+        if r_migration.filename not in all_repeatable_filenames:
+            missing_repeatables.append(r_migration.filename)
+
+    if audit_only:
+        _print_audit_report(
+            missing_versions=missing_versions, missing_repeatables=missing_repeatables
+        )
+        return
+
+    _remove_missing_migrations(
+        missing_versions=missing_versions, missing_repeatables=missing_repeatables
+    )
+
+
+def _print_audit_report(
+    missing_versions: list[str], missing_repeatables: list[str]
+) -> None:
+    """
+    Print a formatted report of migrations with missing files.
+
+    Lists all versioned and repeatable migrations that are tracked in the
+    database but no longer have corresponding files on disk.
+
+    Args:
+        missing_versions (list[str]): List of version strings for versioned
+            migrations with missing files.
+        missing_repeatables (list[str]): List of filenames for repeatable
+            migrations with missing files.
+
+    Returns:
+        None: Prints the audit report to stdout.
+    """
+    if missing_versions or missing_repeatables:
+        print("The following migrations are missing their corresponding files:")
+        for version in missing_versions:
+            print(f"→ {version}")
+        for r_file in missing_repeatables:
+            print(f"→ {r_file}")
+
+    else:
+        print("All migrations have corresponding files.")
+
+
+def _remove_missing_migrations(
+    missing_versions: list[str], missing_repeatables: list[str]
+) -> None:
+    """
+    Delete database records for migrations whose files no longer exist.
+
+    Acquires a migration lock and removes records from the jetbase_migrations
+    table for both versioned and repeatable migrations that are missing files.
+
+    Args:
+        missing_versions (list[str]): List of version strings for versioned
+            migrations to remove from tracking.
+        missing_repeatables (list[str]): List of filenames for repeatable
+            migrations to remove from tracking.
+
+    Returns:
+        None: Prints removal status for each migration to stdout.
+    """
+    if missing_versions or missing_repeatables:
+        with migration_lock():
+            if missing_versions:
+                delete_missing_versions(versions=missing_versions)
+                print("Stopped tracking the following missing versions:")
+                for version in missing_versions:
+                    print(f"→ {version}")
+
+            if missing_repeatables:
+                delete_missing_repeatables(repeatable_filenames=missing_repeatables)
+                print(
+                    "Removed the following missing repeatable migrations from the database:"
+                )
+                for r_file in missing_repeatables:
+                    print(f"→ {r_file}")
+    else:
+        print("No missing migration files.")

jetbase/commands/history.py

@@ -0,0 +1,53 @@
+from rich.console import Console
+from rich.table import Table
+
+from jetbase.engine.formatters import format_applied_at, get_display_version
+from jetbase.models import MigrationRecord
+from jetbase.repositories.migrations_repo import (
+    get_migration_records,
+    migrations_table_exists,
+)
+
+
+def history_cmd() -> None:
+    """
+    Display the migration history in a formatted table.
+
+    Retrieves all applied migrations from the database and displays them
+    in a rich-formatted table showing version numbers, execution order,
+    descriptions, and timestamps.
+
+    Returns:
+        None: Prints a formatted table to stdout, or a message if no
+            migrations have been applied.
+    """
+    console: Console = Console()
+    table_exists: bool = migrations_table_exists()
+    if not table_exists:
+        console.print("[yellow]No migrations have been applied.[/yellow]")
+        return None
+
+    migration_records: list[MigrationRecord] = get_migration_records()
+    if not migration_records:
+        console.print("[yellow]No migrations have been applied yet.[/yellow]")
+        return
+
+    migration_history_table: Table = Table(
+        title="Migration History", show_header=True, header_style="bold magenta"
+    )
+    migration_history_table.add_column("Version", style="cyan", no_wrap=True)
+    migration_history_table.add_column("Order Executed", style="green")
+    migration_history_table.add_column("Description", style="white")
+    migration_history_table.add_column("Applied At", style="green", no_wrap=True)
+
+    for record in migration_records:
+        migration_history_table.add_row(
+            get_display_version(
+                version=record.version, migration_type=record.migration_type
+            ),
+            str(record.order_executed),
+            record.description,
+            format_applied_at(applied_at=record.applied_at),
+        )
+
+    console.print(migration_history_table)

jetbase/commands/init.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from jetbase.constants import BASE_DIR, ENV_FILE, ENV_FILE_CONTENT, MIGRATIONS_DIR
+
+# def initialize_cmd() -> None:
+#     create_directory_structure(base_path=BASE_DIR)
+
+
+def initialize_cmd() -> None:
+    """
+    Create the directory structure for a new Jetbase project.
+
+    Creates a 'jetbase' directory containing a 'migrations' subdirectory
+    and an 'env.py' configuration file with a template database URL.
+
+    Returns:
+        None: Prints a confirmation message with the project location.
+    """
+    migrations_dir: Path = Path(BASE_DIR) / MIGRATIONS_DIR
+    migrations_dir.mkdir(parents=True, exist_ok=True)
+
+    config_path: Path = Path(BASE_DIR) / ENV_FILE
+    with open(config_path, "w") as f:
+        f.write(ENV_FILE_CONTENT)
+
+    print(
+        f"Initialized Jetbase project in {Path(BASE_DIR).absolute()}\n"
+        "Run 'cd jetbase' to get started!"
+    )

jetbase/commands/lock_status.py

@@ -0,0 +1,25 @@
+from jetbase.models import LockStatus
+from jetbase.repositories.lock_repo import fetch_lock_status, lock_table_exists
+from jetbase.repositories.migrations_repo import migrations_table_exists
+
+
+def lock_status_cmd() -> None:
+    """
+    Display whether the migration lock is currently held.
+
+    Queries the jetbase_lock table to check if migrations are currently
+    locked. If locked, displays the timestamp when the lock was acquired.
+
+    Returns:
+        None: Prints "LOCKED" with timestamp or "UNLOCKED" to stdout.
+    """
+
+    if not lock_table_exists() or not migrations_table_exists():
+        print("Status: UNLOCKED")
+        return
+
+    lock_status: LockStatus = fetch_lock_status()
+    if lock_status.is_locked:
+        print(f"Status: LOCKED\nLocked At: {lock_status.locked_at}")
+    else:
+        print("Status: UNLOCKED")

jetbase/commands/new.py

@@ -0,0 +1,65 @@
+import datetime as dt
+import os
+
+from jetbase.constants import MIGRATIONS_DIR, NEW_MIGRATION_FILE_CONTENT
+from jetbase.exceptions import DirectoryNotFoundError
+
+
+def generate_new_migration_file_cmd(description: str) -> None:
+    """
+    Generate a new migration file with a timestamped filename.
+
+    Creates a new SQL migration file in the migrations directory with a
+    filename format of V{timestamp}__{description}.sql. The file contains
+    template sections for upgrade and rollback SQL statements.
+
+    Args:
+        description (str): A human-readable description for the migration.
+            Spaces will be replaced with underscores in the filename.
+
+    Returns:
+        None: Prints the created filename to stdout.
+
+    Raises:
+        DirectoryNotFoundError: If the migrations directory does not exist.
+
+    Example:
+        >>> generate_new_migration_file_cmd("create users table")
+        Created migration file: V20251201.120000__create_users_table.sql
+    """
+
+    migrations_dir_path: str = os.path.join(os.getcwd(), MIGRATIONS_DIR)
+
+    if not os.path.exists(migrations_dir_path):
+        raise DirectoryNotFoundError(
+            "Migrations directory not found. Run 'jetbase initialize' to set up jetbase.\n"
+            "If you have already done so, run this command from the jetbase directory."
+        )
+
+    filename: str = _generate_new_filename(description=description)
+    filepath: str = os.path.join(migrations_dir_path, filename)
+
+    with open(filepath, "w") as f:  # noqa: F841
+        f.write(NEW_MIGRATION_FILE_CONTENT)
+    print(f"Created migration file: {filename}")
+
+
+def _generate_new_filename(description: str) -> str:
+    """
+    Generate a timestamped filename for a migration.
+
+    Creates a filename using the current timestamp in YYYYMMDD.HHMMSS format
+    followed by the description with spaces converted to underscores.
+
+    Args:
+        description (str): A human-readable description for the migration.
+
+    Returns:
+        str: Formatted filename like "V20251201.120000__description.sql".
+
+    Example:
+        >>> _generate_new_filename("add users")
+        'V20251201.120000__add_users.sql'
+    """
+    timestamp = dt.datetime.now().strftime("%Y%m%d.%H%M%S")
+    return f"V{timestamp}__{description.replace(' ', '_')}.sql"