starrocks-br 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

starrocks_br/cli.py

@@ -15,6 +15,40 @@ from . import schema
 from . import logger
 
 
+def _handle_snapshot_exists_error(error_details: dict, label: str, config: str, repository: str, backup_type: str, group: str, baseline_backup: str = None) -> None:
+    """Handle snapshot_exists error by providing helpful guidance to the user.
+    
+    Args:
+        error_details: Error details dict containing error_type and snapshot_name
+        label: The backup label that was generated
+        config: Path to config file
+        repository: Repository name
+        backup_type: Type of backup ('incremental' or 'full')
+        group: Inventory group name
+        baseline_backup: Optional baseline backup label (for incremental backups)
+    """
+    snapshot_name = error_details.get('snapshot_name', label)
+    logger.error(f"Snapshot '{snapshot_name}' already exists in the repository.")
+    logger.info("")
+    logger.info("This typically happens when:")
+    logger.info("  • The CLI lost connectivity during a previous backup operation")
+    logger.info("  • The backup completed on the server, but backup_history wasn't updated")
+    logger.info("")
+    logger.info("To resolve this, retry the backup with a custom label using --name:")
+    
+    if backup_type == 'incremental':
+        retry_cmd = f"  starrocks-br backup incremental --config {config} --group {group} --name {snapshot_name}_retry"
+        if baseline_backup:
+            retry_cmd += f" --baseline-backup {baseline_backup}"
+        logger.info(retry_cmd)
+    else:
+        logger.info(f"  starrocks-br backup full --config {config} --group {group} --name {snapshot_name}_retry")
+    
+    logger.info("")
+    logger.tip("You can verify the existing backup by checking the repository or running:")
+    logger.tip(f"  SHOW SNAPSHOT ON {repository} WHERE Snapshot = '{snapshot_name}'")
+
+
 @click.group()
 def cli():
     """StarRocks Backup & Restore automation tool."""
@@ -43,7 +77,8 @@ def init(config):
             port=cfg['port'],
             user=cfg['user'],
             password=os.getenv('STARROCKS_PASSWORD'),
-            database=cfg['database']
+            database=cfg['database'],
+            tls_config=cfg.get('tls'),
         )
         
         with database:
@@ -102,7 +137,8 @@ def backup_incremental(config, baseline_backup, group, name):
             port=cfg['port'],
             user=cfg['user'],
             password=os.getenv('STARROCKS_PASSWORD'),
-            database=cfg['database']
+            database=cfg['database'],
+            tls_config=cfg.get('tls'),
         )
         
         with database:
@@ -174,6 +210,13 @@ def backup_incremental(config, baseline_backup, group, name):
                 logger.success(f"Backup completed successfully: {result['final_status']['state']}")
                 sys.exit(0)
             else:
+                error_details = result.get('error_details')
+                if error_details and error_details.get('error_type') == 'snapshot_exists':
+                    _handle_snapshot_exists_error(
+                        error_details, label, config, cfg['repository'], 'incremental', group, baseline_backup
+                    )
+                    sys.exit(1)
+                
                 state = result.get('final_status', {}).get('state', 'UNKNOWN')
                 if state == "LOST":
                     logger.critical("Backup tracking lost!")
@@ -215,7 +258,8 @@ def backup_full(config, group, name):
             port=cfg['port'],
             user=cfg['user'],
             password=os.getenv('STARROCKS_PASSWORD'),
-            database=cfg['database']
+            database=cfg['database'],
+            tls_config=cfg.get('tls'),
         )
         
         with database:
@@ -274,6 +318,13 @@ def backup_full(config, group, name):
                 logger.success(f"Backup completed successfully: {result['final_status']['state']}")
                 sys.exit(0)
             else:
+                error_details = result.get('error_details')
+                if error_details and error_details.get('error_type') == 'snapshot_exists':
+                    _handle_snapshot_exists_error(
+                        error_details, label, config, cfg['repository'], 'full', group
+                    )
+                    sys.exit(1)
+                
                 state = result.get('final_status', {}).get('state', 'UNKNOWN')
                 if state == "LOST":
                     logger.critical("Backup tracking lost!")
@@ -300,8 +351,10 @@ def backup_full(config, group, name):
 @click.option('--config', required=True, help='Path to config YAML file')
 @click.option('--target-label', required=True, help='Backup label to restore to')
 @click.option('--group', help='Optional inventory group to filter tables to restore')
+@click.option('--table', help='Optional table name to restore (table name only, database comes from config). Cannot be used with --group.')
 @click.option('--rename-suffix', default='_restored', help='Suffix for temporary tables during restore (default: _restored)')
