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

jetbase/commands/rollback.py

@@ -0,0 +1,172 @@
+import os
+
+from jetbase.engine.dry_run import process_dry_run
+from jetbase.engine.file_parser import parse_rollback_statements
+from jetbase.engine.lock import (
+    migration_lock,
+)
+from jetbase.engine.version import get_migration_filepaths_by_version
+from jetbase.enums import MigrationDirectionType
+from jetbase.exceptions import VersionNotFoundError
+from jetbase.repositories.lock_repo import create_lock_table_if_not_exists
+from jetbase.repositories.migrations_repo import (
+    create_migrations_table_if_not_exists,
+    get_latest_versions,
+    run_migration,
+)
+
+
+def rollback_cmd(
+    count: int | None = None, to_version: str | None = None, dry_run: bool = False
+) -> None:
+    """
+    Rollback applied migrations.
+
+    Reverts previously applied migrations by executing their rollback SQL
+    statements in reverse order. Can rollback a specific number of migrations
+    or all migrations after a specified version.
+
+    Args:
+        count (int | None): Number of migrations to rollback. If None and
+            to_version is also None, defaults to 1. Defaults to None.
+        to_version (str | None): Rollback all migrations applied after this
+            version. Cannot be used with count. Defaults to None.
+        dry_run (bool): If True, shows a preview of the rollback SQL without
+            executing it. Defaults to False.
+
+    Returns:
+        None: Prints rollback status for each migration to stdout.
+
+    Raises:
+        ValueError: If both count and to_version are specified.
+        VersionNotFoundError: If a required migration file is missing.
+    """
+    create_migrations_table_if_not_exists()
+    create_lock_table_if_not_exists()
+
+    if count is not None and to_version is not None:
+        raise ValueError(
+            "Cannot specify both 'count' and 'to_version' for rollback. "
+            "Select only one, or do not specify either to rollback the last migration."
+        )
+    if count is None and to_version is None:
+        count = 1
+
+    latest_migration_versions: list[str] = _get_latest_migration_versions(
+        count=count, to_version=to_version
+    )
+
+    if not latest_migration_versions:
+        print("Nothing to rollback.")
+        return
+
+    versions_to_rollback: dict[str, str] = _get_versions_to_rollback(
+        latest_migration_versions=latest_migration_versions
+    )
+
+    _validate_rollback_files_exist(
+        latest_migration_versions=latest_migration_versions,
+        versions_to_rollback=versions_to_rollback,
+    )
+
+    if not dry_run:
+        with migration_lock():
+            print("Starting rollback...")
+            for version, file_path in versions_to_rollback.items():
+                sql_statements: list[str] = parse_rollback_statements(
+                    file_path=file_path
+                )
+                filename: str = os.path.basename(file_path)
+
+                run_migration(
+                    sql_statements=sql_statements,
+                    version=version,
+                    migration_operation=MigrationDirectionType.ROLLBACK,
+                    filename=filename,
+                )
+
+                print(f"Rollback applied successfully: {filename}")
+            print("Rollbacks completed successfully.")
+
+    else:
+        process_dry_run(
+            version_to_filepath=versions_to_rollback,
+            migration_operation=MigrationDirectionType.ROLLBACK,
+        )
+
+
+def _get_latest_migration_versions(
+    count: int | None = None, to_version: str | None = None
+) -> list[str]:
+    """
+    Get the latest migration versions from the database.
+
+    Retrieves migration versions either by count or by starting version.
+    If neither is specified, returns the single most recent migration.
+
+    Args:
+        count (int | None): Number of migrations to retrieve.
+            Defaults to None.
+        to_version (str | None): Retrieve all migrations applied after
+            this version. Defaults to None.
+
+    Returns:
+        list[str]: List of version strings in order of application.
+    """
+    if count:
+        return get_latest_versions(limit=count)
+    elif to_version:
+        return get_latest_versions(starting_version=to_version)
+    else:
+        return get_latest_versions(limit=1)
+
+
+def _get_versions_to_rollback(latest_migration_versions: list[str]) -> dict[str, str]:
+    """
+    Get migration file paths for versions to rollback.
+
+    Maps version strings to their corresponding file paths, ordered
+    in reverse (newest first) for rollback execution.
+
+    Args:
+        latest_migration_versions (list[str]): List of version strings
+            to rollback, ordered oldest to newest.
+
+    Returns:
+        dict[str, str]: Mapping of version to file path, reversed so
+            newest versions are rolled back first.
+    """
+    versions_to_rollback: dict[str, str] = get_migration_filepaths_by_version(
+        directory=os.path.join(os.getcwd(), "migrations"),
+        version_to_start_from=latest_migration_versions[-1],
+        end_version=latest_migration_versions[0],
+    )
+
+    return dict(reversed(versions_to_rollback.items()))
+
+
+def _validate_rollback_files_exist(
+    latest_migration_versions: list[str], versions_to_rollback: dict[str, str]
+) -> None:
+    """
+    Validate that all migration files exist for rollback.
+
+    Ensures every version that needs to be rolled back has a corresponding
+    migration file in the migrations directory.
+
+    Args:
+        latest_migration_versions (list[str]): Version strings that need
+            to be rolled back.
+        versions_to_rollback (dict[str, str]): Mapping of version to
+            file path for available migration files.
+
+    Raises:
+        VersionNotFoundError: If any migration file is missing.
+    """
+    for version in latest_migration_versions:
+        if version not in list(versions_to_rollback.keys()):
+            raise VersionNotFoundError(
+                f"Migration file for version '{version}' not found. Cannot proceed with rollback.\n"
+                "Please restore the missing migration file and try again, or run 'jetbase fix' "
+                "to synchronize the migrations table with existing files before retrying the rollback."
+            )

