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

jetbase/database/queries/sqlite.py

@@ -0,0 +1,197 @@
+from sqlalchemy import TextClause, text
+
+from jetbase.database.queries.base import BaseQueries
+
+
+class SQLiteQueries(BaseQueries):
+    """
+    SQLite-specific SQL queries.
+
+    Provides SQLite-compatible implementations for queries that differ
+    from the default PostgreSQL syntax.
+    """
+
+    @staticmethod
+    def create_migrations_table_stmt() -> TextClause:
+        """
+        Get SQLite statement to create the jetbase_migrations table.
+
+        Uses INTEGER PRIMARY KEY AUTOINCREMENT and TEXT types for
+        SQLite compatibility.
+
+        Returns:
+            TextClause: SQLAlchemy text clause for the CREATE TABLE statement.
+        """
+        return text(
+            """
+        CREATE TABLE IF NOT EXISTS jetbase_migrations (
+            order_executed INTEGER PRIMARY KEY AUTOINCREMENT,
+            version TEXT,
+            description TEXT,
+            filename TEXT NOT NULL,
+            migration_type TEXT NOT NULL,
+            applied_at TEXT DEFAULT (STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+            checksum TEXT
+        );
+        """
+        )
+
+    @staticmethod
+    def check_if_migrations_table_exists_query() -> TextClause:
+        """
+        Get SQLite query to check if the jetbase_migrations table exists.
+
+        Uses sqlite_master to check for table existence.
+
+        Returns:
+            TextClause: SQLAlchemy text clause that returns a boolean.
+        """
+        return text(
+            """
+        SELECT COUNT(*) > 0
+            FROM sqlite_master
+            WHERE type = 'table'
+              AND name = 'jetbase_migrations'
+        """
+        )
+
+    @staticmethod
+    def check_if_lock_table_exists_query() -> TextClause:
+        """
+        Get SQLite query to check if the jetbase_lock table exists.
+
+        Uses sqlite_master to check for table existence.
+
+        Returns:
+            TextClause: SQLAlchemy text clause that returns the table name
+                if it exists.
+        """
+        return text(
+            """
+        SELECT name FROM sqlite_master 
+        WHERE type='table' AND name='jetbase_lock'
+        """
+        )
+
+    @staticmethod
+    def create_lock_table_stmt() -> TextClause:
+        """
+        Get SQLite statement to create the jetbase_lock table.
+
+        Uses CHECK constraint to ensure only one row exists, and
+        TEXT type for timestamp storage.
+
+        Returns:
+            TextClause: SQLAlchemy text clause for the CREATE TABLE statement.
+        """
+        return text(
+            """
+        CREATE TABLE IF NOT EXISTS jetbase_lock (
+            id INTEGER PRIMARY KEY CHECK (id = 1),
+            is_locked BOOLEAN NOT NULL DEFAULT 0,
+            locked_at TEXT DEFAULT (STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')),
+            process_id TEXT
+        );
+        """
+        )
+
+    @staticmethod
+    def force_unlock_stmt() -> TextClause:
+        """
+        Get SQLite statement to force release the migration lock.
+
+        Sets is_locked to 0 and clears the locked_at and process_id fields.
+
+        Returns:
+            TextClause: SQLAlchemy text clause for the UPDATE statement.
+        """
+        return text(
+            """
+        UPDATE jetbase_lock
+        SET is_locked = 0,
+            locked_at = NULL,
+            process_id = NULL
+        WHERE id = 1;
+        """
+        )
+
+    @staticmethod
+    def initialize_lock_record_stmt() -> TextClause:
+        """
+        Get SQLite statement to initialize the lock record.
+
+        Uses INSERT OR IGNORE to create the initial unlocked record
+        without failing if it already exists.
+
+        Returns:
+            TextClause: SQLAlchemy text clause for the INSERT statement.
+        """
+        return text(
+            """
+        INSERT OR IGNORE INTO jetbase_lock (id, is_locked)
+        VALUES (1, 0)
+        """
+        )
+
+    @staticmethod
+    def acquire_lock_stmt() -> TextClause:
+        """
+        Get SQLite statement to atomically acquire the migration lock.
+
+        Only updates if the lock is not currently held. Uses STRFTIME
+        for timestamp generation.
+
+        Returns:
+            TextClause: SQLAlchemy text clause with :process_id parameter.
+        """
+        return text(
+            """
+        UPDATE jetbase_lock
+        SET is_locked = 1,
+            locked_at = STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW'),
+            process_id = :process_id
+        WHERE id = 1 AND is_locked = 0
+        """
+        )
+
+    @staticmethod
+    def release_lock_stmt() -> TextClause:
+        """
+        Get SQLite statement to release the migration lock.
+
+        Only releases if the lock is held by the specified process ID.
+
+        Returns:
+            TextClause: SQLAlchemy text clause with :process_id parameter.
+        """
+        return text(
+            """
+        UPDATE jetbase_lock
+        SET is_locked = 0,
+            locked_at = NULL,
+            process_id = NULL
+        WHERE id = 1 AND process_id = :process_id
+        """
+        )
+
+    @staticmethod
+    def update_repeatable_migration_stmt() -> TextClause:
+        """
+        Get SQLite statement to update a repeatable migration record.
+
+        Updates the checksum and applied_at timestamp using SQLite's
+        STRFTIME function for the current time.
+
+        Returns:
+            TextClause: SQLAlchemy text clause with :checksum, :filename,
+                and :migration_type parameters.
+        """
+        return text(
+            """
+        UPDATE jetbase_migrations
+        SET checksum = :checksum,
+            applied_at = STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')
+        WHERE filename = :filename
+        AND migration_type = :migration_type
+        """
+        )

