jetbase 0.7.0__py3-none-any.whl

jetbase/cli/main.py

@@ -0,0 +1,61 @@
+import typer
+
+from jetbase.core.initialize import initialize_cmd
+from jetbase.core.rollback import rollback_cmd
+from jetbase.core.upgrade import upgrade_cmd
+
+app = typer.Typer(help="Jetbase CLI")
+
+
+@app.command()
+def init():
+    """Initialize jetbase in current directory"""
+    initialize_cmd()
+
+
+@app.command()
+def upgrade(
+    count: int = typer.Option(
+        None, "--count", "-c", help="Number of migrations to apply"
+    ),
+    to_version: str | None = typer.Option(
+        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"
+    ),
+):
+    """Execute pending migrations"""
+    upgrade_cmd(
+        count=count,
+        to_version=to_version.replace("_", ".") if to_version else None,
+        dry_run=dry_run,
+    )
+
+
+@app.command()
+def rollback(
+    count: int = typer.Option(
+        None, "--count", "-c", help="Number of migrations to rollback"
+    ),
+    to_version: str | None = typer.Option(
+        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"
+    ),
+):
+    """Rollback migration(s)"""
+    rollback_cmd(
+        count=count,
+        to_version=to_version.replace("_", ".") if to_version else None,
+        dry_run=dry_run,
+    )
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

jetbase/config.py

@@ -0,0 +1,60 @@
+import importlib.machinery
+import importlib.util
+import os
+
+# from importlib import ModuleType
+from types import ModuleType
+from typing import Any
+
+from jetbase.constants import CONFIG_FILE
+
+
+def get_sqlalchemy_url(filename: str = CONFIG_FILE) -> str:
+    """
+    Load a config file and extract the sqlalchemy_url.
+
+    Args:
+        config_filename: Name of the config file (e.g., "config.py")
+
+    Returns:
+        The sqlalchemy_url from the config file, or None if not found
+    """
+    config_path: str = os.path.join(os.getcwd(), filename)
+    spec: importlib.machinery.ModuleSpec | None = (
+        importlib.util.spec_from_file_location("config", config_path)
+    )
+
+    assert spec is not None
+    assert spec.loader is not None
+
+    config: ModuleType = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module=config)
+
+    raw_sqlalchemy_url: Any | None = getattr(config, "sqlalchemy_url", None)
+
+    if raw_sqlalchemy_url is None:
+        raise AttributeError(
+            f"'sqlalchemy_url' not found or is set to None. Please define it in {config_path}."
+        )
+
+    sqlalchemy_url: str = _validate_sqlalchemy_url(url=raw_sqlalchemy_url)
+
+    return sqlalchemy_url
+
+
+def _validate_sqlalchemy_url(url: Any) -> str:
+    """
+    Validates a SQLAlchemy URL string.
+    This function checks if the provided URL is a valid string.
+    Args:
+        url (Any): The SQLAlchemy URL to validate (could be any type from user config).
+    Returns:
+        str: The validated SQLAlchemy URL string.
+    Raises:
+        TypeError: If the provided URL is not a string.
+    """
+
+    if not isinstance(url, str):
+        raise TypeError(f"sqlalchemy_url must be a string, got {type(url).__name__}")
+
+    return url

jetbase/constants.py

@@ -0,0 +1,12 @@
+from typing import Final
+
+BASE_DIR: Final[str] = "jetbase"
+MIGRATIONS_DIR: Final[str] = "migrations"
+CONFIG_FILE: Final[str] = "config.py"
+
+CONFIG_FILE_CONTENT: Final[str] = """
+# Jetbase Configuration
+# Update the sqlalchemy_url with your database connection string.
+
+sqlalchemy_url = "postgresql://user:password@localhost:5432/mydb"
+"""

jetbase/core/dry_run.py

