starrocks-br 0.5.0__tar.gz → 0.5.1__tar.gz

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starrocks-br
-Version: 0.5.0
+Version: 0.5.1
 Summary: StarRocks Backup and Restore automation tool
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "starrocks-br"
-version = "0.5.0"
+version = "0.5.1"
 description = "StarRocks Backup and Restore automation tool"
 readme = "README.md"
 requires-python = ">=3.10"

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/cli.py

@@ -125,11 +125,14 @@ def init(config):
                 "   starrocks-br backup incremental --group my_daily_incremental --config config.yaml"
             )
 
-    except FileNotFoundError as e:
-        logger.error(f"Config file not found: {e}")
+    except exceptions.ConfigFileNotFoundError as e:
+        error_handler.handle_config_file_not_found_error(e)
         sys.exit(1)
-    except ValueError as e:
-        logger.error(f"Configuration error: {e}")
+    except exceptions.ConfigValidationError as e:
+        error_handler.handle_config_validation_error(e, config)
+        sys.exit(1)
+    except FileNotFoundError as e:
+        error_handler.handle_config_file_not_found_error(exceptions.ConfigFileNotFoundError(str(e)))
         sys.exit(1)
     except Exception as e:
         logger.error(f"Failed to initialize schema: {e}")
@@ -275,14 +278,26 @@ def backup_incremental(config, baseline_backup, group, name):
                 logger.error(f"{result['error_message']}")
                 sys.exit(1)
 
+    except exceptions.ConcurrencyConflictError as e:
+        error_handler.handle_concurrency_conflict_error(e, config)
+        sys.exit(1)
+    except exceptions.BackupLabelNotFoundError as e:
+        error_handler.handle_backup_label_not_found_error(e, config)
+        sys.exit(1)
+    except exceptions.NoFullBackupFoundError as e:
+        error_handler.handle_no_full_backup_found_error(e, config, group)
+        sys.exit(1)
+    except exceptions.ConfigFileNotFoundError as e:
+        error_handler.handle_config_file_not_found_error(e)
+        sys.exit(1)
+    except exceptions.ConfigValidationError as e:
+        error_handler.handle_config_validation_error(e, config)
+        sys.exit(1)
     except FileNotFoundError as e:
-        logger.error(f"Config file not found: {e}")
+        error_handler.handle_config_file_not_found_error(exceptions.ConfigFileNotFoundError(str(e)))
         sys.exit(1)
     except ValueError as e:
-        logger.error(f"Configuration error: {e}")
-        sys.exit(1)
-    except RuntimeError as e:
-        logger.error(f"{e}")
+        logger.error(f"Error: {e}")
         sys.exit(1)
     except Exception as e:
         logger.error(f"Unexpected error: {e}")
@@ -394,15 +409,23 @@ def backup_full(config, group, name):
                 logger.error(f"{result['error_message']}")
                 sys.exit(1)
 
-    except (FileNotFoundError, ValueError, RuntimeError, Exception) as e:
-        if isinstance(e, FileNotFoundError):
-            logger.error(f"Config file not found: {e}")
-        elif isinstance(e, ValueError):
-            logger.error(f"Configuration error: {e}")
-        elif isinstance(e, RuntimeError):
-            logger.error(f"{e}")
-        else:
-            logger.error(f"Unexpected error: {e}")
+    except exceptions.ConcurrencyConflictError as e:
+        error_handler.handle_concurrency_conflict_error(e, config)
+        sys.exit(1)
+    except exceptions.ConfigFileNotFoundError as e:
+        error_handler.handle_config_file_not_found_error(e)
+        sys.exit(1)
+    except exceptions.ConfigValidationError as e:
+        error_handler.handle_config_validation_error(e, config)
+        sys.exit(1)
+    except FileNotFoundError as e:
+        error_handler.handle_config_file_not_found_error(exceptions.ConfigFileNotFoundError(str(e)))
+        sys.exit(1)
+    except ValueError as e:
+        logger.error(f"Error: {e}")
+        sys.exit(1)
+    except Exception as e:
+        logger.error(f"Unexpected error: {e}")
         sys.exit(1)
 
 