jetbase/commands/status.py

@@ -0,0 +1,212 @@
+import os
+
+from rich.console import Console
+from rich.table import Table
+
+from jetbase.engine.file_parser import get_description_from_filename
+from jetbase.engine.formatters import get_display_version
+from jetbase.engine.repeatable import get_ra_filenames, get_runs_on_change_filepaths
+from jetbase.engine.version import get_migration_filepaths_by_version
+from jetbase.enums import MigrationType
+from jetbase.models import MigrationRecord
+from jetbase.repositories.migrations_repo import (
+    create_migrations_table_if_not_exists,
+    get_existing_on_change_filenames_to_checksums,
+    get_migration_records,
+    migrations_table_exists,
+)
+
+
+def status_cmd() -> None:
+    """
+    Display applied and pending migrations.
+
+    Shows two tables: one listing all migrations that have been applied to
+    the database, and another listing pending migrations that are available
+    in the migrations directory but have not yet been applied.
+
+    Returns:
+        None: Prints formatted tables to stdout showing migration status.
+    """
+    is_migrations_table: bool = migrations_table_exists()
+    if not is_migrations_table:
+        create_migrations_table_if_not_exists()
+        is_migrations_table = True
+
+    migration_records: list[MigrationRecord] = (
+        get_migration_records() if is_migrations_table else []
+    )
+
+    versioned_migration_records: list[MigrationRecord] = [
+        record
+        for record in migration_records
+        if record.migration_type == MigrationType.VERSIONED.value
+    ]
+
+    latest_migrated_version: str | None = (
+        versioned_migration_records[-1].version if versioned_migration_records else None
+    )
+
+    pending_versioned_filepaths: dict[str, str] = get_migration_filepaths_by_version(
+        directory=os.path.join(os.getcwd(), "migrations"),
+        version_to_start_from=latest_migrated_version,
+    )
+
+    if latest_migrated_version:
+        pending_versioned_filepaths = dict(
+            list(pending_versioned_filepaths.items())[1:]
+        )
+
+    all_roc_filenames: list[str] = get_ra_filenames()
+
+    roc_filenames_changed_only: list[str] = [
+        os.path.basename(filepath)
+        for filepath in get_runs_on_change_filepaths(
+            directory=os.path.join(os.getcwd(), "migrations"), changed_only=True
+        )
+    ]
+
+    roc_filenames_migrated: list[str] = list(
+        get_existing_on_change_filenames_to_checksums().keys()
+    )
+
+    all_roc_filenames: list[str] = [
+        os.path.basename(filepath)
+        for filepath in get_runs_on_change_filepaths(
+            directory=os.path.join(os.getcwd(), "migrations")
+        )
+    ]
+
+    console = Console()
+
+    applied_table: Table = _create_migrations_display_table(title="Migrations Applied")
+
+    _add_applied_rows(table=applied_table, migration_records=migration_records)
+
+    console.print(applied_table)
+    console.print()
+
+    pending_table: Table = _create_migrations_display_table(title="Migrations Pending")
+
+    _add_pending_rows(
+        table=pending_table,
+        pending_versioned_filepaths=pending_versioned_filepaths,
+        migration_records=migration_records,
+        roc_filenames_changed_only=roc_filenames_changed_only,
+        all_roc_filenames=all_roc_filenames,
+        roc_filenames_migrated=roc_filenames_migrated,
+    )
+
+    console.print(pending_table)
+
+
+def _create_migrations_display_table(title: str) -> Table:
+    """
+    Create a rich Table for displaying migrations.
+
+    Configures a table with styled columns for displaying migration
+    version numbers and descriptions.
+
+    Args:
+        title (str): The title to display above the table.
+
+    Returns:
+        Table: A configured rich Table with Version and Description columns.
+    """
+    display_table: Table = Table(
+        title=title, show_header=True, header_style="bold magenta"
+    )
+    display_table.add_column("Version", style="cyan")
+    display_table.add_column("Description", style="green")
+
+    return display_table
+
+
+def _add_applied_rows(table: Table, migration_records: list[MigrationRecord]) -> None:
+    """
+    Add applied migration rows to the table.
+
+    Populates the table with rows for each applied migration, displaying
+    the version number and description for both versioned and repeatable
+    migrations.
+
+    Args:
+        table (Table): The rich Table to add rows to.
+        migration_records (list[MigrationRecord]): List of migration records
+            that have been applied to the database.
+
+    Returns:
+        None: Modifies the table in place.
+    """
+    for record in migration_records:
+        if record.migration_type == MigrationType.VERSIONED.value:
+            table.add_row(record.version, record.description)
+        else:
+            table.add_row(
+                get_display_version(migration_type=record.migration_type),
+                record.description,
+            )
+
+
+def _add_pending_rows(
+    table: Table,
+    pending_versioned_filepaths: dict[str, str],
+    migration_records: list[MigrationRecord],
+    roc_filenames_changed_only: list[str],
+    all_roc_filenames: list[str],
+    roc_filenames_migrated: list[str],
+) -> None:
+    """
+    Add pending migration rows to the table.
+
+    Populates the table with rows for each pending migration including
+    versioned migrations, runs-always migrations, and runs-on-change
+    migrations that have been modified or not yet applied.
+
+    Args:
+        table (Table): The rich Table to add rows to.
+        pending_versioned_filepaths (dict[str, str]): Mapping of version
+            strings to file paths for pending versioned migrations.
+        migration_records (list[MigrationRecord]): All migration records
+            from the database.
+        roc_filenames_changed_only (list[str]): Filenames of runs-on-change
+            migrations that have been modified since last applied.
+        all_roc_filenames (list[str]): All runs-on-change migration filenames.
+        roc_filenames_migrated (list[str]): Runs-on-change migrations that
+            have been previously applied.
+
+    Returns:
+        None: Modifies the table in place.
+    """
+    for version, filepath in pending_versioned_filepaths.items():
+        table.add_row(
+            version, get_description_from_filename(filename=os.path.basename(filepath))
+        )
+
+    # Runs always
+    for ra_filename in get_ra_filenames():
+        description: str = get_description_from_filename(filename=ra_filename)
+        table.add_row(
+            get_display_version(migration_type=MigrationType.RUNS_ALWAYS.value),
+            description,
+        )
+
+    # Runs on change - changed only
+    for record in migration_records:
+        if (
+            record.migration_type == MigrationType.RUNS_ON_CHANGE.value
+            and record.filename in roc_filenames_changed_only
+        ):
+            table.add_row(
+                get_display_version(migration_type=MigrationType.RUNS_ON_CHANGE.value),
+                record.description,
+            )
+
+    # Runs on change - new
+    for filename in all_roc_filenames:
+        if filename not in roc_filenames_migrated:
+            description: str = get_description_from_filename(filename=filename)
+            table.add_row(
+                get_display_version(migration_type=MigrationType.RUNS_ON_CHANGE.value),
+                description,
+            )