@@ -0,0 +1,38 @@
+import os
+
+from jetbase.core.file_parser import parse_rollback_statements, parse_upgrade_statements
+from jetbase.enums import MigrationOperationType
+
+
+def process_dry_run(
+    version_to_filepath: dict[str, str], migration_operation: MigrationOperationType
+) -> None:
+    print("\nJETBASE - Dry Run Mode")
+    print("No SQL will be executed. This is a preview of what would happen.")
+    print("----------------------------------------\n\n")
+
+    for version, file_path in version_to_filepath.items():
+        if migration_operation == MigrationOperationType.UPGRADE:
+            sql_statements: list[str] = parse_upgrade_statements(
+                file_path=file_path, dry_run=True
+            )
+        elif migration_operation == MigrationOperationType.ROLLBACK:
+            sql_statements: list[str] = parse_rollback_statements(
+                file_path=file_path, dry_run=True
+            )
+        else:
+            raise NotImplementedError(
+                f"Dry run not implemented for migration operation: {migration_operation}"
+            )
+
+        filename: str = os.path.basename(file_path)
+
+        num_sql_statements: int = len(sql_statements)
+
+        print(
+            f"\nSQL Preview for {filename} ({num_sql_statements} {'statements' if num_sql_statements != 1 else 'statement'})"
+        )
+        for statement in sql_statements:
+            print("\n")
+            print(statement)
+        print("----------------------------------------\n")

jetbase/core/file_parser.py