@@ -559,8 +582,8 @@ def restore_command(config, target_label, group, table, rename_suffix, yes):
             exceptions.ConfigValidationError(str(e)), config
         )
         sys.exit(1)
-    except RuntimeError as e:
-        logger.error(f"{e}")
+    except exceptions.ConcurrencyConflictError as e:
+        error_handler.handle_concurrency_conflict_error(e, config)
         sys.exit(1)
     except Exception as e:
         logger.error(f"Unexpected error: {e}")

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/concurrency.py

@@ -1,6 +1,6 @@
 from typing import Literal
 
-from . import logger, utils
+from . import exceptions, logger, utils
 
 
 def reserve_job_slot(db, scope: str, label: str) -> None:
@@ -46,14 +46,7 @@ def _can_heal_stale_job(scope: str, label: str, db) -> bool:
 
 def _raise_concurrency_conflict(scope: str, active_jobs: list[tuple[str, str, str]]) -> None:
     """Raise a concurrency conflict error with helpful message."""
-    active_job_strings = [f"{job[0]}:{job[1]}" for job in active_jobs]
-    active_labels = [job[1] for job in active_jobs]
-
-    raise RuntimeError(
-        f"Concurrency conflict: Another '{scope}' job is already ACTIVE: {', '.join(active_job_strings)}. "
-        f"Wait for it to complete or cancel it via: UPDATE ops.run_status SET state='CANCELLED' "
-        f"WHERE label='{active_labels[0]}' AND state='ACTIVE'"
-    )
+    raise exceptions.ConcurrencyConflictError(scope, active_jobs)
 
 
 def _insert_new_job(db, scope: str, label: str) -> None:

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/config.py

@@ -2,6 +2,8 @@ from typing import Any
 
 import yaml
 
+from . import exceptions
+
 
 def load_config(config_path: str) -> dict[str, Any]:
     """Load and parse YAML configuration file.
@@ -20,7 +22,7 @@ def load_config(config_path: str) -> dict[str, Any]:
         config = yaml.safe_load(f)
 
     if not isinstance(config, dict):
-        raise ValueError("Config must be a dictionary")
+        raise exceptions.ConfigValidationError("Config must be a dictionary")
 
     return config
 
@@ -32,13 +34,13 @@ def validate_config(config: dict[str, Any]) -> None:
         config: Configuration dictionary
 
     Raises:
-        ValueError: If required fields are missing
+        ConfigValidationError: If required fields are missing
     """
     required_fields = ["host", "port", "user", "database", "repository"]
 
     for field in required_fields:
         if field not in config:
-            raise ValueError(f"Missing required config field: {field}")
+            raise exceptions.ConfigValidationError(f"Missing required config field: {field}")
 
     _validate_tls_section(config.get("tls"))
 
@@ -48,17 +50,19 @@ def _validate_tls_section(tls_config) -> None:
         return
 
     if not isinstance(tls_config, dict):
-        raise ValueError("TLS configuration must be a dictionary")
+        raise exceptions.ConfigValidationError("TLS configuration must be a dictionary")
 
     enabled = bool(tls_config.get("enabled", False))
 
     if enabled and not tls_config.get("ca_cert"):
-        raise ValueError("TLS configuration requires 'ca_cert' when 'enabled' is true")
+        raise exceptions.ConfigValidationError(
+            "TLS configuration requires 'ca_cert' when 'enabled' is true"
+        )
 
     if "verify_server_cert" in tls_config and not isinstance(
         tls_config["verify_server_cert"], bool
     ):
-        raise ValueError(
+        raise exceptions.ConfigValidationError(
             "TLS configuration field 'verify_server_cert' must be a boolean if provided"
         )
 
@@ -67,6 +71,6 @@ def _validate_tls_section(tls_config) -> None:
         if not isinstance(tls_versions, list) or not all(
             isinstance(version, str) for version in tls_versions
         ):
-            raise ValueError(
+            raise exceptions.ConfigValidationError(
                 "TLS configuration field 'tls_versions' must be a list of strings if provided"
             )

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/error_handler.py

@@ -263,3 +263,45 @@ def handle_restore_operation_cancelled_error() -> None:
         ],
         help_links=["starrocks-br restore --help"],
     )