jetbase/engine/checksum.py

@@ -0,0 +1,25 @@
+import hashlib
+
+
+def calculate_checksum(sql_statements: list[str]) -> str:
+    """
+    Calculate SHA256 checksum for a list of SQL statements.
+
+    Joins all statements with newlines and computes a SHA256 hash to create
+    a unique fingerprint of the migration content.
+
+    Args:
+        sql_statements (list[str]): List of SQL statements to hash.
+
+    Returns:
+        str: 64-character hexadecimal SHA256 checksum string.
+
+    Example:
+        >>> calculate_checksum(["SELECT 1", "SELECT 2"])
+        'a1b2c3d4e5f6...'
+    """
+    formatted_sql_statements: str = "\n".join(sql_statements)
+
+    checksum: str = hashlib.sha256(formatted_sql_statements.encode("utf-8")).hexdigest()
+
+    return checksum

jetbase/engine/dry_run.py

@@ -0,0 +1,105 @@
+import os
+
+from jetbase.engine.file_parser import (
+    parse_rollback_statements,
+    parse_upgrade_statements,
+)
+from jetbase.enums import MigrationDirectionType
+
+
+def process_dry_run(
+    version_to_filepath: dict[str, str],
+    migration_operation: MigrationDirectionType,
+    repeatable_always_filepaths: list[str] | None = None,
+    runs_on_change_filepaths: list[str] | None = None,
+) -> None:
+    """
+    Preview migrations without executing them.
+
+    Parses and displays the SQL statements that would be executed for
+    each migration, without actually running them against the database.
+
+    Args:
+        version_to_filepath (dict[str, str]): Mapping of version strings
+            to migration file paths for versioned migrations.
+        migration_operation (MigrationDirectionType): Whether this is an
+            UPGRADE or ROLLBACK operation.
+        repeatable_always_filepaths (list[str] | None): File paths for
+            runs-always migrations. Defaults to None.
+        runs_on_change_filepaths (list[str] | None): File paths for
+            runs-on-change migrations. Defaults to None.
+
+    Returns:
+        None: Prints SQL preview to stdout.
+
+    Raises:
+        NotImplementedError: If migration_operation is not UPGRADE or ROLLBACK.
+    """
+    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 == MigrationDirectionType.UPGRADE:
+            sql_statements: list[str] = parse_upgrade_statements(
+                file_path=file_path, dry_run=True
+            )
+        elif migration_operation == MigrationDirectionType.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)
+
+        print_migration_preview(
+            filename=filename,
+            sql_statements=sql_statements,
+        )
+
+    if migration_operation == MigrationDirectionType.UPGRADE:
+        if repeatable_always_filepaths:
+            for filepath in repeatable_always_filepaths:
+                sql_statements: list[str] = parse_upgrade_statements(
+                    file_path=filepath, dry_run=True
+                )
+                filename: str = os.path.basename(filepath)
+
+                print_migration_preview(
+                    filename=filename, sql_statements=sql_statements
+                )
+
+        if runs_on_change_filepaths:
+            for filepath in runs_on_change_filepaths:
+                sql_statements: list[str] = parse_upgrade_statements(
+                    file_path=filepath, dry_run=True
+                )
+
+                print_migration_preview(
+                    filename=os.path.basename(filepath), sql_statements=sql_statements
+                )
+
+
+def print_migration_preview(filename: str, sql_statements: list[str]) -> None:
+    """
+    Print SQL statements for a migration file preview.
+
+    Displays the filename, statement count, and full SQL content for
+    each statement in a formatted output.
+
+    Args:
+        filename (str): The name of the migration file being previewed.
+        sql_statements (list[str]): List of SQL statements to display.
+
+    Returns:
+        None: Prints formatted preview to stdout.
+    """
+    print(
+        f"SQL Preview for {filename} ({len(sql_statements)} {'statements' if len(sql_statements) != 1 else 'statement'})\n"
+    )
+    for statement in sql_statements:
+        print(f"{statement}\n")
+    print("----------------------------------------\n")