@@ -0,0 +1,199 @@
+import re
+
+from jetbase.enums import MigrationOperationType
+
+
+def parse_upgrade_statements(file_path: str, dry_run: bool = False) -> list[str]:
+    statements = []
+    current_statement = []
+
+    with open(file_path, "r") as file:
+        for line in file:
+            if not dry_run:
+                line = line.strip()
+            else:
+                line = line.rstrip()
+
+            if (
+                line.strip().startswith("--")
+                and line[2:].strip().lower() == MigrationOperationType.ROLLBACK.value
+            ):
+                break
+
+            if not line or line.strip().startswith("--"):
+                continue
+            current_statement.append(line)
+
+            if line.strip().endswith(";"):
+                if not dry_run:
+                    statement = " ".join(current_statement)
+                else:
+                    statement = "\n".join(current_statement)
+                statement = statement.rstrip(";").strip()
+                if statement:
+                    statements.append(statement)
+                current_statement = []
+
+    return statements
+
+
+def parse_rollback_statements(file_path: str, dry_run: bool = False) -> list[str]:
+    statements = []
+    current_statement = []
+    in_rollback_section = False
+
+    with open(file_path, "r") as file:
+        for line in file:
+            if not dry_run:
+                line = line.strip()
+            else:
+                line = line.rstrip()
+
+            if not in_rollback_section:
+                if (
+                    line.strip().startswith("--")
+                    and line[2:].strip().lower()
+                    == MigrationOperationType.ROLLBACK.value
+                ):
+                    in_rollback_section = True
+                else:
+                    continue
+
+            if in_rollback_section:
+                if not line or line.strip().startswith("--"):
+                    continue
+                current_statement.append(line)
+
+                if line.strip().endswith(";"):
+                    if not dry_run:
+                        statement = " ".join(current_statement)
+                    else:
+                        statement = "\n".join(current_statement)
+                    statement = statement.rstrip(";").strip()
+                    if statement:
+                        statements.append(statement)
+                    current_statement = []
+
+    return statements
+
+
+def is_filename_format_valid(filename: str) -> bool:
+    """
+    Validates if a filename follows the expected migration file naming convention.
+    A valid filename must:
+    - Start with "V"
+    - Have a valid version number following "V"
+    - Contain "__" (double underscore)
+    - End with ".sql"
+    - Have a valid version number extractable from the filename
+    Args:
+        filename (str): The filename to validate.
+    Returns:
+        bool: True if the filename meets all validation criteria, False otherwise.
+    Example:
+        >>> is_valid_filename_format("V1__initial_migration.sql")
+        True
+        >>> is_valid_filename_format("migration.sql")
+        False
+    """
+    if not filename.endswith(".sql"):
+        return False
+    if not filename.startswith("V"):
+        return False
+    if "__" not in filename:
+        return False
+    description: str = _get_raw_description_from_filename(filename=filename)
+    if len(description.strip()) == 0:
+        return False
+    raw_version: str = _get_version_from_filename(filename=filename)
+    if not _is_valid_version(version=raw_version):
+        return False
+    return True
+
+
+def get_description_from_filename(filename: str) -> str:
+    """
+    Extract and format the description from a migration filename.
+
+    Args:
+        filename: The migration filename (e.g., "V1_2_0__add_feature.sql")
+
+    Returns:
+        str: The formatted description string (e.g., "add feature")
+    """
+
+    raw_description: str = _get_raw_description_from_filename(filename=filename)
+    formatted_description: str = raw_description.replace("_", " ")
+    return formatted_description
+
+
+def is_filename_length_valid(filename: str, max_length: int = 512) -> bool:
+    """
+    Check if the filename length is within the specified maximum length.
+
+    Args:
+        filename: The migration filename to check.
+        max_length: The maximum allowed length for the filename.
+
+    Returns:
+        bool: True if the filename length is within the maximum length, False otherwise.
+    """
+    return len(filename) <= max_length
+
+
+def _get_version_from_filename(filename: str) -> str:
+    """
+    Extract the version string from a migration filename.
+
+    Args:
+        filename: The migration filename (e.g., "V1_2_0__add_feature.sql")
+
+    Returns:
+        str: The extracted version string (e.g., "1_2_0")
+    """
+
+    version: str = filename[1 : filename.index("__")]
+    return version
+
+
+def _get_raw_description_from_filename(filename: str) -> str:
+    """
+    Extract the description string from a migration filename.
+
+    Args:
+        filename: The migration filename (e.g., "V1_2_0__add_feature.sql")
+
+    Returns:
+        str: The extracted description string (e.g., "add_feature")
+    """
+
+    description: str = filename[
+        filename.index("__") + 2 : filename.index(".sql")
+    ].strip()
+    return description
+
+
+def _is_valid_version(version: str) -> bool:
+    """
+    Validate that a version string follows the correct format.
+
+    Rules:
+    - Must start and end with a number
+    - Can be any length (1 or greater)
+    - Can contain periods (.) or underscores (_) between numbers
+
+    Valid examples: "1", "1.2", "1_2", "1.2.3", "1_2_3", "10.20.30"
+    Invalid examples: ".1", "1.", "_1", "1_", "1..2", "1__2", "abc", ""
+
+    Args:
+        version: The version string to validate
+
+    Returns:
+        bool: True if version is valid, False otherwise
+    """
+    if not version:
+        return False
+
+    # Pattern: starts with digit, ends with digit, can have periods/underscores between digits
+    pattern = r"^\d+([._]\d+)*$"
+    return bool(re.match(pattern, version))

jetbase/core/initialize.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from jetbase.constants import BASE_DIR, CONFIG_FILE, CONFIG_FILE_CONTENT, MIGRATIONS_DIR
+
+
+def create_directory_structure(base_path: str) -> None:
+    """
+    Create the basic directory structure for a new Jetbase project.
+
+    This function creates:
+    - A migrations directory
+    - A config file with default content
+
+    After creating the structure, it prints a confirmation message.
+
+    Args:
+        base_path (str): The base path where the Jetbase project structure will be created
+
+    Returns:
+        None
+    """
+    migrations_dir: Path = Path(base_path) / MIGRATIONS_DIR
+    migrations_dir.mkdir(parents=True, exist_ok=True)
+
+    config_path: Path = Path(base_path) / CONFIG_FILE
+    with open(config_path, "w") as f:
+        f.write(CONFIG_FILE_CONTENT)
+
+    print(f"Initialized Jetbase project in {Path(base_path).absolute()}")
+
+
+def initialize_cmd() -> None:
+    create_directory_structure(base_path=BASE_DIR)

jetbase/core/repository.py

