starrocks-br 0.5.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

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/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/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/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/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/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.dist-info → starrocks_br-0.5.1.dist-info}/METADATA

@@ -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.dist-info → starrocks_br-0.5.1.dist-info}/RECORD

@@ -1,23 +1,23 @@
 starrocks_br/__init__.py,sha256=i1m0FIl2IAXaVyNoya0ZNAx3WfhIp9I6VLhTz06qNFY,28
-starrocks_br/cli.py,sha256=fMtTLGFgEfM1HkXX5y0IVmTC6yCcGLfYnoA8G-qPWCs,21686
-starrocks_br/concurrency.py,sha256=N0LD4VHTAFNhD4YslrkOCDSx5cnR5rCEkNH9MkODxv8,5903
-starrocks_br/config.py,sha256=APqOZcJuUzYmGNHoJRlsu4l3sWl_4SS1kRLKjKm2Oag,2059
+starrocks_br/cli.py,sha256=rTqKP4gSkMhX4rgAOhvDFZfwJQB7USRV9uYrDvJ-58c,22924
+starrocks_br/concurrency.py,sha256=uj5s5wR5ixa3XIdrwLiy7ootc71mMg3F1Uw-t0w16Ik,5558
+starrocks_br/config.py,sha256=VrNXy_YxqiRJ3vDUGzRStZFM5ttK-q5EN_JdNiDiNJ0,2250
 starrocks_br/db.py,sha256=47ynDQ9kdykJRj_nrHxX020b9njozzQxiZBI9lFdS7A,4946
-starrocks_br/error_handler.py,sha256=qqN3Ht2YCHMzvnP_snPIPJuZPKxvgrHSt2qlVfItBY8,10830
-starrocks_br/exceptions.py,sha256=vStzFWxDpO6krg1l-_6IxrXNKI8jc0aYSs7GiVsDze8,3273
+starrocks_br/error_handler.py,sha256=j9UW4vh7PaQW5tSi1YP-SqGuD420cCWo2-eFrkewCoU,13085
+starrocks_br/exceptions.py,sha256=0KFwLKrNS4UGGvhc-54HncL6BX-wc6XnNVBvl8nYEus,3909
 starrocks_br/executor.py,sha256=YE12jiU-4tru2D7BAe8Y0Fom72LHjGz04obN4FcAWhA,11345
 starrocks_br/health.py,sha256=rmkgNYf6kk3VDZx-PmnAG3lzmtvnJcUPG7Ppb6BA7IU,1021
 starrocks_br/history.py,sha256=ewXMVUHJvpWjvPndYUdz9xPh24HDPiUAuJgIALuWays,2964
 starrocks_br/labels.py,sha256=07UFd8BMyyV2MQwf7NaLviuu37lMLOOFX3DCbf_XqOE,1662
 starrocks_br/logger.py,sha256=8F7ZnqCOVFJDt6-rZevh94udGbhZhDLrBw8W3RZbM-4,1432
-starrocks_br/planner.py,sha256=wbOTKZvuWAFaGWXcciKOIveLzfYWsnGXK1ZI4lr7MVU,10892
+starrocks_br/planner.py,sha256=qk-T6SZmNzztrXwyS1jjwL1kSS_l6MRo3TNx-U-ECRw,10754
 starrocks_br/repository.py,sha256=gZgT0mAjs-AAdESXPF8Syv0bE8m5njya5leTageElQ8,1251
 starrocks_br/restore.py,sha256=7_VcrGt0KVqhWe9f3JgQYDMNuM6_EjBqCi63BiSa2WY,20105
 starrocks_br/schema.py,sha256=FSJjcz4q3SU_rHLptsSzrlm-o0dcvIu6LbpT-Z5GyZA,6199
 starrocks_br/timezone.py,sha256=WlB_gkgI4AjQzqHVA1eG9CY_9QiX5cYpVKjQLvSrd4Y,3578
 starrocks_br/utils.py,sha256=LF3uBdaNMeslE4UHl_wwv4QErCS48ISxpPqYX8dbrc8,2176
-starrocks_br-0.5.0.dist-info/METADATA,sha256=kfTP9BWHOUoF7gvh8tgH2TufIRmWQasVGZgXw4GH5Ec,5728
-starrocks_br-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-starrocks_br-0.5.0.dist-info/entry_points.txt,sha256=AKUt01G2MAlh85s1Q9kNQDOUio14kaTnT3dmg9gjdNg,54
-starrocks_br-0.5.0.dist-info/top_level.txt,sha256=CU1tGVo0kjulhDr761Sndg-oTeRKsisDnWm8UG95aBE,13
-starrocks_br-0.5.0.dist-info/RECORD,,
+starrocks_br-0.5.1.dist-info/METADATA,sha256=0n2LiJNNG8p_Es5zV8JRQhdSTcV8fkE2eCiwiSYTRas,5728
+starrocks_br-0.5.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+starrocks_br-0.5.1.dist-info/entry_points.txt,sha256=AKUt01G2MAlh85s1Q9kNQDOUio14kaTnT3dmg9gjdNg,54
+starrocks_br-0.5.1.dist-info/top_level.txt,sha256=CU1tGVo0kjulhDr761Sndg-oTeRKsisDnWm8UG95aBE,13
+starrocks_br-0.5.1.dist-info/RECORD,,