jetbase/commands/unlock.py

@@ -0,0 +1,29 @@
+from jetbase.config import get_config
+from jetbase.repositories.lock_repo import (
+    lock_table_exists,
+    unlock_database,
+)
+from jetbase.repositories.migrations_repo import migrations_table_exists
+
+sqlalchemy_url: str = get_config(required={"sqlalchemy_url"}).sqlalchemy_url
+
+
+def unlock_cmd() -> None:
+    """
+    Force release the migration lock.
+
+    Unconditionally releases the migration lock in the jetbase_lock table.
+    Use this only if you are certain that no migration is currently running,
+    as unlocking during an active migration can cause database corruption.
+
+    Returns:
+        None: Prints "Unlock successful." to stdout.
+    """
+
+    if not lock_table_exists() or not migrations_table_exists():
+        print("Unlock successful.")
+        return
+    #
+    unlock_database()
+
+    print("Unlock successful.")

jetbase/commands/upgrade.py

@@ -0,0 +1,248 @@
+import os
+
+from jetbase.constants import MIGRATIONS_DIR
+from jetbase.engine.dry_run import process_dry_run
+from jetbase.engine.file_parser import parse_upgrade_statements
+from jetbase.engine.lock import migration_lock
+from jetbase.engine.repeatable import (
+    get_repeatable_always_filepaths,
+    get_runs_on_change_filepaths,
+)
+from jetbase.engine.validation import run_migration_validations
+from jetbase.engine.version import (
+    get_migration_filepaths_by_version,
+)
+from jetbase.enums import MigrationDirectionType, MigrationType
+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,
+    fetch_latest_versioned_migration,
+    get_existing_on_change_filenames_to_checksums,
+    get_existing_repeatable_always_migration_filenames,
+    run_migration,
+    run_update_repeatable_migration,
+)
+
+
+def upgrade_cmd(
+    count: int | None = None,
+    to_version: str | None = None,
+    dry_run: bool = False,
+    skip_validation: bool = False,
+    skip_checksum_validation: bool = False,
+    skip_file_validation: bool = False,
+) -> None:
+    """
+    Apply pending migrations to the database in order.
+
+    Args:
+        count (int | None): Maximum number of migrations to apply.
+        to_version (str | None): Apply migrations up to this version.
+        dry_run (bool): Preview SQL without executing.
+        skip_validation (bool): Skip all validations.
+        skip_checksum_validation (bool): Skip checksum validation only.
+        skip_file_validation (bool): Skip file validation only.
+
+    Raises:
+        ValueError: If both count and to_version are specified.
+    """
+
+    if count is not None and to_version is not None:
+        raise ValueError(
+            "Cannot specify both 'count' and 'to_version' for upgrade. "
+            "Select only one, or do not specify either to run all pending migrations."
+        )
+
+    if count:
+        if count < 1 or not isinstance(count, int):
+            raise ValueError("'count' must be a positive integer.")
+
+    create_migrations_table_if_not_exists()
+    create_lock_table_if_not_exists()
+
+    latest_migration: MigrationRecord | None = fetch_latest_versioned_migration()
+
+    if latest_migration:
+        run_migration_validations(
+            latest_migrated_version=latest_migration.version,
+            skip_validation=skip_validation,
+            skip_checksum_validation=skip_checksum_validation,
+            skip_file_validation=skip_file_validation,
+        )
+
+    filepaths_by_version: dict[str, str] = _get_filepaths_by_version(
+        latest_migration=latest_migration,
+        count=count,
+        to_version=to_version,
+    )
+
+    repeatable_always_filepaths: list[str] = get_repeatable_always_filepaths(
+        directory=os.path.join(os.getcwd(), MIGRATIONS_DIR)
+    )
+
+    runs_on_change_filepaths: list[str] = get_runs_on_change_filepaths(
+        directory=os.path.join(os.getcwd(), MIGRATIONS_DIR),
+        changed_only=True,
+    )
+
+    if not dry_run:
+        if (
+            not filepaths_by_version
+            and not repeatable_always_filepaths
+            and not runs_on_change_filepaths
+        ):
+            print("Migrations are up to date.")
+            return
+
+        with migration_lock():
+            print("Starting migrations...")
+
+            _run_versioned_migrations(filepaths_by_version=filepaths_by_version)
+
+            _run_repeatable_always_migrations(
+                repeatable_always_filepaths=repeatable_always_filepaths
+            )
+
+            _run_repeatable_on_change_migrations(
+                runs_on_change_filepaths=runs_on_change_filepaths
+            )
+
+            print("Migrations completed successfully.")
+    else:
+        process_dry_run(
+            version_to_filepath=filepaths_by_version,
+            migration_operation=MigrationDirectionType.UPGRADE,
+            repeatable_always_filepaths=repeatable_always_filepaths,
+            runs_on_change_filepaths=runs_on_change_filepaths,
+        )
+
+
+def _get_filepaths_by_version(
+    latest_migration: MigrationRecord | None,
+    count: int | None = None,
+    to_version: str | None = None,
+) -> dict[str, str]:
+    """
+    Get pending migration file paths filtered by count or target version.
+
+    Args:
+        latest_migration (MigrationRecord | None): The most recently
+            applied migration, or None if no migrations applied.
+        count (int | None): Limit to this many migrations. Defaults to None.
+        to_version (str | None): Include migrations up to this version.
+            Defaults to None.
+
+    Returns:
+        dict[str, str]: Mapping of version to file path for pending migrations.
+
+    Raises:
+        FileNotFoundError: If to_version is not found in pending migrations.
+    """
+    filepaths_by_version: dict[str, str] = get_migration_filepaths_by_version(
+        directory=os.path.join(os.getcwd(), MIGRATIONS_DIR),
+        version_to_start_from=latest_migration.version if latest_migration else None,
+    )
+
+    if latest_migration:
+        filepaths_by_version = dict(list(filepaths_by_version.items())[1:])
+
+    if count:
+        filepaths_by_version = dict(list(filepaths_by_version.items())[:count])
+    elif to_version:
+        if filepaths_by_version.get(to_version) is None:
+            raise FileNotFoundError(
+                f"The specified to_version '{to_version}' does not exist among pending migrations."
+            )
+        seen_versions: dict[str, str] = {}
+        for file_version, file_path in filepaths_by_version.items():
+            seen_versions[file_version] = file_path
+            if file_version == to_version:
+                break
+        filepaths_by_version = seen_versions
+
+    return filepaths_by_version
+
+
+def _run_versioned_migrations(filepaths_by_version: dict[str, str]) -> None:
+    """
+    Execute versioned (V__) migrations.
+
+    Args:
+        filepaths_by_version (dict[str, str]): Mapping of version to file path.
+    """
+    for version, file_path in filepaths_by_version.items():
+        sql_statements: list[str] = parse_upgrade_statements(file_path=file_path)
+        filename: str = os.path.basename(file_path)
+
+        run_migration(
+            sql_statements=sql_statements,
+            version=version,
+            migration_operation=MigrationDirectionType.UPGRADE,
+            filename=filename,
+        )
+
+        print(f"Migration applied successfully: {filename}")
+
+
+def _run_repeatable_always_migrations(
+    repeatable_always_filepaths: list[str],
+) -> None:
+    """
+    Execute runs-always (RA__) migrations.
+
+    Args:
+        repeatable_always_filepaths (list[str]): List of RA__ file paths.
+    """
+    if repeatable_always_filepaths:
+        for filepath in repeatable_always_filepaths:
+            sql_statements: list[str] = parse_upgrade_statements(file_path=filepath)
+            filename: str = os.path.basename(filepath)
+
+            if filename in get_existing_repeatable_always_migration_filenames():
+                run_update_repeatable_migration(
+                    sql_statements=sql_statements,
+                    filename=filename,
+                    migration_type=MigrationType.RUNS_ALWAYS,
+                )
+                print(f"Migration applied successfully: {filename}")
+            else:
+                run_migration(
+                    sql_statements=sql_statements,
+                    version=None,
+                    migration_operation=MigrationDirectionType.UPGRADE,
+                    filename=filename,
+                    migration_type=MigrationType.RUNS_ALWAYS,
+                )
+                print(f"Migration applied successfully: {filename}")
+
+
+def _run_repeatable_on_change_migrations(runs_on_change_filepaths: list[str]) -> None:
+    """
+    Execute runs-on-change (ROC__) migrations.
+
+    Args:
+        runs_on_change_filepaths (list[str]): List of ROC__ file paths.
+    """
+    if runs_on_change_filepaths:
+        for filepath in runs_on_change_filepaths:
+            sql_statements: list[str] = parse_upgrade_statements(file_path=filepath)
+            filename: str = os.path.basename(filepath)
+
+            if filename in list(get_existing_on_change_filenames_to_checksums().keys()):
+                # update migration
+                run_update_repeatable_migration(
+                    sql_statements=sql_statements,
+                    filename=filename,
+                    migration_type=MigrationType.RUNS_ON_CHANGE,
+                )
+                print(f"Migration applied successfully: {filename}")
+            else:
+                run_migration(
+                    sql_statements=sql_statements,
+                    version=None,
+                    migration_operation=MigrationDirectionType.UPGRADE,
+                    filename=filename,
+                    migration_type=MigrationType.RUNS_ON_CHANGE,
+                )
+                print(f"Migration applied successfully: {filename}")