@@ -0,0 +1,169 @@
+from sqlalchemy import Engine, Result, create_engine, text
+
+from jetbase.config import get_sqlalchemy_url
+from jetbase.core.file_parser import get_description_from_filename
+from jetbase.enums import MigrationOperationType
+from jetbase.queries import (
+    CHECK_IF_MIGRATIONS_TABLE_EXISTS_QUERY,
+    CHECK_IF_VERSION_EXISTS_QUERY,
+    CREATE_MIGRATIONS_TABLE_STMT,
+    DELETE_VERSION_STMT,
+    INSERT_VERSION_STMT,
+    LATEST_VERSION_QUERY,
+    LATEST_VERSIONS_BY_STARTING_VERSION_QUERY,
+    LATEST_VERSIONS_QUERY,
+)
+
+
+def get_last_updated_version() -> str | None:
+    """
+    Retrieves the latest version from the database.
+    This function connects to the database, executes a query to get the most recent version,
+    and returns that version as a string.
+    Returns:
+        str | None: The latest version string if available, None if no version was found.
+    """
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+
+    with engine.begin() as connection:
+        result: Result[tuple[str]] = connection.execute(LATEST_VERSION_QUERY)
+        latest_version: str | None = result.scalar()
+    if not latest_version:
+        return None
+    return latest_version
+
+
+def create_migrations_table_if_not_exists() -> None:
+    """
+    Creates the migrations table in the database
+    if it does not already exist.
+    Returns:
+        None
+    """
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+    with engine.begin() as connection:
+        connection.execute(statement=CREATE_MIGRATIONS_TABLE_STMT)
+
+
+def run_migration(
+    sql_statements: list[str],
+    version: str,
+    migration_operation: MigrationOperationType,
+    filename: str | None = None,
+) -> None:
+    """
+    Execute a database migration by running SQL statements and recording the migration version.
+    Args:
+        sql_statements (list[str]): List of SQL statements to execute as part of the migration
+        version (str): Version identifier to record after successful migration
+    Returns:
+        None
+    """
+
+    if migration_operation == MigrationOperationType.UPGRADE and filename is None:
+        raise ValueError("Filename must be provided for upgrade migrations.")
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+
+    with engine.begin() as connection:
+        for statement in sql_statements:
+            connection.execute(text(statement))
+
+        if migration_operation == MigrationOperationType.UPGRADE:
+            assert filename is not None
+            description: str = get_description_from_filename(filename=filename)
+            connection.execute(
+                statement=INSERT_VERSION_STMT,
+                parameters={
+                    "version": version,
+                    "description": description,
+                    "filename": filename,
+                },
+            )
+
+        elif migration_operation == MigrationOperationType.ROLLBACK:
+            connection.execute(
+                statement=DELETE_VERSION_STMT, parameters={"version": version}
+            )
+
+
+def get_latest_versions(limit: int) -> list[str]:
+    """
+    Retrieve the latest N migration versions from the database.
+    Args:
+        limit (int): The number of latest versions to retrieve
+    Returns:
+        list[str]: A list of the latest migration version strings
+    """
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+    latest_versions: list[str] = []
+
+    with engine.begin() as connection:
+        result: Result[tuple[str]] = connection.execute(
+            statement=LATEST_VERSIONS_QUERY,
+            parameters={"limit": limit},
+        )
+        latest_versions: list[str] = [row[0] for row in result.fetchall()]
+
+    return latest_versions
+
+
+def get_latest_versions_by_starting_version(
+    starting_version: str,
+) -> list[str]:
+    """
+    Retrieve the latest N migration versions from the database,
+    starting from a specific version.
+    Args:
+        starting_version (str): The version to start retrieving from
+        limit (int): The number of latest versions to retrieve
+    Returns:
+        list[str]: A list of the latest migration version strings
+    """
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+    latest_versions: list[str] = []
+    starting_version = starting_version
+
+    with engine.begin() as connection:
+        version_exists_result: Result[tuple[int]] = connection.execute(
+            statement=CHECK_IF_VERSION_EXISTS_QUERY,
+            parameters={"version": starting_version},
+        )
+        version_exists: int = version_exists_result.scalar_one()
+
+        if version_exists == 0:
+            raise ValueError(
+                f"'{starting_version}' has not been applied yet or does not exist."
+            )
+
+        latest_versions_result: Result[tuple[str]] = connection.execute(
+            statement=LATEST_VERSIONS_BY_STARTING_VERSION_QUERY,
+            parameters={"starting_version": starting_version},
+        )
+        latest_versions: list[str] = [
+            row[0] for row in latest_versions_result.fetchall()
+        ]
+
+    return latest_versions
+
+
+def migrations_table_exists() -> bool:
+    """
+    Check if the jetbase_migrations table exists in the database.
+    Returns:
+        bool: True if the jetbase_migrations table exists, False otherwise.
+    """
+
+    engine: Engine = create_engine(url=get_sqlalchemy_url())
+
+    with engine.begin() as connection:
+        result: Result[tuple[bool]] = connection.execute(
+            statement=CHECK_IF_MIGRATIONS_TABLE_EXISTS_QUERY
+        )
+        table_exists: bool = result.scalar_one()
+
+    return table_exists