jetbase/engine/file_parser.py

@@ -0,0 +1,324 @@
+import re
+
+from jetbase.constants import (
+    RUNS_ALWAYS_FILE_PREFIX,
+    RUNS_ON_CHANGE_FILE_PREFIX,
+    VERSION_FILE_PREFIX,
+)
+from jetbase.enums import MigrationDirectionType
+from jetbase.exceptions import (
+    InvalidMigrationFilenameError,
+    MigrationFilenameTooLongError,
+)
+
+
+def parse_upgrade_statements(file_path: str, dry_run: bool = False) -> list[str]:
+    """
+    Parse SQL statements from the upgrade section of a migration file.
+
+    Reads the migration file and extracts all SQL statements that appear
+    before the '-- rollback' marker. Statements are split on semicolons.
+
+    Args:
+        file_path (str): Path to the migration SQL file.
+        dry_run (bool): If True, preserves formatting for display.
+            If False, joins lines for execution. Defaults to False.
+
+    Returns:
+        list[str]: List of SQL statements.
+    """
+    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() == MigrationDirectionType.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]:
+    """
+    Parse SQL statements from the rollback section of a migration file.
+
+    Reads the migration file and extracts all SQL statements that appear
+    after the '-- rollback' marker. Statements are split on semicolons.
+
+    Args:
+        file_path (str): Path to the migration SQL file.
+        dry_run (bool): If True, preserves formatting for display.
+            If False, joins lines for execution. Defaults to False.
+
+    Returns:
+        list[str]: List of SQL statements (without trailing semicolons).
+    """
+    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()
+                    == MigrationDirectionType.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:
+    """
+    Check if filename follows the migration naming convention.
+
+    Valid filenames must start with 'V', 'RA__', or 'ROC__', contain '__',
+    end with '.sql', and have a non-empty description.
+
+    Args:
+        filename (str): The filename to validate.
+
+    Returns:
+        bool: True if the filename matches the convention, False otherwise.
+
+    Example:
+        >>> is_filename_format_valid("V1__init.sql")
+        True
+        >>> is_filename_format_valid("invalid.sql")
+        False
+    """
+    if not filename.endswith(".sql"):
+        return False
+    if not filename.startswith(
+        (VERSION_FILE_PREFIX, RUNS_ON_CHANGE_FILE_PREFIX, RUNS_ALWAYS_FILE_PREFIX)
+    ):
+        return False
+    if "__" not in filename:
+        return False
+    description: str = _get_raw_description_from_filename(filename=filename)
+    if len(description.strip()) == 0:
+        return False
+    if filename.startswith((RUNS_ON_CHANGE_FILE_PREFIX, RUNS_ALWAYS_FILE_PREFIX)):
+        return True
+    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.
+
+    Extracts the portion after '__' and before '.sql', then replaces
+    underscores with spaces for human-readable display.
+
+    Args:
+        filename (str): The migration filename to parse.
+
+    Returns:
+        str: Human-readable description with spaces.
+
+    Example:
+        >>> get_description_from_filename("V1__add_users.sql")
+        'add users'
+    """
+
+    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 allowed maximum.
+
+    Args:
+        filename (str): The filename to check.
+        max_length (int): Maximum allowed character length. Defaults to 512.
+
+    Returns:
+        bool: True if the filename length is <= max_length.
+    """
+    return len(filename) <= max_length
+
+
+def _get_version_from_filename(filename: str) -> str:
+    """
+    Extract the version string from a migration filename.
+
+    Parses the portion between 'V' and '__' to get the raw version.
+
+    Args:
+        filename (str): The migration filename to parse.
+
+    Returns:
+        str: Raw version string (e.g., "1_2_0" from "V1_2_0__desc.sql").
+    """
+
+    version: str = filename[1 : filename.index("__")]
+    return version
+
+
+def _get_raw_description_from_filename(filename: str) -> str:
+    """
+    Extract the raw description from a migration filename.
+
+    Returns the portion between '__' and '.sql' without any formatting.
+
+    Args:
+        filename (str): The migration filename to parse.
+
+    Returns:
+        str: Raw description with underscores preserved.
+    """
+
+    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.
+
+    Valid versions contain digits separated by periods or underscores.
+    Must start and end with a digit.
+
+    Args:
+        version (str): The version string to validate.
+
+    Returns:
+        bool: True if the version format is valid.
+
+    Example:
+        >>> _is_valid_version("1.2.3")
+        True
+        >>> _is_valid_version("1__2")
+        False
+    """
+    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))
+
+
+def validate_filename_format(filename: str) -> None:
+    """
+    Validate filename format, raising an exception if invalid.
+
+    Checks that the filename follows the migration naming convention
+    and does not exceed the maximum length.
+
+    Args:
+        filename (str): The filename to validate.
+
+    Returns:
+        None: Returns silently if validation passes.
+
+    Raises:
+        InvalidMigrationFilenameError: If the filename doesn't match
+            the required naming convention.
+        MigrationFilenameTooLongError: If the filename exceeds 512 characters.
+    """
+    is_valid_filename: bool = True
+    if not filename.endswith(".sql"):
+        is_valid_filename = False
+    if not filename.startswith(
+        (VERSION_FILE_PREFIX, RUNS_ON_CHANGE_FILE_PREFIX, RUNS_ALWAYS_FILE_PREFIX)
+    ):
+        is_valid_filename = False
+    if "__" not in filename:
+        is_valid_filename = False
+    description: str = _get_raw_description_from_filename(filename=filename)
+    if len(description.strip()) == 0:
+        is_valid_filename = False
+    if filename.startswith(VERSION_FILE_PREFIX):
+        raw_version: str = _get_version_from_filename(filename=filename)
+        if not _is_valid_version(version=raw_version):
+            is_valid_filename = False
+
+    if not is_valid_filename:
+        raise InvalidMigrationFilenameError(
+            f"Invalid migration filename format: {filename}.\n"
+            "Filenames must start with 'V', followed by the version number, "
+            "two underscores '__', a description, and end with '.sql'.\n"
+            "V<version_number>__<my_description>.sql. "
+            "Examples: 'V1_2_0__add_new_table.sql' or 'V1.2.0__add_new_table.sql'\n\n"
+            "For repeatable migrations, filenames must start with 'RC' or 'RA', "
+            "followed by two underscores '__', a description, and end with '.sql'.\n"
+            "RC__<my_description>.sql or RA__<my_description>.sql."
+        )
+
+    _validate_filename_length(filename=filename)
+
+
+def _validate_filename_length(filename: str, max_length: int = 512) -> None:
+    """
+    Validate that the filename does not exceed the maximum length.
+
+    Args:
+        filename (str): The filename to validate.
+        max_length (int): Maximum allowed character length. Defaults to 512.
+
+    Returns:
+        None: Returns silently if validation passes.
+
+    Raises:
+        MigrationFilenameTooLongError: If the filename exceeds max_length.
+    """
+    if len(filename) > max_length:
+        raise MigrationFilenameTooLongError(
+            f"Migration filename too long: {filename}.\n"
+            f"Filename is currently {len(filename)} characters.\n"
+            "Filenames must not exceed 512 characters."
+        )