-def restore_command(config, target_label, group, rename_suffix):
+@click.option('--yes', is_flag=True, help='Skip confirmation prompt and proceed automatically')
+def restore_command(config, target_label, group, table, rename_suffix, yes):
     """Restore data to a specific point in time using intelligent backup chain resolution.
     
     This command automatically determines the correct sequence of backups needed for restore:
@@ -311,9 +364,23 @@ def restore_command(config, target_label, group, rename_suffix):
     The restore process uses temporary tables with the specified suffix for safety, then performs
     an atomic rename to make the restored data live.
     
-    Flow: load config → find restore pair → get tables from backup → execute restore flow
+    Flow: load config → check health → ensure repository → find restore pair → get tables from backup → execute restore flow
     """
     try:
+        if group and table:
+            logger.error("Cannot specify both --group and --table. Use --table for single table restore or --group for inventory group restore.")
+            sys.exit(1)
+        
+        if table:
+            table = table.strip()
+            if not table:
+                logger.error("Table name cannot be empty")
+                sys.exit(1)
+            
+            if '.' in table:
+                logger.error("Table name must not include database prefix. Use 'table_name' not 'database.table_name'. Database comes from config file.")
+                sys.exit(1)
+        
         cfg = config_module.load_config(config)
         config_module.validate_config(cfg)
         
@@ -322,7 +389,8 @@ def restore_command(config, target_label, group, rename_suffix):
             port=cfg['port'],
             user=cfg['user'],
             password=os.getenv('STARROCKS_PASSWORD'),
-            database=cfg['database']
+            database=cfg['database'],
+            tls_config=cfg.get('tls'),
         )
         
         with database:
@@ -332,6 +400,17 @@ def restore_command(config, target_label, group, rename_suffix):
                 logger.warning("Remember to populate ops.table_inventory with your backup groups!")
                 sys.exit(1) # Exit if schema was just created, requires user action
             
+            healthy, message = health.check_cluster_health(database)
+            if not healthy:
+                logger.error(f"Cluster health check failed: {message}")
+                sys.exit(1)
+            
+            logger.success(f"Cluster health: {message}")
+            
+            repository.ensure_repository(database, cfg['repository'])
+            
+            logger.success(f"Repository '{cfg['repository']}' verified")
+            
             logger.info(f"Finding restore sequence for target backup: {target_label}")
             
             try:
@@ -342,11 +421,24 @@ def restore_command(config, target_label, group, rename_suffix):
                 sys.exit(1)
             
             logger.info("Determining tables to restore from backup manifest...")
-            tables_to_restore = restore.get_tables_from_backup(database, target_label, group)
+            
+            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)
             
             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)
@@ -359,7 +451,8 @@ def restore_command(config, target_label, group, rename_suffix):
                 cfg['repository'],
                 restore_pair,
                 tables_to_restore,
-                rename_suffix
+                rename_suffix,
+                skip_confirmation=yes
             )
             
             if result['success']:
@@ -375,6 +468,9 @@ def restore_command(config, target_label, group, rename_suffix):
     except ValueError as e:
         logger.error(f"Configuration error: {e}")
         sys.exit(1)
+    except RuntimeError as e:
+        logger.error(f"{e}")
+        sys.exit(1)
     except Exception as e:
         logger.error(f"Unexpected error: {e}")
         sys.exit(1)

starrocks_br/config.py

@@ -1,8 +1,8 @@
 import yaml
-from typing import Dict
+from typing import Any, Dict, Optional
 
 
-def load_config(config_path: str) -> Dict:
+def load_config(config_path: str) -> Dict[str, Any]:
     """Load and parse YAML configuration file.
     
     Args:
@@ -24,7 +24,7 @@ def load_config(config_path: str) -> Dict:
     return config
 
 
-def validate_config(config: Dict) -> None:
+def validate_config(config: Dict[str, Any]) -> None:
     """Validate that config contains required fields.
     
     Args:
@@ -39,3 +39,26 @@ def validate_config(config: Dict) -> None:
         if field not in config:
             raise ValueError(f"Missing required config field: {field}")
 
+    _validate_tls_section(config.get('tls'))
+
+
+def _validate_tls_section(tls_config) -> None:
+    if tls_config is None:
+        return
+
+    if not isinstance(tls_config, dict):
+        raise ValueError("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")
+
+    if 'verify_server_cert' in tls_config and not isinstance(tls_config['verify_server_cert'], bool):
+        raise ValueError("TLS configuration field 'verify_server_cert' must be a boolean if provided")
+
+    if 'tls_versions' in tls_config:
+        tls_versions = tls_config['tls_versions']
+        if not isinstance(tls_versions, list) or not all(isinstance(version, str) for version in tls_versions):
+            raise ValueError("TLS configuration field 'tls_versions' must be a list of strings if provided")
+

starrocks_br/db.py