jetbase/core/rollback.py

@@ -0,0 +1,67 @@
+import os
+
+from jetbase.core.dry_run import process_dry_run
+from jetbase.core.file_parser import parse_rollback_statements
+from jetbase.core.repository import (
+    get_latest_versions,
+    get_latest_versions_by_starting_version,
+    migrations_table_exists,
+    run_migration,
+)
+from jetbase.core.version import get_migration_filepaths_by_version
+from jetbase.enums import MigrationOperationType
+
+
+def rollback_cmd(
+    count: int | None = None, to_version: str | None = None, dry_run: bool = False
+) -> None:
+    table_exists: bool = migrations_table_exists()
+    if not table_exists:
+        print("No migrations have been applied; nothing to rollback.")
+        return
+
+    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] = []
+    if count:
+        latest_migration_versions = get_latest_versions(limit=count)
+    elif to_version:
+        latest_migration_versions = get_latest_versions_by_starting_version(
+            starting_version=to_version
+        )
+
+    if not latest_migration_versions:
+        print("No migrations have been applied; nothing to rollback.")
+        return
+
+    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],
+    )
+
+    versions_to_rollback: dict[str, str] = dict(reversed(versions_to_rollback.items()))
+
+    if not dry_run:
+        for version, file_path in versions_to_rollback.items():
+            sql_statements: list[str] = parse_rollback_statements(file_path=file_path)
+            run_migration(
+                sql_statements=sql_statements,
+                version=version,
+                migration_operation=MigrationOperationType.ROLLBACK,
+            )
+            filename: str = os.path.basename(file_path)
+
+            print(f"Rollback applied successfully: {filename}")
+
+    else:
+        process_dry_run(
+            version_to_filepath=versions_to_rollback,
+            migration_operation=MigrationOperationType.ROLLBACK,
+        )

jetbase/core/upgrade.py

