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

starrocks_br/cli.py

@@ -6,6 +6,8 @@ import click
 from . import (
     concurrency,
     db,
+    error_handler,
+    exceptions,
     executor,
     health,
     labels,
@@ -63,9 +65,20 @@ def _handle_snapshot_exists_error(
 
 
 @click.group()
-def cli():
+@click.option("--verbose", is_flag=True, help="Enable verbose debug logging")
+@click.pass_context
+def cli(ctx, verbose):
     """StarRocks Backup & Restore automation tool."""
-    pass
+    ctx.ensure_object(dict)
+    ctx.obj["verbose"] = verbose
+
+    if verbose:
+        import logging
+
+        logger.setup_logging(level=logging.DEBUG)
+        logger.debug("Verbose logging enabled")
+    else:
+        logger.setup_logging()
 
 
 @cli.command("init")
@@ -112,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}")
@@ -262,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}")
@@ -381,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)
 
 
@@ -429,14 +465,13 @@ def restore_command(config, target_label, group, table, rename_suffix, yes):
         if table:
             table = table.strip()
             if not table:
-                logger.error("Table name cannot be empty")
-                sys.exit(1)
+                raise exceptions.InvalidTableNameError("", "Table name cannot be empty")
 
             if "." in table:
-                logger.error(
-                    "Table name must not include database prefix. Use 'table_name' not 'database.table_name'. Database comes from config file."
+                raise exceptions.InvalidTableNameError(
+                    table,
+                    "Table name must not include database prefix. Use 'table_name' not 'database.table_name'",
                 )
-                sys.exit(1)
 
         cfg = config_module.load_config(config)
         config_module.validate_config(cfg)
@@ -472,39 +507,21 @@ def restore_command(config, target_label, group, table, rename_suffix, yes):
 
             logger.info(f"Finding restore sequence for target backup: {target_label}")
 
-            try:
-                restore_pair = restore.find_restore_pair(database, target_label)
-                logger.success(f"Found restore sequence: {' -> '.join(restore_pair)}")
-            except ValueError as e:
-                logger.error(f"Failed to find restore sequence: {e}")
-                sys.exit(1)
+            restore_pair = restore.find_restore_pair(database, target_label)
+            logger.success(f"Found restore sequence: {' -> '.join(restore_pair)}")
 
             logger.info("Determining tables to restore from backup manifest...")
 
-            try:
-                tables_to_restore = restore.get_tables_from_backup(
-                    database,
-                    target_label,
-                    group=group,
-                    table=table,
-                    database=cfg["database"] if table else None,
-                )
-            except ValueError as e:
-                logger.error(str(e))
-                sys.exit(1)
+            tables_to_restore = restore.get_tables_from_backup(
+                database,
+                target_label,
+                group=group,
+                table=table,
+                database=cfg["database"] if table else None,
+            )
 
             if not tables_to_restore:
-                if group:
-                    logger.warning(
-                        f"No tables found in backup '{target_label}' for group '{group}'"
-                    )
-                elif table:
-                    logger.warning(
-                        f"No tables found in backup '{target_label}' for table '{table}'"
-                    )
-                else:
-                    logger.warning(f"No tables found in backup '{target_label}'")
-                sys.exit(1)
+                raise exceptions.NoTablesFoundError(group=group, label=target_label)
 
             logger.success(
                 f"Found {len(tables_to_restore)} table(s) to restore: {', '.join(tables_to_restore)}"
@@ -527,14 +544,46 @@ def restore_command(config, target_label, group, table, rename_suffix, yes):
                 logger.error(f"Restore failed: {result['error_message']}")
                 sys.exit(1)
 
+    except exceptions.InvalidTableNameError as e:
+        error_handler.handle_invalid_table_name_error(e)
+        sys.exit(1)
+    except exceptions.BackupLabelNotFoundError as e:
+        error_handler.handle_backup_label_not_found_error(e, config)
+        sys.exit(1)
+    except exceptions.NoSuccessfulFullBackupFoundError as e:
+        error_handler.handle_no_successful_full_backup_found_error(e, config)
+        sys.exit(1)
+    except exceptions.TableNotFoundInBackupError as e:
+        error_handler.handle_table_not_found_in_backup_error(e, config)
+        sys.exit(1)
+    except exceptions.NoTablesFoundError as e:
+        error_handler.handle_no_tables_found_error(e, config, target_label)
+        sys.exit(1)
+    except exceptions.SnapshotNotFoundError as e:
+        error_handler.handle_snapshot_not_found_error(e, config)
+        sys.exit(1)
+    except exceptions.RestoreOperationCancelledError:
+        error_handler.handle_restore_operation_cancelled_error()
+        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 exceptions.ClusterHealthCheckFailedError as e:
+        error_handler.handle_cluster_health_check_failed_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}")
+        error_handler.handle_config_validation_error(
+            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/db.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any
 
 import mysql.connector
 
@@ -13,7 +13,7 @@ class StarRocksDB:
         user: str,
         password: str,
         database: str,
-        tls_config: Optional[dict[str, Any]] = None,
+        tls_config: dict[str, Any] | None = None,
     ):
         """Initialize database connection.
 
@@ -31,7 +31,7 @@ class StarRocksDB:
         self.database = database
         self._connection = None
         self.tls_config = tls_config or {}
-        self._timezone: Optional[str] = None
+        self._timezone: str | None = None
 
     def connect(self) -> None:
         """Establish database connection."""

starrocks_br/error_handler.py

@@ -0,0 +1,307 @@
+import click
+
+from . import exceptions
+
+
+def display_structured_error(
+    title: str,
+    reason: str,
+    what_to_do: list[str],
+    inputs: dict = None,
+    help_links: list[str] = None,
+) -> None:
+    click.echo()
+    click.echo(click.style(f"❌ {title}", fg="red", bold=True), err=True)
+    click.echo(reason, err=True)
+    click.echo()
+
+    click.echo(click.style("REASON", fg="yellow", bold=True), err=True)
+    click.echo(reason, err=True)
+    click.echo()
+
+    click.echo(click.style("WHAT YOU CAN DO", fg="cyan", bold=True), err=True)
+    for i, action in enumerate(what_to_do, 1):
+        click.echo(f"{i}) {action}", err=True)
+    click.echo()
+
+    if inputs:
+        click.echo(click.style("INPUT YOU PROVIDED", fg="magenta", bold=True), err=True)
+        for key, value in inputs.items():
+            if value is None:
+                click.echo(f" Missing: {key}", err=True)
+            else:
+                click.echo(f" {key}: {value}", err=True)
+        click.echo()
+
+    if help_links:
+        click.echo(click.style("NEED HELP?", fg="green", bold=True), err=True)
+        for link in help_links:
+            click.echo(f" → {link}", err=True)
+        click.echo()
+
+
+def handle_missing_option_error(exc: exceptions.MissingOptionError, config: str = None) -> None:
+    display_structured_error(
+        title="OPERATION FAILED",
+        reason=f'The "{exc.missing_option}" option was not provided.\nThis parameter is required for the operation.',
+        what_to_do=[
+            f"Add the missing parameter: {exc.missing_option}",
+            "Run the command with --help to see all required options",
+            f"Example: starrocks-br <command> {exc.missing_option} <value>"
+            + (f" --config {config}" if config else ""),
+        ],
+        inputs={"--config": config, "Missing": exc.missing_option}
+        if config
+        else {"Missing": exc.missing_option},
+        help_links=["Run with --help for more information"],
+    )
+
+
+def handle_backup_label_not_found_error(
+    exc: exceptions.BackupLabelNotFoundError, config: str = None
+) -> None:
+    display_structured_error(
+        title="RESTORE FAILED",
+        reason=f'The backup label "{exc.label}" does not exist in the repository'
+        + (f' "{exc.repository}"' if exc.repository else "")
+        + ",\nor the backup did not complete successfully.",
+        what_to_do=[
+            "List available backups by querying the backup history table:\n     SELECT label, backup_type, status, finished_at FROM ops.backup_history ORDER BY finished_at DESC;",
+            "Check whether the backup completed successfully using StarRocks SQL:"
+            + (
+                f"\n     SHOW BACKUP FROM `{exc.repository}`;"
+                if exc.repository
+                else "\n     SHOW BACKUP;"
+            ),
+            "Verify that the backup label spelling is correct.",
+        ],
+        inputs={"--config": config, "--target-label": exc.label, "Repository": exc.repository},
+        help_links=["starrocks-br restore --help"],
+    )
+
+
+def handle_no_successful_full_backup_found_error(
+    exc: exceptions.NoSuccessfulFullBackupFoundError, config: str = None
+) -> None:
+    display_structured_error(
+        title="RESTORE FAILED",
+        reason=f'No successful full backup was found before the incremental backup "{exc.incremental_label}".\nIncremental backups require a base full backup to restore from.',
+        what_to_do=[
+            "Verify that a full backup was created before this incremental backup:\n     SELECT label, backup_type, status, finished_at FROM ops.backup_history WHERE backup_type = 'full' AND status = 'FINISHED' ORDER BY finished_at DESC;",
+            "Run a full backup first:\n     starrocks-br backup full --config "
+            + (config if config else "<config.yaml>")
+            + " --group <group_name>",
+            "Check that the full backup completed successfully before running the incremental backup",
+        ],
+        inputs={"--target-label": exc.incremental_label, "--config": config},
+        help_links=["starrocks-br backup full --help"],
+    )
+
+
+def handle_table_not_found_in_backup_error(
+    exc: exceptions.TableNotFoundInBackupError, config: str = None
+) -> None:
+    display_structured_error(
+        title="TABLE NOT FOUND",
+        reason=f'Table "{exc.table}" was not found in backup "{exc.label}" for database "{exc.database}".',
+        what_to_do=[
+            "List all tables in the backup:"
+            + (
+                f"\n     SELECT DISTINCT database_name, table_name FROM ops.backup_partitions WHERE label = '{exc.label}';"
+                if config
+                else ""
+            ),
+            "Verify the table name spelling is correct",
+            f"Ensure the table was included in the backup {exc.label}",
+        ],
+        inputs={
+            "--table": exc.table,
+            "--target-label": exc.label,
+            "Database": exc.database,
+            "--config": config,
+        },
+        help_links=["starrocks-br restore --help"],
+    )
+
+
+def handle_invalid_table_name_error(exc: exceptions.InvalidTableNameError) -> None:
+    display_structured_error(
+        title="INVALID TABLE NAME",
+        reason=f'The table name "{exc.table_name}" is invalid.\n{exc.reason}',
+        what_to_do=[
+            "Use only the table name without database prefix",
+            "Example: Use 'my_table' instead of 'database.my_table'",
+            "The database name should come from the config file",
+        ],
+        inputs={"--table": exc.table_name},
+        help_links=["starrocks-br restore --help"],
+    )
+
+
+def handle_config_file_not_found_error(exc: exceptions.ConfigFileNotFoundError) -> None:
+    display_structured_error(
+        title="CONFIG FILE NOT FOUND",
+        reason=f'The configuration file "{exc.config_path}" could not be found.',
+        what_to_do=[
+            "Verify the config file path is correct",
+            "Ensure the file exists at the specified location",
+            "Create a config file with the required settings:\n     host, port, user, database, repository",
+        ],
+        inputs={"--config": exc.config_path},
+        help_links=["Check the documentation for config file format"],
+    )
+
+
+def handle_config_validation_error(
+    exc: exceptions.ConfigValidationError, config: str = None
+) -> None:
+    display_structured_error(
+        title="CONFIGURATION ERROR",
+        reason=str(exc),
+        what_to_do=[
+            "Review your configuration file for missing or invalid settings",
+            "Ensure all required fields are present: host, port, user, database, repository",
+            "Check that values are in the correct format",
+        ],
+        inputs={"--config": config},
+        help_links=["Check the documentation for config file requirements"],
+    )
+
+
+def handle_cluster_health_check_failed_error(
+    exc: exceptions.ClusterHealthCheckFailedError, config: str = None
+) -> None:
+    display_structured_error(
+        title="CLUSTER HEALTH CHECK FAILED",
+        reason=f"The StarRocks cluster health check failed: {exc.health_message}",
+        what_to_do=[
+            "Check that the StarRocks cluster is running",
+            "Verify database connectivity settings in your config file",
+            "Check cluster status with: SHOW PROC '/frontends'; SHOW PROC '/backends';",
+        ],
+        inputs={"--config": config},
+        help_links=["Check StarRocks documentation for troubleshooting cluster issues"],
+    )
+
+
+def handle_snapshot_not_found_error(
+    exc: exceptions.SnapshotNotFoundError, config: str = None
+) -> None:
+    display_structured_error(
+        title="SNAPSHOT NOT FOUND",
+        reason=f'Snapshot "{exc.snapshot_name}" was not found in repository "{exc.repository}".',
+        what_to_do=[
+            f"List available snapshots:\n     SHOW SNAPSHOT ON {exc.repository};",
+            "Verify the snapshot name spelling is correct",
+            "Ensure the backup completed successfully:\n     SELECT * FROM ops.backup_history WHERE label = '"
+            + exc.snapshot_name
+            + "';",
+        ],
+        inputs={"Snapshot": exc.snapshot_name, "Repository": exc.repository, "--config": config},
+        help_links=["starrocks-br restore --help"],
+    )
+
+
+def handle_no_partitions_found_error(
+    exc: exceptions.NoPartitionsFoundError, config: str = None, group: str = None
+) -> None:
+    display_structured_error(
+        title="NO PARTITIONS FOUND",
+        reason="No partitions were found to backup"
+        + (f" for group '{exc.group_name}'" if exc.group_name else "")
+        + ".",
+        what_to_do=[
+            "Verify that the inventory group exists in ops.table_inventory:\n     SELECT * FROM ops.table_inventory WHERE inventory_group = "
+            + (f"'{exc.group_name}';" if exc.group_name else "'<your_group>';"),
+            "Check that the tables in the group have partitions",
+            "Ensure the baseline backup date is correct",
+        ],
+        inputs={"--group": exc.group_name or group, "--config": config},
+        help_links=["starrocks-br backup incremental --help"],
+    )
+
+
+def handle_no_tables_found_error(
+    exc: exceptions.NoTablesFoundError, config: str = None, target_label: str = None
+) -> None:
+    display_structured_error(
+        title="NO TABLES FOUND",
+        reason="No tables were found"
+        + (
+            f" in backup '{exc.label}' for group '{exc.group}'"
+            if exc.group and exc.label
+            else f" in backup '{exc.label}'"
+            if exc.label
+            else ""
+        )
+        + ".",
+        what_to_do=[
+            "Verify that tables exist in the backup manifest:\n     SELECT DISTINCT database_name, table_name FROM ops.backup_partitions WHERE label = "
+            + (f"'{exc.label}';" if exc.label else "'<label>';"),
+            "Check that the group name is correct in ops.table_inventory"
+            if exc.group
+            else "Verify the backup completed successfully",
+            "List available backups:\n     SELECT label, backup_type, status, finished_at FROM ops.backup_history ORDER BY finished_at DESC;",
+        ],
+        inputs={
+            "--target-label": exc.label or target_label,
+            "--group": exc.group,
+            "--config": config,
+        },
+        help_links=["starrocks-br restore --help"],
+    )
+
+
+def handle_restore_operation_cancelled_error() -> None:
+    display_structured_error(
+        title="OPERATION CANCELLED",
+        reason="The restore operation was cancelled by the user.",
+        what_to_do=[
+            "Review the restore plan carefully",
+            "Run again and confirm with 'Y' to proceed",
+            "Use the --yes flag to skip the confirmation prompt:\n     starrocks-br restore --yes ...",
+        ],
+        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

@@ -0,0 +1,109 @@
+class StarRocksBRError(Exception):
+    pass
+
+
+class MissingOptionError(StarRocksBRError):
+    def __init__(self, missing_option: str):
+        self.missing_option = missing_option
+        super().__init__(f"Missing required option: {missing_option}")
+
+
+class BackupLabelNotFoundError(StarRocksBRError):
+    def __init__(self, label: str, repository: str = None):
+        self.label = label
+        self.repository = repository
+        if repository:
+            super().__init__(f"Backup label '{label}' not found in repository '{repository}'")
+        else:
+            super().__init__(f"Backup label '{label}' not found")
+
+
+class NoSuccessfulFullBackupFoundError(StarRocksBRError):
+    def __init__(self, incremental_label: str):
+        self.incremental_label = incremental_label
+        super().__init__(
+            f"No successful full backup found before incremental '{incremental_label}'"
+        )
+
+
+class TableNotFoundInBackupError(StarRocksBRError):
+    def __init__(self, table: str, label: str, database: str):
+        self.table = table
+        self.label = label
+        self.database = database
+        super().__init__(f"Table '{table}' not found in backup '{label}' for database '{database}'")
+
+
+class InvalidTableNameError(StarRocksBRError):
+    def __init__(self, table_name: str, reason: str):
+        self.table_name = table_name
+        self.reason = reason
+        super().__init__(f"Invalid table name '{table_name}': {reason}")
+
+
+class ConfigFileNotFoundError(StarRocksBRError):
+    def __init__(self, config_path: str):
+        self.config_path = config_path
+        super().__init__(f"Config file not found: {config_path}")
+
+
+class ConfigValidationError(StarRocksBRError):
+    def __init__(self, message: str):
+        super().__init__(f"Configuration error: {message}")
+
+
+class ClusterHealthCheckFailedError(StarRocksBRError):
+    def __init__(self, message: str):
+        self.health_message = message
+        super().__init__(f"Cluster health check failed: {message}")
+
+
+class SnapshotNotFoundError(StarRocksBRError):
+    def __init__(self, snapshot_name: str, repository: str):
+        self.snapshot_name = snapshot_name
+        self.repository = repository
+        super().__init__(f"Snapshot '{snapshot_name}' not found in repository '{repository}'")
+
+
+class NoPartitionsFoundError(StarRocksBRError):
+    def __init__(self, group_name: str = None):
+        self.group_name = group_name
+        if group_name:
+            super().__init__(f"No partitions found to backup for group '{group_name}'")
+        else:
+            super().__init__("No partitions found to backup")
+
+
+class NoTablesFoundError(StarRocksBRError):
+    def __init__(self, group: str = None, label: str = None):
+        self.group = group
+        self.label = label
+        if group and label:
+            super().__init__(f"No tables found in backup '{label}' for group '{group}'")
+        elif group:
+            super().__init__(f"No tables found for group '{group}'")
+        elif label:
+            super().__init__(f"No tables found in backup '{label}'")
+        else:
+            super().__init__("No tables found")
+
+
+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/executor.py

@@ -1,6 +1,6 @@
 import re
 import time
-from typing import Literal, Optional
+from typing import Literal
 
 from . import concurrency, history, logger, timezone
 
@@ -22,7 +22,7 @@ def _calculate_next_interval(current_interval: float, max_interval: float) -> fl
 
 def submit_backup_command(
     db, backup_command: str
-) -> tuple[bool, Optional[str], Optional[dict[str, str]]]:
+) -> tuple[bool, str | None, dict[str, str] | None]:
     """Submit a backup command to StarRocks.
 
     Returns (success, error_message, error_details).
@@ -50,7 +50,7 @@ def submit_backup_command(
         return False, error_msg, None
 
 
-def _check_snapshot_exists_error(exception: Exception, error_str: str) -> Optional[str]:
+def _check_snapshot_exists_error(exception: Exception, error_str: str) -> str | None:
     """Check if the error is a 'snapshot already exists' error and extract snapshot name.
 
     Args:
@@ -166,7 +166,7 @@ def execute_backup(
     repository: str,
     backup_type: Literal["incremental", "full"] = None,
     scope: str = "backup",
-    database: Optional[str] = None,
+    database: str | None = None,
 ) -> dict:
     """Execute a complete backup workflow: submit command and monitor progress.
 

starrocks_br/history.py

@@ -1,9 +1,7 @@
-from typing import Optional
-
 from . import logger
 
 
-def log_backup(db, entry: dict[str, Optional[str]]) -> None:
+def log_backup(db, entry: dict[str, str | None]) -> None:
     """Write a backup history entry to ops.backup_history.
 
     Expected keys in entry:
@@ -24,7 +22,7 @@ def log_backup(db, entry: dict[str, Optional[str]]) -> None:
     finished_at = entry.get("finished_at", "NULL")
     error_message = entry.get("error_message")
 
-    def esc(val: Optional[str]) -> str:
+    def esc(val: str | None) -> str:
         if val is None:
             return "NULL"
         return "'" + str(val).replace("'", "''") + "'"
@@ -45,7 +43,7 @@ def log_backup(db, entry: dict[str, Optional[str]]) -> None:
         raise
 
 
-def log_restore(db, entry: dict[str, Optional[str]]) -> None:
+def log_restore(db, entry: dict[str, str | None]) -> None:
     """Write a restore history entry to ops.restore_history.
 
     Expected keys in entry:
@@ -69,7 +67,7 @@ def log_restore(db, entry: dict[str, Optional[str]]) -> None:
     error_message = entry.get("error_message")
     verification_checksum = entry.get("verification_checksum")
 
-    def esc(val: Optional[str]) -> str:
+    def esc(val: str | None) -> str:
         if val is None:
             return "NULL"
         return "'" + str(val).replace("'", "''") + "'"

starrocks_br/labels.py

@@ -1,12 +1,12 @@
 from datetime import datetime
-from typing import Literal, Optional
+from typing import Literal
 
 
 def determine_backup_label(
     db,
     backup_type: Literal["incremental", "full"],
     database_name: str,
-    custom_name: Optional[str] = None,
+    custom_name: str | None = None,
 ) -> str:
     """Determine a unique backup label for the given parameters.
 

starrocks_br/logger.py

@@ -1,36 +1,66 @@
-import click
+import logging
+import threading
+
+_logger = None
+_logger_lock = threading.Lock()
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    global _logger
+    _logger = logging.getLogger("starrocks_br")
+    _logger.setLevel(level)
+
+    if _logger.handlers:
+        _logger.handlers.clear()
+
+    handler = logging.StreamHandler()
+
+    if level == logging.DEBUG:
+        formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(name)s - %(message)s")
+    else:
+        formatter = logging.Formatter("%(message)s")
+
+    handler.setFormatter(formatter)
+    _logger.addHandler(handler)
+    _logger.propagate = False
+
+
+def _get_logger() -> logging.Logger:
+    global _logger
+    if _logger is None:
+        with _logger_lock:
+            if _logger is None:
+                setup_logging()
+    return _logger
 
 
 def info(message: str) -> None:
-    """Log an informational message."""
-    click.echo(message)
+    _get_logger().info(message)
 
 
 def success(message: str) -> None:
-    """Log a success message with checkmark."""
-    click.echo(f"✓ {message}")
+    _get_logger().info(f"✓ {message}")
 
 
 def warning(message: str) -> None:
-    """Log a warning message with warning symbol."""
-    click.echo(f"⚠ {message}", err=True)
+    _get_logger().warning(f"⚠ {message}")
 
 
 def error(message: str) -> None:
-    """Log an error message with error prefix."""
-    click.echo(f"Error: {message}", err=True)
+    _get_logger().error(f"Error: {message}")
 
 
 def critical(message: str) -> None:
-    """Log a critical error message with critical symbol."""
-    click.echo(f"❌ CRITICAL: {message}", err=True)
+    _get_logger().critical(f"❌ CRITICAL: {message}")
 
 
 def progress(message: str) -> None:
-    """Log a progress message with hourglass symbol."""
-    click.echo(f"⏳ {message}")
+    _get_logger().info(f"⏳ {message}")
 
 
 def tip(message: str) -> None:
-    """Log a tip message with lightbulb symbol."""
-    click.echo(f"💡 {message}", err=True)
+    _get_logger().warning(f"💡 {message}")
+
+
+def debug(message: str) -> None:
+    _get_logger().debug(message)

starrocks_br/planner.py

@@ -1,11 +1,10 @@
 import datetime
 import hashlib
-from typing import Optional
 
-from starrocks_br import logger, timezone, utils
+from starrocks_br import exceptions, logger, timezone, utils
 
 
-def find_latest_full_backup(db, database: str) -> Optional[dict[str, str]]:
+def find_latest_full_backup(db, database: str) -> dict[str, str] | None:
     """Find the latest successful full backup for a database.
 
     Args:
@@ -60,7 +59,7 @@ def find_tables_by_group(db, group_name: str) -> list[dict[str, str]]:
 
 
 def find_recent_partitions(
-    db, database: str, baseline_backup_label: Optional[str] = None, *, group_name: str
+    db, database: str, baseline_backup_label: str | None = None, *, group_name: str
 ) -> list[dict[str, str]]:
     """Find partitions updated since baseline for tables in the given inventory group.
 
@@ -84,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/restore.py

@@ -1,8 +1,7 @@
 import datetime
 import time
-from typing import Optional
 
-from . import concurrency, history, logger, timezone, utils
+from . import concurrency, exceptions, history, logger, timezone, utils
 
 MAX_POLLS = 86400  # 1 day
 
@@ -38,7 +37,7 @@ def get_snapshot_timestamp(db, repo_name: str, snapshot_name: str) -> str:
 
     rows = db.query(query)
     if not rows:
-        raise ValueError(f"Snapshot '{snapshot_name}' not found in repository '{repo_name}'")
+        raise exceptions.SnapshotNotFoundError(snapshot_name, repo_name)
 
     # The result should be a single row with columns: Snapshot, Timestamp, Status
     result = rows[0]
@@ -274,7 +273,7 @@ def find_restore_pair(db, target_label: str) -> list[str]:
 
     rows = db.query(query)
     if not rows:
-        raise ValueError(f"Backup label '{target_label}' not found or not successful")
+        raise exceptions.BackupLabelNotFoundError(target_label)
 
     target_info = {"label": rows[0][0], "backup_type": rows[0][1], "finished_at": rows[0][2]}
 
@@ -297,7 +296,7 @@ def find_restore_pair(db, target_label: str) -> list[str]:
 
         full_rows = db.query(full_backup_query)
         if not full_rows:
-            raise ValueError(f"No successful full backup found before incremental '{target_label}'")
+            raise exceptions.NoSuccessfulFullBackupFoundError(target_label)
 
         base_full_backup = full_rows[0][0]
         return [base_full_backup, target_label]
@@ -310,9 +309,9 @@ def find_restore_pair(db, target_label: str) -> list[str]:
 def get_tables_from_backup(
     db,
     label: str,
-    group: Optional[str] = None,
-    table: Optional[str] = None,
-    database: Optional[str] = None,
+    group: str | None = None,
+    table: str | None = None,
+    database: str | None = None,
 ) -> list[str]:
     """Get list of tables to restore from backup manifest.
 
@@ -332,12 +331,12 @@ def get_tables_from_backup(
         ValueError: If table is specified but not found in backup
     """
     if group and table:
-        raise ValueError(
-            "Cannot specify both --group and --table. Use --table for single table restore or --group for inventory group restore."
-        )
+        raise exceptions.InvalidTableNameError(table, "Cannot specify both --group and --table")
 
     if table and not database:
-        raise ValueError("database parameter is required when table is specified")
+        raise exceptions.InvalidTableNameError(
+            table, "database parameter is required when table is specified"
+        )
 
     query = f"""
     SELECT DISTINCT database_name, table_name
@@ -357,9 +356,7 @@ def get_tables_from_backup(
         filtered_tables = [t for t in tables if t == target_table]
 
         if not filtered_tables:
-            raise ValueError(
-                f"Table '{table}' not found in backup '{label}' for database '{database}'"
-            )
+            raise exceptions.TableNotFoundInBackupError(table, label, database)
 
         return filtered_tables
 
@@ -433,7 +430,7 @@ def execute_restore_flow(
     if not skip_confirmation:
         confirmation = input("\nDo you want to proceed? [Y/n]: ").strip()
         if confirmation.lower() != "y":
-            return {"success": False, "error_message": "Restore operation cancelled by user"}
+            raise exceptions.RestoreOperationCancelledError()
     else:
         logger.info("Proceeding automatically (--yes flag provided)")
 

starrocks_br/timezone.py

@@ -1,5 +1,4 @@
 import datetime
-from typing import Union
 from zoneinfo import ZoneInfo
 
 
@@ -55,7 +54,7 @@ def normalize_datetime_to_tz(dt: datetime.datetime, target_tz: str) -> datetime.
     return dt
 
 
-def _get_timezone(tz_str: str) -> Union[ZoneInfo, datetime.timezone]:
+def _get_timezone(tz_str: str) -> ZoneInfo | datetime.timezone:
     """Get timezone object from timezone string.
 
     Handles both named timezones (e.g., 'Asia/Shanghai') and offset strings (e.g., '+08:00', '-05:00').

{starrocks_br-0.4.0.dist-info → starrocks_br-0.5.1.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: starrocks-br
-Version: 0.4.0
+Version: 0.5.1
 Summary: StarRocks Backup and Restore automation tool
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: click<9,>=8.1.7
 Requires-Dist: PyYAML<7,>=6.0.1
@@ -12,6 +12,7 @@ Requires-Dist: pytest<9,>=8.3.2; extra == "dev"
 Requires-Dist: pytest-mock<4,>=3.14.0; extra == "dev"
 Requires-Dist: pytest-cov<6,>=5.0.0; extra == "dev"
 Requires-Dist: ruff<1,>=0.8.0; extra == "dev"
+Requires-Dist: pre-commit<5,>=4.0.0; extra == "dev"
 
 # StarRocks Backup & Restore
 

starrocks_br-0.5.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+starrocks_br/__init__.py,sha256=i1m0FIl2IAXaVyNoya0ZNAx3WfhIp9I6VLhTz06qNFY,28
+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=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=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.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,,

starrocks_br-0.4.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-starrocks_br/__init__.py,sha256=i1m0FIl2IAXaVyNoya0ZNAx3WfhIp9I6VLhTz06qNFY,28
-starrocks_br/cli.py,sha256=yXrmfLL-doIZ9ahFKfXqGR09NB08jqz4BUhkkSCpEJc,20483
-starrocks_br/concurrency.py,sha256=N0LD4VHTAFNhD4YslrkOCDSx5cnR5rCEkNH9MkODxv8,5903
-starrocks_br/config.py,sha256=APqOZcJuUzYmGNHoJRlsu4l3sWl_4SS1kRLKjKm2Oag,2059
-starrocks_br/db.py,sha256=gPFP_VcGmAM5uMADSFR9pNEbYN9IXDnN0O2YFMptkmM,4962
-starrocks_br/executor.py,sha256=Z8k5oW-TRE0zg8on9_YtKqhT82Nq_ZmuGxC09Wx7M60,11367
-starrocks_br/health.py,sha256=rmkgNYf6kk3VDZx-PmnAG3lzmtvnJcUPG7Ppb6BA7IU,1021
-starrocks_br/history.py,sha256=kx2H0wGVYCoIvC1_zN4BMGv9d2YebR5oX3NlUd9yeWg,3005
-starrocks_br/labels.py,sha256=-JfO34gNjYEGjSRW5haRRYYWvMrXRpNh9mTKXthAxzI,1675
-starrocks_br/logger.py,sha256=QTfr-nC3TdeU7f1gcRTRDAQSLYpwaevd_iT1B_RbuF8,900
-starrocks_br/planner.py,sha256=QcgBw_psqzWS2FnsmXvYHFgiOMMkfyEvMJryDUFhkpk,10926
-starrocks_br/repository.py,sha256=gZgT0mAjs-AAdESXPF8Syv0bE8m5njya5leTageElQ8,1251
-starrocks_br/restore.py,sha256=4XBcPMeplrqKyaU_yU5GhunAtPWtmvErOi2xOQPWQKA,20306
-starrocks_br/schema.py,sha256=FSJjcz4q3SU_rHLptsSzrlm-o0dcvIu6LbpT-Z5GyZA,6199
-starrocks_br/timezone.py,sha256=RYmM9RIEy1hphVGhwv7A8j1DyV9Djf-Y5HE8NxZMDtg,3609
-starrocks_br/utils.py,sha256=LF3uBdaNMeslE4UHl_wwv4QErCS48ISxpPqYX8dbrc8,2176
-starrocks_br-0.4.0.dist-info/METADATA,sha256=wYmVX_4K_i5K42fxA075GEUqCBSAbhfbAJ-qnvPx8I8,5675
-starrocks_br-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-starrocks_br-0.4.0.dist-info/entry_points.txt,sha256=AKUt01G2MAlh85s1Q9kNQDOUio14kaTnT3dmg9gjdNg,54
-starrocks_br-0.4.0.dist-info/top_level.txt,sha256=CU1tGVo0kjulhDr761Sndg-oTeRKsisDnWm8UG95aBE,13
-starrocks_br-0.4.0.dist-info/RECORD,,