@@ -1,11 +1,19 @@
 import mysql.connector
-from typing import List
+from typing import Any, Dict, List, Optional
 
 
 class StarRocksDB:
     """Database connection wrapper for StarRocks."""
     
-    def __init__(self, host: str, port: int, user: str, password: str, database: str):
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        user: str,
+        password: str,
+        database: str,
+        tls_config: Optional[Dict[str, Any]] = None,
+    ):
         """Initialize database connection.
         
         Args:
@@ -21,16 +29,44 @@ class StarRocksDB:
         self.password = password
         self.database = database
         self._connection = None
+        self.tls_config = tls_config or {}
+        self._timezone: Optional[str] = None
     
     def connect(self) -> None:
         """Establish database connection."""
-        self._connection = mysql.connector.connect(
-            host=self.host,
-            port=self.port,
-            user=self.user,
-            password=self.password,
-            database=self.database
-        )
+        conn_args: Dict[str, Any] = {
+            'host': self.host,
+            'port': self.port,
+            'user': self.user,
+            'password': self.password,
+            'database': self.database,
+        }
+
+        if self.tls_config.get('enabled'):
+            ssl_args: Dict[str, Any] = {
+                'ssl_ca': self.tls_config.get('ca_cert'),
+                'ssl_cert': self.tls_config.get('client_cert'),
+                'ssl_key': self.tls_config.get('client_key'),
+                'ssl_verify_cert': self.tls_config.get('verify_server_cert', True),
+            }
+
+            tls_versions = self.tls_config.get('tls_versions', ['TLSv1.2', 'TLSv1.3'])
+            if tls_versions:
+                ssl_args['tls_versions'] = tls_versions
+
+            conn_args.update({key: value for key, value in ssl_args.items() if value is not None})
+
+        try:
+            self._connection = mysql.connector.connect(**conn_args)
+        except mysql.connector.Error as e:
+            if self.tls_config.get('enabled') and "SSL is required" in str(e):
+                raise mysql.connector.Error(
+                    f"TLS is enabled in configuration but StarRocks server doesn't support it. "
+                    f"Error: {e}. "
+                    f"To fix this, you need to enable TLS/SSL in your StarRocks server configuration. "
+                    f"Alternatively, set 'enabled: false' in the tls section of your config file."
+                ) from e
+            raise
     
     def close(self) -> None:
         """Close database connection."""
@@ -85,4 +121,34 @@ class StarRocksDB:
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Context manager exit."""
         self.close()
+    
+    @property
+    def timezone(self) -> str:
+        """Get the StarRocks cluster timezone.
+        
+        Queries the cluster timezone on first access and caches it for subsequent use.
+        If the query fails (e.g., database unavailable, connection error, permissions),
+        defaults to 'UTC' to ensure the property always returns a valid timezone string.
+        
+        Returns:
+            Timezone string (e.g., 'Asia/Shanghai', 'UTC', '+08:00')
+            Defaults to 'UTC' if query fails or returns no results.
+        """
+        if self._timezone is None:
+            try:
+                query = "SHOW VARIABLES LIKE 'time_zone'"
+                rows = self.query(query)
+                
+                if not rows:
+                    self._timezone = "UTC"
+                else:
+                    row = rows[0]
+                    if isinstance(row, dict):
+                        self._timezone = row.get("Value", "UTC")
+                    else:
+                        self._timezone = row[1] if len(row) > 1 else "UTC"
+            except Exception:
+                self._timezone = "UTC"
+        
+        return self._timezone
 

starrocks_br/executor.py

@@ -1,23 +1,68 @@
 import time
 import datetime
-from typing import Dict, Literal, Optional
-from . import history, concurrency, logger
+import re
+from typing import Dict, Literal, Optional, Tuple
+from . import history, concurrency, logger, timezone
 
-MAX_POLLS = 21600 # 6 hours
+MAX_POLLS = 86400 # 1 day
 
-def submit_backup_command(db, backup_command: str) -> tuple[bool, Optional[str]]:
+def submit_backup_command(db, backup_command: str) -> Tuple[bool, Optional[str], Optional[Dict[str, str]]]:
     """Submit a backup command to StarRocks.
     
-    Returns (success, error_message).
+    Returns (success, error_message, error_details).
+    error_details is a dict with keys like 'error_type' and 'snapshot_name' for specific error cases.
     """
     try:
         db.execute(backup_command.strip())
-        return True, None
+        return True, None, None
     except Exception as e:
-        error_msg = f"Failed to submit backup command: {type(e).__name__}: {str(e)}"
+        error_str = str(e)
+        error_type = type(e).__name__
+        
+        snapshot_exists_match = _check_snapshot_exists_error(e, error_str)
+        if snapshot_exists_match:
+            snapshot_name = snapshot_exists_match
+            error_details = {
+                'error_type': 'snapshot_exists',
+                'snapshot_name': snapshot_name
+            }
+            error_msg = f"Snapshot '{snapshot_name}' already exists in repository"
+            logger.error(error_msg)
+            logger.error(f"backup_command: {backup_command}")
+            return False, error_msg, error_details
+        
+        error_msg = f"Failed to submit backup command: {error_type}: {error_str}"
         logger.error(error_msg)
         logger.error(f"backup_command: {backup_command}")
-        return False, error_msg
+        return False, error_msg, None
+
+
+def _check_snapshot_exists_error(exception: Exception, error_str: str) -> Optional[str]:
+    """Check if the error is a 'snapshot already exists' error and extract snapshot name.
+    
+    Args:
+        exception: The exception that was raised
+        error_str: String representation of the error
+        
+    Returns:
+        Snapshot name if this is a snapshot exists error, None otherwise
+    """
+    snapshot_name_pattern = r"Snapshot with name '([^']+)' already exist"
+    error_lower = error_str.lower()
+    
+    is_snapshot_exists_error = (
+        "already exist" in error_lower or 
+        "already exists" in error_lower or
+        ("5064" in error_str and "already exist" in error_lower) or
+        (hasattr(exception, 'errno') and exception.errno == 5064)
+    )
+    
+    if is_snapshot_exists_error:
+        match = re.search(snapshot_name_pattern, error_str, re.IGNORECASE)
+        if match:
+            return match.group(1)
+    
+    return None
 
 
 def poll_backup_status(db, label: str, database: str, max_polls: int = MAX_POLLS, poll_interval: float = 1.0) -> Dict[str, str]:
@@ -117,15 +162,19 @@ def execute_backup(
     if not database:
         database = _extract_database_from_command(backup_command)
 
-    started_at = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    cluster_tz = db.timezone
+    started_at = timezone.get_current_time_in_cluster_tz(cluster_tz)
     
-    success, submit_error = submit_backup_command(db, backup_command)
+    success, submit_error, error_details = submit_backup_command(db, backup_command)
     if not success:
-        return {
+        result = {
             "success": False,
             "final_status": None,
             "error_message": submit_error or "Failed to submit backup command (unknown error)"
         }
+        if error_details:
+            result["error_details"] = error_details
+        return result
     
     try:
         final_status = poll_backup_status(db, label, database, max_polls, poll_interval)
@@ -133,6 +182,7 @@ def execute_backup(
         success = final_status["state"] == "FINISHED"
 
         try:
+            finished_at = timezone.get_current_time_in_cluster_tz(cluster_tz)
             history.log_backup(
                 db,
                 {
@@ -141,7 +191,7 @@ def execute_backup(
                     "status": final_status["state"],
                     "repository": repository,
                     "started_at": started_at,
-                    "finished_at": datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                    "finished_at": finished_at,
                     "error_message": None if success else (final_status["state"] or ""),
                 },
             )

starrocks_br/planner.py

@@ -1,6 +1,7 @@
 from typing import List, Dict, Optional
+import datetime
 
-from starrocks_br import logger
+from starrocks_br import logger, timezone
 
 
 def find_latest_full_backup(db, database: str) -> Optional[Dict[str, str]]:
@@ -11,7 +12,8 @@ def find_latest_full_backup(db, database: str) -> Optional[Dict[str, str]]:
         database: Database name to search for
         
     Returns:
-        Dictionary with keys: label, backup_type, finished_at, or None if no full backup found
+        Dictionary with keys: label, backup_type, finished_at, or None if no full backup found.
+        The finished_at value is returned as a string in the cluster timezone format.
     """
     query = f"""
     SELECT label, backup_type, finished_at
@@ -29,10 +31,18 @@ def find_latest_full_backup(db, database: str) -> Optional[Dict[str, str]]:
         return None
     
     row = rows[0]
+    finished_at = row[2]
+    
+    if isinstance(finished_at, datetime.datetime):
+        cluster_tz = db.timezone
+        finished_at = finished_at.strftime("%Y-%m-%d %H:%M:%S")
+    elif not isinstance(finished_at, str):
+        finished_at = str(finished_at)
+    
     return {
         "label": row[0],
         "backup_type": row[1],
-        "finished_at": row[2]
+        "finished_at": finished_at
     }
 
 
@@ -66,6 +76,8 @@ def find_recent_partitions(db, database: str, baseline_backup_label: Optional[st
     Returns list of dictionaries with keys: database, table, partition_name.
     Only partitions of tables within the specified database are returned.
     """
+    cluster_tz = db.timezone
+    
     if baseline_backup_label:
         baseline_query = f"""
         SELECT finished_at
@@ -76,17 +88,21 @@ def find_recent_partitions(db, database: str, baseline_backup_label: Optional[st
         baseline_rows = db.query(baseline_query)
         if not baseline_rows:
             raise ValueError(f"Baseline backup '{baseline_backup_label}' not found or not successful")
-        baseline_time = baseline_rows[0][0]
+        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.")
-        baseline_time = latest_backup['finished_at']
+        baseline_time_raw = latest_backup['finished_at']
     
-    if isinstance(baseline_time, str):
-        threshold_str = baseline_time
+    if isinstance(baseline_time_raw, datetime.datetime):
+        baseline_time_str = baseline_time_raw.strftime("%Y-%m-%d %H:%M:%S")
+    elif isinstance(baseline_time_raw, str):
+        baseline_time_str = baseline_time_raw
     else:
-        threshold_str = baseline_time.strftime("%Y-%m-%d %H:%M:%S")
+        baseline_time_str = str(baseline_time_raw)
+    
+    baseline_dt = timezone.parse_datetime_with_tz(baseline_time_str, cluster_tz)
     
     group_tables = find_tables_by_group(db, group_name)
 
@@ -129,12 +145,16 @@ def find_recent_partitions(db, database: str, baseline_backup_label: Optional[st
             partition_name = row[1]
             visible_version_time = row[3]
 
-            if isinstance(visible_version_time, str):
-                version_time_str = visible_version_time
+            if isinstance(visible_version_time, datetime.datetime):
+                visible_version_time_str = visible_version_time.strftime("%Y-%m-%d %H:%M:%S")
+            elif isinstance(visible_version_time, str):
+                visible_version_time_str = visible_version_time
             else:
-                version_time_str = visible_version_time.strftime("%Y-%m-%d %H:%M:%S")
+                visible_version_time_str = str(visible_version_time)
+            
+            visible_version_dt = timezone.parse_datetime_with_tz(visible_version_time_str, cluster_tz)
             
-            if version_time_str > threshold_str:
+            if visible_version_dt > baseline_dt:
                 recent_partitions.append({
                     'database': db_name,
                     'table': table_name,

starrocks_br/restore.py

@@ -3,7 +3,7 @@ import datetime
 from typing import Dict, List, Optional
 from . import history, concurrency, logger
 
-MAX_POLLS = 21600 # 6 hours
+MAX_POLLS = 86400 # 1 day
 
 def get_snapshot_timestamp(db, repo_name: str, snapshot_name: str) -> str:
     """Get the backup timestamp for a specific snapshot from the repository.
@@ -281,17 +281,30 @@ def find_restore_pair(db, target_label: str) -> List[str]:
     raise ValueError(f"Unknown backup type '{target_info['backup_type']}' for label '{target_label}'")
 
 
-def get_tables_from_backup(db, label: str, group: Optional[str] = None) -> List[str]:
+def get_tables_from_backup(db, label: str, group: Optional[str] = None, table: Optional[str] = None, database: Optional[str] = None) -> List[str]:
     """Get list of tables to restore from backup manifest.
     
     Args:
         db: Database connection
         label: Backup label
         group: Optional inventory group to filter tables
+        table: Optional table name to filter (single table, database comes from database parameter)
+        database: Database name (required if table is specified)
         
     Returns:
-        List of table names to restore
+        List of table names to restore (format: database.table)
+        
+    Raises:
+        ValueError: If both group and table are specified
+        ValueError: If table is specified but database is not provided
+        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.")
+    
+    if table and not database:
+        raise ValueError("database parameter is required when table is specified")
+    
     query = f"""
     SELECT DISTINCT database_name, table_name
     FROM ops.backup_partitions
@@ -305,6 +318,15 @@ def get_tables_from_backup(db, label: str, group: Optional[str] = None) -> List[
     
     tables = [f"{row[0]}.{row[1]}" for row in rows]
     
+    if table:
+        target_table = f"{database}.{table}"
+        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}'")
+        
+        return filtered_tables
+    
     if group:
         group_query = f"""
         SELECT database_name, table_name
@@ -316,14 +338,26 @@ def get_tables_from_backup(db, label: str, group: Optional[str] = None) -> List[
         if not group_rows:
             return []
         
-        group_tables = {f"{row[0]}.{row[1]}" for row in group_rows}
+        group_tables = set()
+        for row in group_rows:
+            database_name, table_name = row[0], row[1]
+            if table_name == '*':
+                show_tables_query = f"SHOW TABLES FROM {database_name}"
+                try:
+                    tables_rows = db.query(show_tables_query)
+                    for table_row in tables_rows:
+                        group_tables.add(f"{database_name}.{table_row[0]}")
+                except Exception:
+                    continue
+            else:
+                group_tables.add(f"{database_name}.{table_name}")
         
         tables = [table for table in tables if table in group_tables]
     
     return tables
 
 
-def execute_restore_flow(db, repo_name: str, restore_pair: List[str], tables_to_restore: List[str], rename_suffix: str = "_restored") -> Dict:
+def execute_restore_flow(db, repo_name: str, restore_pair: List[str], tables_to_restore: List[str], rename_suffix: str = "_restored", skip_confirmation: bool = False) -> Dict:
     """Execute the complete restore flow with safety measures.
     
     Args:
@@ -332,6 +366,7 @@ def execute_restore_flow(db, repo_name: str, restore_pair: List[str], tables_to_
         restore_pair: List of backup labels in restore order
         tables_to_restore: List of tables to restore (format: database.table)
         rename_suffix: Suffix for temporary tables
+        skip_confirmation: If True, skip interactive confirmation prompt
         
     Returns:
         Dictionary with success status and details
@@ -358,12 +393,15 @@ def execute_restore_flow(db, repo_name: str, restore_pair: List[str], tables_to_
     logger.info("This will restore data to temporary tables and then perform atomic rename.")
     logger.warning("WARNING: This operation will replace existing tables!")
     
-    confirmation = input("\nDo you want to proceed? [Y/n]: ").strip()
-    if confirmation.lower() != 'y':
-        return {
-            "success": False,
-            "error_message": "Restore operation cancelled by user"
-        }
+    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"
+            }
+    else:
+        logger.info("Proceeding automatically (--yes flag provided)")
     
     try:
         database_name = tables_to_restore[0].split('.')[0]
@@ -470,6 +508,19 @@ def _build_restore_command_without_rename(backup_label: str, repo_name: str, tab
     PROPERTIES ("backup_timestamp" = "{backup_timestamp}")"""
 
 
+def _generate_timestamped_backup_name(table_name: str) -> str:
+    """Generate a timestamped backup table name.
+    
+    Args:
+        table_name: Original table name
+        
+    Returns:
+        Timestamped backup name in format: {table_name}_backup_YYYYMMDD_HHMMSS
+    """
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    return f"{table_name}_backup_{timestamp}"
+
+
 def _perform_atomic_rename(db, tables: List[str], rename_suffix: str) -> Dict:
     """Perform atomic rename of temporary tables to make them live."""
     try:
@@ -477,8 +528,9 @@ def _perform_atomic_rename(db, tables: List[str], rename_suffix: str) -> Dict:
         for table in tables:
             database, table_name = table.split('.', 1)
             temp_table_name = f"{table_name}{rename_suffix}"
+            backup_table_name = _generate_timestamped_backup_name(table_name)
             
-            rename_statements.append(f"ALTER TABLE {database}.{table_name} RENAME {table_name}_backup")
+            rename_statements.append(f"ALTER TABLE {database}.{table_name} RENAME {backup_table_name}")
             rename_statements.append(f"ALTER TABLE {database}.{temp_table_name} RENAME {table_name}")
         
         for statement in rename_statements:

starrocks_br/schema.py

@@ -120,7 +120,7 @@ def get_run_status_schema() -> str:
     CREATE TABLE IF NOT EXISTS ops.run_status (
         scope STRING NOT NULL COMMENT "Job scope: backup or restore",
         label STRING NOT NULL COMMENT "Job label or identifier",
-        state STRING NOT NULL DEFAULT "ACTIVE" COMMENT "Job state: ACTIVE or COMPLETED",
+        state STRING NOT NULL DEFAULT "ACTIVE" COMMENT "Job state: ACTIVE, FINISHED, FAILED, or CANCELLED",
         started_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT "Job start timestamp",
         finished_at DATETIME COMMENT "Job completion timestamp"
     )

starrocks_br/timezone.py

@@ -0,0 +1,125 @@
+import datetime
+from typing import Union
+from zoneinfo import ZoneInfo
+
+
+def get_current_time_in_cluster_tz(cluster_tz: str) -> str:
+    """Get current time formatted in cluster timezone.
+    
+    Args:
+        cluster_tz: Timezone string (e.g., 'Asia/Shanghai', 'UTC', '+08:00')
+        
+    Returns:
+        Formatted datetime string in 'YYYY-MM-DD HH:MM:SS' format in the cluster timezone
+    """
+    tz = _get_timezone(cluster_tz)
+    now = datetime.datetime.now(tz)
+    return now.strftime("%Y-%m-%d %H:%M:%S")
+
+
+def parse_datetime_with_tz(dt_str: str, tz: str) -> datetime.datetime:
+    """Parse datetime string assuming the given timezone.
+    
+    Args:
+        dt_str: Datetime string in 'YYYY-MM-DD HH:MM:SS' format
+        tz: Timezone string (e.g., 'Asia/Shanghai', 'UTC', '+08:00')
+        
+    Returns:
+        Timezone-aware datetime object
+    """
+    timezone = _get_timezone(tz)
+    
+    dt = datetime.datetime.strptime(dt_str, "%Y-%m-%d %H:%M:%S")
+    dt = dt.replace(tzinfo=timezone)
+    
+    return dt
+
+
+def normalize_datetime_to_tz(dt: datetime.datetime, target_tz: str) -> datetime.datetime:
+    """Convert datetime to target timezone.
+    
+    Args:
+        dt: Datetime object (timezone-aware or naive)
+        target_tz: Target timezone string (e.g., 'Asia/Shanghai', 'UTC', '+08:00')
+        
+    Returns:
+        Timezone-aware datetime object in the target timezone
+    """
+    timezone = _get_timezone(target_tz)
+    
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=datetime.timezone.utc)
+    
+    dt = dt.astimezone(timezone)
+    
+    return dt
+
+
+def _get_timezone(tz_str: str) -> Union[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').
+    
+    Args:
+        tz_str: Timezone string
+        
+    Returns:
+        ZoneInfo or timezone object
+    """
+    tz_str = tz_str.strip()
+    
+    if tz_str.upper() == "UTC" or tz_str == "+00:00" or tz_str == "-00:00":
+        return ZoneInfo("UTC")
+    
+    if tz_str.startswith(("+", "-")):
+        try:
+            hours, minutes = _parse_offset(tz_str)
+            offset = datetime.timedelta(hours=hours, minutes=minutes)
+            return datetime.timezone(offset)
+        except ValueError:
+            return ZoneInfo("UTC")
+    
+    try:
+        return ZoneInfo(tz_str)
+    except Exception:
+        return ZoneInfo("UTC")
+
+
+def _parse_offset(offset_str: str) -> tuple[int, int]:
+    """Parse timezone offset string to hours and minutes.
+    
+    Args:
+        offset_str: Offset string in format '+HH:MM' or '-HH:MM'
+        
+    Returns:
+        Tuple of (hours, minutes)
+        
+    Raises:
+        ValueError: If offset string is invalid, including:
+            - String length < 6 characters
+            - Invalid format (missing colon, invalid characters)
+            - Hours >= 24 or < 0
+            - Minutes >= 60 or < 0
+    """
+    if len(offset_str) < 6:
+        raise ValueError(f"Invalid offset format: {offset_str}")
+    
+    if offset_str[3] != ':':
+        raise ValueError(f"Invalid offset format: {offset_str} (missing colon)")
+    
+    sign = 1 if offset_str[0] == '+' else -1
+    
+    try:
+        hours = int(offset_str[1:3])
+        minutes = int(offset_str[4:6])
+    except ValueError as e:
+        raise ValueError(f"Invalid offset format: {offset_str} (non-numeric values)") from e
+    
+    if hours < 0 or hours >= 24:
+        raise ValueError(f"Invalid offset format: {offset_str} (hours must be 00-23)")
+    
+    if minutes < 0 or minutes >= 60:
+        raise ValueError(f"Invalid offset format: {offset_str} (minutes must be 00-59)")
+    
+    return sign * hours, sign * minutes
+

{starrocks_br-0.1.0.dist-info → starrocks_br-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starrocks-br
-Version: 0.1.0
+Version: 0.2.0
 Summary: StarRocks Backup and Restore automation tool
 Requires-Python: >=3.9
 Requires-Dist: click<9,>=8.1.7

starrocks_br-0.2.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+starrocks_br/__init__.py,sha256=i1m0FIl2IAXaVyNoya0ZNAx3WfhIp9I6VLhTz06qNFY,28
+starrocks_br/cli.py,sha256=3FvtMDYra6_9CwxSWj3i4VcIjHlSDO9LbBwC0-Bh8bc,20550
+starrocks_br/concurrency.py,sha256=wx69u-RW1OnukKn6CQ9EJS4L42N9Gzw7Xz7rgETzmy4,5934
+starrocks_br/config.py,sha256=nL57JR4O1WBG6iOscuCX5aui7lOs6PIiS97MIgVDvOM,2036
+starrocks_br/db.py,sha256=UDmN8uIYTMzxx7_D0XxmYSpH3VTwBKEeBNQ-4hI4SnA,5098
+starrocks_br/executor.py,sha256=I9cefPbHaSiajPvoYBVaRXM06UfP6jzVRdS8q_t5zeE,10681
+starrocks_br/health.py,sha256=DpTy4uqk1UrbV0d9Wtk9Ke9K0iT4ndL-01gqqSywR_c,1050
+starrocks_br/history.py,sha256=j6eqkD1MyTvgoztffnLnr6-6VXd0gdvLxLLKxbC1AG0,3016
+starrocks_br/labels.py,sha256=D67JqIUWtFAnuj9thnC4Y7A0tzLk6d4YpBtDGhen1yc,1689
+starrocks_br/logger.py,sha256=QTfr-nC3TdeU7f1gcRTRDAQSLYpwaevd_iT1B_RbuF8,900
+starrocks_br/planner.py,sha256=_e65v5XRoXKJcLPX73UXKtA721TWjw2Txfet-TItXu8,10326
+starrocks_br/repository.py,sha256=6uTJBYgQFEjJBlfhirriTkad80teTPcBSl_tphUExz4,1269
+starrocks_br/restore.py,sha256=_OzlQjPFkH7ySgFSSbpYZHY3A_U1Jz3-UKTwGl2AiQw,18965
+starrocks_br/schema.py,sha256=s_BAUhNgfQscRzhj-OB4xmp19CYZ0ZElyBfdht0_OSE,6114
+starrocks_br/timezone.py,sha256=ONaudOgIfzPdJpZyIUSh0HF5D7oPQAtungNoUqtGM6M,3738
+starrocks_br-0.2.0.dist-info/METADATA,sha256=RnBcIZXdCArx1rXruABPf735XJjb3ZB1jy-egUrKBy0,419
+starrocks_br-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+starrocks_br-0.2.0.dist-info/entry_points.txt,sha256=AKUt01G2MAlh85s1Q9kNQDOUio14kaTnT3dmg9gjdNg,54
+starrocks_br-0.2.0.dist-info/top_level.txt,sha256=CU1tGVo0kjulhDr761Sndg-oTeRKsisDnWm8UG95aBE,13
+starrocks_br-0.2.0.dist-info/RECORD,,

starrocks_br-0.1.0.dist-info/RECORD

@@ -1,19 +0,0 @@
-starrocks_br/__init__.py,sha256=i1m0FIl2IAXaVyNoya0ZNAx3WfhIp9I6VLhTz06qNFY,28
-starrocks_br/cli.py,sha256=VrLLyvyAop687KNJnXIJhxL7EgVPzutQTAOJz4ANZMw,15969
-starrocks_br/concurrency.py,sha256=wx69u-RW1OnukKn6CQ9EJS4L42N9Gzw7Xz7rgETzmy4,5934
-starrocks_br/config.py,sha256=btmsf43IuxPIraFxJRScuHW-B3Bv7CPO7y43xn2b2cM,1047
-starrocks_br/db.py,sha256=whbkM5LVLNNauPDuSFXOXWuTOFWHBVsNai74O7bIUAg,2450
-starrocks_br/executor.py,sha256=_lbJQ6KjV7Jg5eYbSLZhvvYj-EM5kBV6lM3Lah9h6-U,8748
-starrocks_br/health.py,sha256=DpTy4uqk1UrbV0d9Wtk9Ke9K0iT4ndL-01gqqSywR_c,1050
-starrocks_br/history.py,sha256=j6eqkD1MyTvgoztffnLnr6-6VXd0gdvLxLLKxbC1AG0,3016
-starrocks_br/labels.py,sha256=D67JqIUWtFAnuj9thnC4Y7A0tzLk6d4YpBtDGhen1yc,1689
-starrocks_br/logger.py,sha256=QTfr-nC3TdeU7f1gcRTRDAQSLYpwaevd_iT1B_RbuF8,900
-starrocks_br/planner.py,sha256=wnFMbIQhY9dVaoRjmzB3DypPMEXQam94TFenwGhMGGk,9414
-starrocks_br/repository.py,sha256=6uTJBYgQFEjJBlfhirriTkad80teTPcBSl_tphUExz4,1269
-starrocks_br/restore.py,sha256=IPs8EzIS_7iTUMkKJV32YJvb4b0MTXpLgZmUWhnzPXo,16672
-starrocks_br/schema.py,sha256=_cFzD3Bnvb1WDlLzmFXuMSinLjiXKmLbJ9uUhyOCKK4,6095
-starrocks_br-0.1.0.dist-info/METADATA,sha256=u1ivetyaj0El_v_5Iy9WmJ4_KsEmhU8GUSy3T7Hb4xQ,419
-starrocks_br-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-starrocks_br-0.1.0.dist-info/entry_points.txt,sha256=AKUt01G2MAlh85s1Q9kNQDOUio14kaTnT3dmg9gjdNg,54
-starrocks_br-0.1.0.dist-info/top_level.txt,sha256=CU1tGVo0kjulhDr761Sndg-oTeRKsisDnWm8UG95aBE,13
-starrocks_br-0.1.0.dist-info/RECORD,,