@@ -0,0 +1,75 @@
+import os
+
+from jetbase.core.dry_run import process_dry_run
+from jetbase.core.file_parser import parse_upgrade_statements
+from jetbase.core.repository import (
+    create_migrations_table_if_not_exists,
+    get_last_updated_version,
+    run_migration,
+)
+from jetbase.core.version import get_migration_filepaths_by_version
+from jetbase.enums import MigrationOperationType
+
+
+def upgrade_cmd(
+    count: int | None = None, to_version: str | None = None, dry_run: bool = False
+) -> None:
+    """
+    Run database migrations by applying all pending SQL migration files.
+    Executes migration files in order starting from the last applied version,
+    updating the migrations tracking table after each successful migration.
+
+    Returns:
+        None
+    """
+
+    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."
+        )
+
+    create_migrations_table_if_not_exists()
+    latest_version: str | None = get_last_updated_version()
+
+    all_versions: dict[str, str] = get_migration_filepaths_by_version(
+        directory=os.path.join(os.getcwd(), "migrations"),
+        version_to_start_from=latest_version,
+    )
+
+    if latest_version:
+        all_versions = dict(list(all_versions.items())[1:])
+
+    if count:
+        all_versions = dict(list(all_versions.items())[:count])
+    elif to_version:
+        if all_versions.get(to_version) is None:
+            raise ValueError(
+                f"The specified to_version '{to_version}' does not exist among pending migrations."
+            )
+        all_versions_list = []
+        for file_version, file_path in all_versions.items():
+            all_versions_list.append((file_version, file_path))
+            if file_version == to_version:
+                break
+        all_versions = dict(all_versions_list)
+
+    if not dry_run:
+        for version, file_path in all_versions.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=MigrationOperationType.UPGRADE,
+                filename=filename,
+            )
+
+            print(f"Migration applied successfully: {filename}")
+
+    else:
+        process_dry_run(
+            version_to_filepath=all_versions,
+            migration_operation=MigrationOperationType.UPGRADE,
+        )

jetbase/core/version.py

@@ -0,0 +1,163 @@
+import os
+
+from jetbase.core.file_parser import is_filename_format_valid, is_filename_length_valid
+
+
+def _get_version_key_from_filename(filename: str) -> str:
+    """
+    Extract and normalize version key from a filename.
+
+    The function extracts the version part from a filename that follows the format:
+    'V{version}__{description}.sql' where version can be like '1', '1_1', or '1.1'.
+
+    Args:
+        filename (str): The filename to extract version from.
+            Must follow pattern like 'V1__description.sql' or 'V1_1__description.sql'
+
+    Returns:
+        str: Normalized version string where underscores are replaced with periods.
+
+    Raises:
+        ValueError: If the filename doesn't follow the expected format.
+
+    Examples:
+        >>> _get_version_key_from_filename("V1__my_description.sql")
+        '1'
+        >>> _get_version_key_from_filename("V1_1__my_description.sql")
+        '1.1'
+        >>> _get_version_key_from_filename("V1.1__my_description.sql")
+        '1.1'
+    """
+    try:
+        version = filename.split("__")[0][1:]
+    except Exception:
+        raise (
+            ValueError(
+                "Filename must be in the following format: V1__my_description.sql, V1_1__my_description.sql, V1.1__my_description.sql"
+            )
+        )
+    return version.replace("_", ".")
+
+
+def _convert_version_tuple_to_str(version_tuple: tuple[str, ...]) -> str:
+    """
+    Convert a version tuple to a string representation.
+
+    Args:
+        version_tuple (tuple[str, ...]): A tuple containing version components as strings.
+
+    Returns:
+        str: A string representation of the version, with components joined by periods.
+
+    Example:
+        >>> _convert_version_tuple_to_str(('1', '2', '3'))
+        '1.2.3'
+    """
+    return ".".join(version_tuple)
+
+
+def convert_version_to_tuple(version: str) -> tuple[str, ...]:
+    """
+    Convert a version string to a tuple of version components.
+
+    Args:
+        version_str (str): A version string with components separated by periods.
+
+    Returns:
+        tuple[str, ...]: A tuple containing the version components as strings.
+
+    Example:
+        >>> convert_version_to_tuple("1.2.3")
+        ('1', '2', '3')
+    """
+    return tuple(version.split("."))
+
+
+def get_migration_filepaths_by_version(
+    directory: str,
+    version_to_start_from: str | None = None,
+    end_version: str | None = None,
+) -> dict[str, str]:
+    """
+    Retrieve migration file paths organized by version number.
+
+    Walks through the specified directory to find SQL migration files and creates
+    a dictionary mapping version strings to their file paths. Files are validated
+    for proper naming format and length. Results can be filtered by version range.
+
+    Args:
+        directory (str): The directory path to search for SQL migration files.
+        version_to_start_from (str | None): Optional minimum version (inclusive).
+            Only files with versions >= this value are included. Defaults to None.
+        end_version (str | None): Optional maximum version (exclusive).
+            Only files with versions < this value are included. Defaults to None.
+
+    Returns:
+        dict[str, str]: Dictionary mapping version strings to file paths,
+            sorted in ascending order by version number.
+
+    Raises:
+        ValueError: If a filename doesn't match the required format or exceeds
+            the maximum length of 512 characters.
+
+    Example:
+        >>> get_migration_filepaths_by_version('/path/to/migrations')
+        {'1.0.0': '/path/to/migrations/V1_0_0__init.sql',
+         '1.2.0': '/path/to/migrations/V1_2_0__add_users.sql'}
+        >>> get_migration_filepaths_by_version('/path/to/migrations', version_to_start_from='1.1.0')
+        {'1.2.0': '/path/to/migrations/V1_2_0__add_users.sql'}
+    """
+    version_to_filepath_dict: dict[str, str] = {}
+
+    for root, _, files in os.walk(directory):
+        for filename in files:
+            if filename.endswith(".sql") and not is_filename_format_valid(
+                filename=filename
+            ):
+                raise ValueError(
+                    f"Invalid migration filename format: {filename}. "
+                    "Filenames must start with 'V', followed by the version number, "
+                    "two underscores '__', a description, and end with '.sql'. "
+                    "V<version_number>__<my_description>.sql. "
+                    "Examples: 'V1_2_0__add_new_table.sql' or 'V1.2.0__add_new_table.sql'"
+                )
+
+            if filename.endswith(".sql") and not is_filename_length_valid(
+                filename=filename
+            ):
+                raise ValueError(
+                    f"Migration filename too long: {filename}. "
+                    f"Filename is currently {len(filename)} characters. "
+                    "Filenames must not exceed 512 characters."
+                )
+
+            if is_filename_format_valid(filename=filename):
+                file_path: str = os.path.join(root, filename)
+                version: str = _get_version_key_from_filename(filename=filename)
+                version_tuple: tuple[str, ...] = convert_version_to_tuple(
+                    version=version
+                )
+
+                if end_version:
+                    if version_tuple > convert_version_to_tuple(version=end_version):
+                        continue
+
+                if version_to_start_from:
+                    if version_tuple >= convert_version_to_tuple(
+                        version=version_to_start_from
+                    ):
+                        version_to_filepath_dict[
+                            _convert_version_tuple_to_str(version_tuple=version_tuple)
+                        ] = file_path
+
+                else:
+                    version_to_filepath_dict[
+                        _convert_version_tuple_to_str(version_tuple=version_tuple)
+                    ] = file_path
+
+    ordered_version_to_filepath_dict: dict[str, str] = {
+        version: version_to_filepath_dict[version]
+        for version in sorted(version_to_filepath_dict.keys())
+    }
+
+    return ordered_version_to_filepath_dict