+
+
+def handle_concurrency_conflict_error(
+    exc: exceptions.ConcurrencyConflictError, config: str = None
+) -> None:
+    active_job_strings = [f"{job[0]}:{job[1]}" for job in exc.active_jobs]
+    first_label = exc.active_labels[0] if exc.active_labels else "unknown"
+
+    display_structured_error(
+        title="CONCURRENCY CONFLICT",
+        reason=f"Another '{exc.scope}' job is already running.\nOnly one job of the same type can run at a time to prevent conflicts.",
+        what_to_do=[
+            f"Wait for the active job to complete: {', '.join(active_job_strings)}",
+            f"Check the job status in ops.run_status:\n     SELECT * FROM ops.run_status WHERE label = '{first_label}' AND state = 'ACTIVE';",
+            f"If the job is stuck, cancel it manually:\n     UPDATE ops.run_status SET state = 'CANCELLED' WHERE label = '{first_label}' AND state = 'ACTIVE';",
+            "Verify the job is not actually running in StarRocks before cancelling it",
+        ],
+        inputs={
+            "--config": config,
+            "Scope": exc.scope,
+            "Active jobs": ", ".join(active_job_strings),
+        },
+        help_links=["Check ops.run_status table for job status"],
+    )
+
+
+def handle_no_full_backup_found_error(
+    exc: exceptions.NoFullBackupFoundError, config: str = None, group: str = None
+) -> None:
+    display_structured_error(
+        title="NO FULL BACKUP FOUND",
+        reason=f"No successful full backup was found for database '{exc.database}'.\nIncremental backups require a baseline full backup to compare against.",
+        what_to_do=[
+            "Run a full backup first:\n     starrocks-br backup full --config "
+            + (config if config else "<config.yaml>")
+            + f" --group {group if group else '<group_name>'}",
+            f"Verify no full backups exist for this database:\n     SELECT label, backup_type, status, finished_at FROM ops.backup_history WHERE backup_type = 'full' AND label LIKE '{exc.database}_%' ORDER BY finished_at DESC;",
+            "After the full backup completes successfully, retry the incremental backup",
+        ],
+        inputs={"Database": exc.database, "--config": config, "--group": group},
+        help_links=["starrocks-br backup full --help"],
+    )

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/exceptions.py

@@ -91,3 +91,19 @@ class NoTablesFoundError(StarRocksBRError):
 class RestoreOperationCancelledError(StarRocksBRError):
     def __init__(self):
         super().__init__("Restore operation cancelled by user")
+
+
+class ConcurrencyConflictError(StarRocksBRError):
+    def __init__(self, scope: str, active_jobs: list[tuple[str, str, str]]):
+        self.scope = scope
+        self.active_jobs = active_jobs
+        self.active_labels = [job[1] for job in active_jobs]
+        super().__init__(
+            f"Concurrency conflict: Another '{scope}' job is already active: {', '.join(f'{job[0]}:{job[1]}' for job in active_jobs)}"
+        )
+
+
+class NoFullBackupFoundError(StarRocksBRError):
+    def __init__(self, database: str):
+        self.database = database
+        super().__init__(f"No successful full backup found for database '{database}'")

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br/planner.py

@@ -1,7 +1,7 @@
 import datetime
 import hashlib
 
-from starrocks_br import logger, timezone, utils
+from starrocks_br import exceptions, logger, timezone, utils
 
 
 def find_latest_full_backup(db, database: str) -> dict[str, str] | None:
@@ -83,16 +83,12 @@ def find_recent_partitions(
         """
         baseline_rows = db.query(baseline_query)
         if not baseline_rows:
-            raise ValueError(
-                f"Baseline backup '{baseline_backup_label}' not found or not successful"
-            )
+            raise exceptions.BackupLabelNotFoundError(baseline_backup_label)
         baseline_time_raw = baseline_rows[0][0]
     else:
         latest_backup = find_latest_full_backup(db, database)
         if not latest_backup:
-            raise ValueError(
-                f"No successful full backup found for database '{database}'. Run a full database backup first."
-            )
+            raise exceptions.NoFullBackupFoundError(database)
         baseline_time_raw = latest_backup["finished_at"]
 
     if isinstance(baseline_time_raw, datetime.datetime):

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starrocks-br
-Version: 0.5.0
+Version: 0.5.1
 Summary: StarRocks Backup and Restore automation tool
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{starrocks_br-0.5.0 → starrocks_br-0.5.1}/src/starrocks_br.egg-info/SOURCES.txt

@@ -24,7 +24,11 @@ src/starrocks_br.egg-info/dependency_links.txt
 src/starrocks_br.egg-info/entry_points.txt
 src/starrocks_br.egg-info/requires.txt
 src/starrocks_br.egg-info/top_level.txt
-tests/test_cli.py
+tests/test_cli_backup.py
+tests/test_cli_exceptions.py
+tests/test_cli_general.py
+tests/test_cli_init.py
+tests/test_cli_restore.py
 tests/test_concurrency.py
 tests/test_config.py
 tests/test_db.py

starrocks_br-0.5.1/tests/test_cli_backup.py

@@ -0,0 +1,205 @@
+from click.testing import CliRunner
+
+from starrocks_br import cli
+
+
+def test_backup_incremental_success(
+    config_file,
+    mock_db,
+    mock_initialized_schema,
+    mock_healthy_cluster,
+    mock_repo_exists,
+    setup_password_env,
+    mocker,
+):
+    """Test successful incremental backup with default baseline (latest full backup)."""
+    runner = CliRunner()
+
+    mocker.patch(
+        "starrocks_br.planner.find_latest_full_backup",
+        return_value={
+            "label": "test_db_20251015_full",
+            "backup_type": "full",
+            "finished_at": "2025-10-15 10:00:00",
+        },
+    )
+    mocker.patch(
+        "starrocks_br.planner.find_recent_partitions",
+        return_value=[
+            {"database": "test_db", "table": "fact_table", "partition_name": "p20251016"}
+        ],
+    )
+    mocker.patch("starrocks_br.labels.determine_backup_label", return_value="test_db_20251016_inc")
+    mocker.patch(
+        "starrocks_br.planner.build_incremental_backup_command",
+        return_value="BACKUP DATABASE test_db SNAPSHOT test_db_20251016_inc TO test_repo",
+    )
+    mocker.patch("starrocks_br.concurrency.reserve_job_slot")
+    mocker.patch("starrocks_br.planner.record_backup_partitions")
+    mocker.patch(
+        "starrocks_br.executor.execute_backup",
+        return_value={
+            "success": True,
+            "final_status": {"state": "FINISHED"},
+            "error_message": None,
+        },
+    )
+
+    result = runner.invoke(
+        cli.backup_incremental, ["--config", config_file, "--group", "daily_incremental"]
+    )
+
+    assert result.exit_code == 0
+    assert "Backup completed successfully" in result.output
+    assert "Using latest full backup as baseline: test_db_20251015_full (full)" in result.output
+
+
+def test_backup_incremental_with_specific_baseline(
+    config_file,
+    mock_db,
+    mock_initialized_schema,
+    mock_healthy_cluster,
+    mock_repo_exists,
+    setup_password_env,
+    mocker,
+):
+    """Test incremental backup with user-specified baseline."""
+    runner = CliRunner()
+
+    mocker.patch(
+        "starrocks_br.planner.find_recent_partitions",
+        return_value=[
+            {"database": "test_db", "table": "fact_table", "partition_name": "p20251016"}
+        ],
+    )
+    mocker.patch("starrocks_br.labels.determine_backup_label", return_value="test_db_20251016_inc")
+    mocker.patch(
+        "starrocks_br.planner.build_incremental_backup_command",
+        return_value="BACKUP DATABASE test_db SNAPSHOT test_db_20251016_inc TO test_repo",
+    )
+    mocker.patch("starrocks_br.concurrency.reserve_job_slot")
+    mocker.patch("starrocks_br.planner.record_backup_partitions")
+    mocker.patch(
+        "starrocks_br.executor.execute_backup",
+        return_value={
+            "success": True,
+            "final_status": {"state": "FINISHED"},
+            "error_message": None,
+        },
+    )
+
+    result = runner.invoke(
+        cli.backup_incremental,
+        [
+            "--config",
+            config_file,
+            "--baseline-backup",
+            "test_db_20251010_full",
+            "--group",
+            "daily_incremental",
+        ],
+    )
+
+    assert result.exit_code == 0
+    assert "Backup completed successfully" in result.output
+    assert "Using specified baseline backup: test_db_20251010_full" in result.output
+
+
+def test_backup_full_success(
+    config_file,
+    mock_db,
+    mock_initialized_schema,
+    mock_healthy_cluster,
+    mock_repo_exists,
+    setup_password_env,
+    mocker,
+):
+    """Test successful full backup."""
+    runner = CliRunner()
+
+    mocker.patch(
+        "starrocks_br.planner.build_full_backup_command",
+        return_value="BACKUP DATABASE test_db SNAPSHOT test_db_20251016_full TO test_repo",
+    )
+    mocker.patch(
+        "starrocks_br.planner.find_tables_by_group",
+        return_value=[{"database": "test_db", "table": "dim_customers"}],
+    )
+    mocker.patch("starrocks_br.planner.get_all_partitions_for_tables", return_value=[])
+    mocker.patch("starrocks_br.labels.determine_backup_label", return_value="test_db_20251016_full")
+    mocker.patch("starrocks_br.concurrency.reserve_job_slot")
+    mocker.patch("starrocks_br.planner.record_backup_partitions")
+    mocker.patch(
+        "starrocks_br.executor.execute_backup",
+        return_value={
+            "success": True,
+            "final_status": {"state": "FINISHED"},
+            "error_message": None,
+        },
+    )
+
+    result = runner.invoke(
+        cli.backup_full, ["--config", config_file, "--group", "weekly_dimensions"]
+    )
+
+    assert result.exit_code == 0
+    assert "Backup completed successfully" in result.output
+
+
+def test_backup_reserves_slot_before_recording_partitions(
+    config_file,
+    mock_db,
+    mock_initialized_schema,
+    mock_healthy_cluster,
+    mock_repo_exists,
+    setup_password_env,
+    mocker,
+):
+    """Test that backup reserves job slot before recording partitions (correct order)."""
+    runner = CliRunner()
+    call_order = []
+
+    def mock_reserve_job_slot(*args, **kwargs):
+        call_order.append("reserve_job_slot")
+
+    def mock_record_backup_partitions(*args, **kwargs):
+        call_order.append("record_backup_partitions")
+
+    mocker.patch("starrocks_br.labels.determine_backup_label", return_value="test_backup")
+    mocker.patch(
+        "starrocks_br.planner.find_latest_full_backup",
+        return_value={
+            "label": "test_db_20251015_full",
+            "backup_type": "full",
+            "finished_at": "2025-10-15 10:00:00",
+        },
+    )
+    mocker.patch(
+        "starrocks_br.planner.find_recent_partitions",
+        return_value=[
+            {"database": "test_db", "table": "fact_table", "partition_name": "p20251016"}
+        ],
+    )
+    mocker.patch(
+        "starrocks_br.planner.build_incremental_backup_command",
+        return_value="BACKUP DATABASE test_db SNAPSHOT test_backup TO test_repo",
+    )
+    mocker.patch("starrocks_br.concurrency.reserve_job_slot", side_effect=mock_reserve_job_slot)
+    mocker.patch(
+        "starrocks_br.planner.record_backup_partitions", side_effect=mock_record_backup_partitions
+    )
+    mocker.patch(
+        "starrocks_br.executor.execute_backup",
+        return_value={
+            "success": True,
+            "final_status": {"state": "FINISHED"},
+            "error_message": None,
+        },
+    )
+
+    result = runner.invoke(cli.backup_incremental, ["--config", config_file, "--group", "daily"])
+
+    assert result.exit_code == 0
+    assert len(call_order) == 2
+    assert call_order[0] == "reserve_job_slot"
+    assert call_order[1] == "record_backup_partitions"