jetbase/commands/validators.py

@@ -0,0 +1,37 @@
+from pathlib import Path
+
+from jetbase.exceptions import DirectoryNotFoundError
+
+
+def validate_jetbase_directory() -> None:
+    """
+    Ensure command is run from jetbase directory with migrations folder.
+
+    Validates that the current working directory is named 'jetbase' and
+    contains a 'migrations' subdirectory. This validation is required
+    before running most Jetbase CLI commands.
+
+    Returns:
+        None: Returns silently if validation passes.
+
+    Raises:
+        DirectoryNotFoundError: If the current directory is not named
+            'jetbase' or if the 'migrations' subdirectory does not exist.
+    """
+    current_dir = Path.cwd()
+
+    # Check if current directory is named 'jetbase'
+    if current_dir.name != "jetbase":
+        raise DirectoryNotFoundError(
+            "Command must be run from the 'jetbase' directory.\n"
+            "You can run 'jetbase init' to create a Jetbase project."
+        )
+
+    # Check if migrations directory exists
+    migrations_dir = current_dir / "migrations"
+    if not migrations_dir.exists() or not migrations_dir.is_dir():
+        raise DirectoryNotFoundError(
+            f"'migrations' directory not found in {current_dir}.\n"
+            "Add a migrations directory inside the 'jetbase' directory to proceed.\n"
+            "You can also run 'jetbase init' to create a Jetbase project."
+        )