jetbase/enums.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class MigrationOperationType(Enum):
+    UPGRADE = "upgrade"
+    ROLLBACK = "rollback"

jetbase/queries.py

@@ -0,0 +1,72 @@
+from sqlalchemy import TextClause, text
+
+LATEST_VERSION_QUERY: TextClause = text("""
+    SELECT 
+        version 
+    FROM 
+        jetbase_migrations
+    ORDER BY 
+        applied_at DESC
+    LIMIT 1
+""")
+
+CREATE_MIGRATIONS_TABLE_STMT: TextClause = text("""
+CREATE TABLE IF NOT EXISTS jetbase_migrations (
+    version VARCHAR(255) PRIMARY KEY,
+    description VARCHAR(500),
+    filename VARCHAR(512),
+    order_executed INT GENERATED ALWAYS AS IDENTITY,
+    applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+""")
+
+INSERT_VERSION_STMT: TextClause = text("""
+INSERT INTO jetbase_migrations (version, description, filename) 
+VALUES (:version, :description, :filename)
+""")
+
+DELETE_VERSION_STMT: TextClause = text("""
+DELETE FROM jetbase_migrations 
+WHERE version = :version
+""")
+
+LATEST_VERSIONS_QUERY: TextClause = text("""
+    SELECT 
+        version 
+    FROM 
+        jetbase_migrations
+    ORDER BY 
+        applied_at DESC
+    LIMIT :limit
+""")
+
+LATEST_VERSIONS_BY_STARTING_VERSION_QUERY: TextClause = text("""
+    SELECT
+        version
+    FROM
+        jetbase_migrations
+    WHERE applied_at > 
+        (select applied_at from jetbase_migrations 
+            where version = :starting_version)
+    ORDER BY 
+        applied_at DESC
+""")
+
+CHECK_IF_VERSION_EXISTS_QUERY: TextClause = text("""
+    SELECT 
+        COUNT(*)
+    FROM 
+        jetbase_migrations
+    WHERE 
+        version = :version
+""")
+
+
+CHECK_IF_MIGRATIONS_TABLE_EXISTS_QUERY: TextClause = text("""
+SELECT EXISTS (
+    SELECT 1
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+      AND table_name = 'jetbase_migrations'
+)
+""")

