# deep-bi/starrocks-backup-and-restore architecture

> Architecture diagram of the GitHub repository deep-bi/starrocks-backup-and-restore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deep-bi/starrocks-backup-and-restore
- Repository: https://github.com/deep-bi/starrocks-backup-and-restore

## Overview

StarRocks Backup & Restore is a CLI tool for full and incremental backups, restore-chain selection, and backup retention management. The user configures a StarRocks connection and inventory groups, initializes the ops metadata schema, then invokes backup, restore, or prune commands. For backups, the CLI coordinates partition planning, concurrency control, and StarRocks job execution; restore resolves the requested backup chain and performs a temporary-table restore with atomic rename. The graph reflects README capabilities and shown imports/calls; some module internals were not sampled, so unverified relationships are omitted.

Main entry points: [`src/starrocks_br/cli.py`](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/cli.py) (Command interface), [`src/starrocks_br/db.py`](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/db.py) (Database client), [`src/starrocks_br/restore.py`](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/restore.py) (Restore planner and executor), [`src/starrocks_br/executor.py`](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/executor.py) (Backup executor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["CLI and setup"]
  node_cli["Command interface<br/>[cli.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_database["Database client<br/>[db.py]"]
  node_repository["Repository check<br/>[repository.py]"]
  node_schema["Ops schema<br/>[schema.py]"]
  node_prune["Backup retention<br/>[prune.py]"]
  node_health["Cluster health<br/>[health.py]"]
end

subgraph group_backup["Backup workflow"]
  node_planner["Partition planner<br/>[planner.py]"]
  node_executor["Backup executor<br/>[executor.py]"]
  node_labels["Backup labels<br/>[labels.py]"]
end

subgraph group_restore["Restore workflow"]
  node_restore["Restore planner and executor<br/>[restore.py]"]
end

subgraph group_metadata["Metadata and operations"]
  node_concurrency["Job concurrency<br/>[concurrency.py]"]
  node_history["Operation history<br/>[history.py]"]
  node_opsdata[("Ops metadata")]
end

subgraph group_shared["Shared internals"]
  node_errors["Error reporting<br/>[error_handler.py]"]
  node_exceptions["Domain exceptions<br/>[exceptions.py]"]
  node_timezone["Timezone handling<br/>[timezone.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_operator(("Operator"))
node_starrocks[("StarRocks cluster")]

node_operator -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_configuration
node_cli -->|"opens connection"| node_database
node_cli -->|"validates repository"| node_repository
node_cli -->|"initializes schema"| node_schema
node_cli -->|"plans backup"| node_planner
node_cli -->|"runs backup"| node_executor
node_cli -->|"starts restore"| node_restore
node_cli -->|"runs retention"| node_prune
node_cli -->|"checks health"| node_health
node_cli -->|"coordinates jobs"| node_concurrency
node_cli -->|"formats failures"| node_errors
node_repository -->|"queries repository"| node_database
node_schema -->|"creates schema"| node_database
node_database -.->|"executes SQL"| node_starrocks
node_planner -->|"reads partitions"| node_database
node_planner -->|"uses time parsing"| node_timezone
node_executor -->|"submits backup"| node_database
node_executor -->|"uses job slots"| node_concurrency
node_executor -->|"logs outcomes"| node_history
node_restore -->|"queries and restores"| node_database
node_restore -->|"uses job slots"| node_concurrency
node_restore -->|"logs outcomes"| node_history
node_restore -->|"uses time parsing"| node_timezone
node_concurrency -->|"tracks active jobs"| node_opsdata
node_history -->|"records operations"| node_opsdata
node_schema -->|"creates metadata store"| node_opsdata
node_cli -->|"generates labels"| node_labels
node_cli -->|"handles domain errors"| node_exceptions
node_executor -->|"reports progress"| node_logger
node_restore -->|"reports progress"| node_logger
node_errors -->|"reads ops settings"| node_configuration

click node_cli "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/cli.py"
click node_configuration "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/config.py"
click node_database "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/db.py"
click node_repository "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/repository.py"
click node_schema "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/schema.py"
click node_planner "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/planner.py"
click node_executor "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/executor.py"
click node_concurrency "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/concurrency.py"
click node_history "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/history.py"
click node_restore "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/restore.py"
click node_prune "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/prune.py"
click node_health "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/health.py"
click node_labels "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/labels.py"
click node_errors "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/error_handler.py"
click node_exceptions "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/exceptions.py"
click node_timezone "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/timezone.py"
click node_logger "https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/logger.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_configuration,node_database,node_repository,node_schema,node_prune,node_health toneBlue
class node_planner,node_executor,node_labels,node_starrocks toneAmber
class node_restore toneMint
class node_concurrency,node_history,node_opsdata toneRose
class node_errors,node_exceptions,node_timezone,node_logger,node_operator toneIndigo
```

## Components

### CLI and setup

- [Command interface](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/cli.py): `src/starrocks_br/cli.py`
- [Configuration](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/config.py): `src/starrocks_br/config.py`
- [Database client](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/db.py): `src/starrocks_br/db.py`
- [Repository check](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/repository.py): `src/starrocks_br/repository.py`
- [Ops schema](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/schema.py): `src/starrocks_br/schema.py`
- [Backup retention](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/prune.py): `src/starrocks_br/prune.py`
- [Cluster health](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/health.py): `src/starrocks_br/health.py`

### Backup workflow

- [Partition planner](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/planner.py): `src/starrocks_br/planner.py`
- [Backup executor](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/executor.py): `src/starrocks_br/executor.py`
- [Backup labels](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/labels.py): `src/starrocks_br/labels.py`

### Restore workflow

- [Restore planner and executor](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/restore.py): `src/starrocks_br/restore.py`

### Metadata and operations

- [Job concurrency](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/concurrency.py): `src/starrocks_br/concurrency.py`
- [Operation history](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/history.py): `src/starrocks_br/history.py`
- **Ops metadata**

### Shared internals

- [Error reporting](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/error_handler.py): `src/starrocks_br/error_handler.py`
- [Domain exceptions](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/exceptions.py): `src/starrocks_br/exceptions.py`
- [Timezone handling](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/timezone.py): `src/starrocks_br/timezone.py`
- [Logging](https://github.com/deep-bi/starrocks-backup-and-restore/blob/main/src/starrocks_br/logger.py): `src/starrocks_br/logger.py`

### Other components

- **Operator**
- **StarRocks cluster**

## Connections

- Operator → Command interface: runs commands (evidence: `README.md`)
- Command interface → Configuration: loads settings (evidence: `src/starrocks_br/cli.py`)
- Command interface → Database client: opens connection (evidence: `src/starrocks_br/cli.py`)
- Command interface → Repository check: validates repository (evidence: `src/starrocks_br/cli.py`)
- Command interface → Ops schema: initializes schema (evidence: `src/starrocks_br/cli.py`)
- Command interface → Partition planner: plans backup (evidence: `src/starrocks_br/cli.py`)
- Command interface → Backup executor: runs backup (evidence: `src/starrocks_br/cli.py`)
- Command interface → Restore planner and executor: starts restore (evidence: `src/starrocks_br/cli.py`)
- Command interface → Backup retention: runs retention (evidence: `src/starrocks_br/cli.py`)
- Command interface → Cluster health: checks health (evidence: `src/starrocks_br/cli.py`)
- Command interface → Job concurrency: coordinates jobs (evidence: `src/starrocks_br/cli.py`)
- Command interface → Error reporting: formats failures (evidence: `src/starrocks_br/cli.py`)
- Repository check → Database client: queries repository (evidence: `src/starrocks_br/repository.py`)
- Ops schema → Database client: creates schema (evidence: `README.md`)
- Database client → StarRocks cluster: executes SQL
- Partition planner → Database client: reads partitions (evidence: `src/starrocks_br/planner.py`)
- Partition planner → Timezone handling: uses time parsing (evidence: `src/starrocks_br/planner.py`)
- Backup executor → Database client: submits backup (evidence: `src/starrocks_br/executor.py`)
- Backup executor → Job concurrency: uses job slots (evidence: `src/starrocks_br/executor.py`)
- Backup executor → Operation history: logs outcomes (evidence: `src/starrocks_br/executor.py`)
- Restore planner and executor → Database client: queries and restores (evidence: `src/starrocks_br/restore.py`)
- Restore planner and executor → Job concurrency: uses job slots (evidence: `src/starrocks_br/restore.py`)
- Restore planner and executor → Operation history: logs outcomes (evidence: `src/starrocks_br/restore.py`)
- Restore planner and executor → Timezone handling: uses time parsing (evidence: `src/starrocks_br/restore.py`)
- Job concurrency → Ops metadata: tracks active jobs (evidence: `src/starrocks_br/concurrency.py`)
- Operation history → Ops metadata: records operations (evidence: `src/starrocks_br/history.py`)
- Ops schema → Ops metadata: creates metadata store (evidence: `README.md`)
- Command interface → Backup labels: generates labels (evidence: `src/starrocks_br/cli.py`)
- Command interface → Domain exceptions: handles domain errors (evidence: `src/starrocks_br/cli.py`)
- Backup executor → Logging: reports progress (evidence: `src/starrocks_br/executor.py`)
- Restore planner and executor → Logging: reports progress (evidence: `src/starrocks_br/restore.py`)
- Error reporting → Configuration: reads ops settings (evidence: `src/starrocks_br/error_handler.py`)