jetbase-0.7.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: jetbase
+Version: 0.7.0
+Summary: Jetbase is a Python database migration tool
+Author-email: jaz <jaz.allibhai@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: sqlalchemy>=2.0.10
+Requires-Dist: typer>=0.12.3
+Description-Content-Type: text/markdown
+
+# jetbase

jetbase-0.7.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+jetbase/config.py,sha256=-YZgS-fVW8k53azx9Ur0GjJvYCZLwOHkguMr_Ujc-mo,1731
+jetbase/constants.py,sha256=X2SYgXRxj77zWB-6N764RQsJmKKUd5Wa7RaQGN6eTiQ,339
+jetbase/enums.py,sha256=LFNZnWcBxvF4kIdZYdGKn2Z65ADHJs38MnGAqeEbZ_U,110
+jetbase/queries.py,sha256=jZ9ei8V-dEb_8ZAwtSAFqLnIEI5rumm3KvQmw4CiZk4,1619
+jetbase/cli/main.py,sha256=I0HIRGC7dmTvEhgdEBksF-p7QPoY4-CfVcm-niVhzck,1504
+jetbase/core/dry_run.py,sha256=zIV4NM_OL-aR7UJlEXYysiGairMOgytnT5rg8baFSms,1469
+jetbase/core/file_parser.py,sha256=Aau7iFaBoZxOgoxB-4C5XAvE_a9142kv7sJHOAANe2A,6069
+jetbase/core/initialize.py,sha256=lm3FWhe1YNKCTmZix465tBGjJsl_YshhRo2ENm7iPFM,955
+jetbase/core/repository.py,sha256=JrmqFkIIbICPsxnY7O3ei9kLL-0mXWFefU0QPHppcgw,5586
+jetbase/core/rollback.py,sha256=e87xlI3WJaOAQD_4QdmeZIDj9a5CW7wKUxQkgIFXy3c,2385
+jetbase/core/upgrade.py,sha256=GowNGAxXRD9dks8FWqSMoQPCMnMh_yP01HNEYB5Py2Q,2603
+jetbase/core/version.py,sha256=mPeJEgcqA0hZMb6YMZQcfc-MGcNI2Ls_7hiH6vJnC1k,6136
+jetbase-0.7.0.dist-info/METADATA,sha256=6vue-I4pBPIQRmMHY3JrxjU7j81fgL6ITMiWcwnmbOs,306
+jetbase-0.7.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+jetbase-0.7.0.dist-info/entry_points.txt,sha256=-Pe7A0r8aGF-6C14hB0Ck8aEuszuH5pdadt5OWSiWwA,50
+jetbase-0.7.0.dist-info/licenses/LICENSE,sha256=hyssQNKtnK32aFCk8mVR406ysMtGNP6_dZCig8zBk4Q,1065
+jetbase-0.7.0.dist-info/RECORD,,

jetbase-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jetbase-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jetbase = jetbase.cli.main:main

jetbase-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jaz-alli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.