Backup & Restore
RAMP includes a dedicated CLI tool (RAMP.Cli) for backup and disaster recovery. The CLI supports full and partial backups in multiple formats, validation before restore, and two restore modes (overwrite and copy). It operates directly against the RAMP database and produces self-contained backup files.
CLI Overview
Section titled “CLI Overview”The RAMP CLI (ramp-cli) provides four commands:
| Command | Description |
|---|---|
list | Display the entity hierarchy (systems, stages, templates, versions, instances) |
backup | Create a full or partial backup |
validate | Validate a backup file before restoring |
restore | Restore data from a backup file |
Installation and Configuration
Section titled “Installation and Configuration”The CLI is built as part of the RAMP solution (src/RAMP.Cli). It connects to the same database as the RAMP API using the connection string from appsettings.json.
# Build the CLIcd src/RAMP.Clidotnet build
# Run the CLIdotnet run -- <command> [options]
# View helpdotnet run -- --helpEntity Hierarchy
Section titled “Entity Hierarchy”RAMP data follows a hierarchical structure. Understanding this hierarchy is important for partial backups and restores.
System └── Stage └── (Instances are linked to Stages)
Template └── Template Version └── Steps, Variables └── Instance └── Instance Steps, Instance Variables, AttachmentsWhen backing up or restoring a specific entity, RAMP automatically includes all child entities in the hierarchy. For example, backing up a System includes its Stages, and backing up a Template includes all its Versions.
Viewing the Hierarchy
Section titled “Viewing the Hierarchy”Use the list command to explore the entity hierarchy before creating backups:
# List entire hierarchyramp-cli list
# List from a specific entityramp-cli list --type system --id <system-guid>
# Expand all nodesramp-cli list --expandThe output displays a tree view with color-coded entity types and child counts.
Backup Formats
Section titled “Backup Formats”RAMP supports three backup formats:
| Format | Extension | Description | Best For |
|---|---|---|---|
| JSON | .json | Human-readable JSON file with all data inline | Small backups, inspection, programmatic processing |
| ZIP | .zip | Compressed archive with JSON data and attachment files stored separately | Backups with large attachments |
| SQLite | .sqlite | Portable SQLite database file | Large backups, offline querying |
Creating Backups
Section titled “Creating Backups”Full Backup
Section titled “Full Backup”A full backup captures all data in the RAMP database: systems, stages, templates, versions, instances, steps, variables, attachments, and user/group/category references.
ramp-cli backup full --output <path> [--format <format>]| Option | Alias | Required | Default | Description |
|---|---|---|---|---|
--output | -o | Yes | — | Output file path |
--format | -f | No | Json | Backup format: Json, Zip, or Sqlite |
Example:
# Full backup in JSON formatramp-cli backup full --output /backups/ramp-full-2026-03-09.json
# Full backup in ZIP format (recommended for large databases)ramp-cli backup full --output /backups/ramp-full-2026-03-09.zip --format ZipAfter completion, the CLI displays a summary table showing entity counts:
Entity Type Count──────────────────────Systems 3Stages 12Templates 45Versions 89Instances 234User References 156Category Refs 18Partial Backup (Object Backup)
Section titled “Partial Backup (Object Backup)”A partial backup captures a specific entity and all its children in the hierarchy.
ramp-cli backup object --type <entity-type> --id <guid> --output <path> [--format <format>]| Option | Alias | Required | Default | Description |
|---|---|---|---|---|
--type | -t | Yes | — | Entity type: system, stage, template, version, instance |
--id | -i | Yes | — | Entity GUID |
--output | -o | Yes | — | Output file path |
--format | -f | No | Json | Backup format: Json, Zip, or Sqlite |
Examples:
# Backup a single instanceramp-cli backup object --type instance --id a1b2c3d4-... --output instance-backup.json
# Backup a system and all its stagesramp-cli backup object --type system --id e5f6a7b8-... --output system-backup.zip --format Zip
# Backup a template with all versions and instancesramp-cli backup object --type template --id c9d0e1f2-... --output template-backup.jsonWhat Is Included in Partial Backups
Section titled “What Is Included in Partial Backups”| Starting Entity | Includes |
|---|---|
| System | The system + all its stages |
| Stage | The stage + reference to its parent system |
| Template | The template + all versions + steps + variables |
| Version | The version + all steps + variables + reference to parent template |
| Instance | The instance + all instance steps + instance variables + attachments + references to parent version and stage |
Each backup also includes reference data — minimal information (IDs and names) for users, groups, and categories that are referenced by the backed-up entities. This enables the restore process to create placeholder records when the original users or groups do not exist in the target system.
Backup Manifest
Section titled “Backup Manifest”Every backup file contains a manifest with metadata about the backup:
| Field | Description |
|---|---|
| Version | Backup format version (currently “1.0”) |
| Created At | Timestamp when the backup was created |
| Created By | User or system that initiated the backup |
| Type | Full or Partial |
| Format | Json, Zip, or Sqlite |
| Root Object Type | For partial backups: the entity type that was backed up |
| Root Object ID | For partial backups: the GUID of the entity that was backed up |
| Contents | Summary of all entities included in the backup |
Validating Backups
Section titled “Validating Backups”Before restoring, you can validate a backup file to check for potential issues.
ramp-cli validate --input <path> [--mode <mode>]| Option | Alias | Required | Default | Description |
|---|---|---|---|---|
--input | -i | Yes | — | Path to the backup file |
--mode | -m | No | Copy | Restore mode to validate for: Overwrite or Copy |
Validation Checks
Section titled “Validation Checks”The validate command performs the following checks:
- File integrity: Backup file can be read and parsed correctly
- Schema validation: All required fields are present and correctly typed
- Reference integrity: Referenced entities (users, systems, templates) exist in the target database (for Overwrite mode)
- ID conflicts: For Overwrite mode, checks whether existing entities would be overwritten
Validation Output
Section titled “Validation Output”Backup Information┌──────────────┬─────────────────────────────┐│ Property │ Value │├──────────────┼─────────────────────────────┤│ Backup Type │ Partial ││ Created At │ 2026-03-09 14:30:00 ││ Created By │ admin ││ Format │ Json ││ Root Object │ Template │└──────────────┴─────────────────────────────┘
Validation passed!If validation fails, the output lists specific errors and warnings, with a suggestion to try the alternative restore mode.
Restoring from Backup
Section titled “Restoring from Backup”The restore command imports data from a backup file into the RAMP database.
ramp-cli restore --input <path> [--mode <mode>] [--dry-run] [--dummy-prefix <prefix>]| Option | Alias | Required | Default | Description |
|---|---|---|---|---|
--input | -i | Yes | — | Path to the backup file |
--mode | -m | No | Copy | Restore mode: Overwrite or Copy |
--dry-run | — | No | false | Validate only, make no changes |
--dummy-prefix | — | No | [RESTORED] | Prefix for dummy parent entity names |
Restore Modes
Section titled “Restore Modes”RAMP provides two restore modes that determine how entity IDs are handled during import.
Copy Mode
Section titled “Copy Mode”Behavior: All entities receive new GUIDs. Original IDs are discarded and remapped.
Advantages:
- Always works, regardless of what exists in the target database
- No risk of overwriting existing data
- Creates dummy parent entities if the original parents are not present
Use cases:
- Cloning data to a different environment
- Restoring data alongside existing records
- Migrating data between separate RAMP installations
Dummy parents: When restoring a partial backup (e.g., an instance) and the parent entity (e.g., template version, stage) does not exist in the target database, RAMP creates a placeholder parent with the name prefix [RESTORED]. These dummy parents ensure referential integrity.
ramp-cli restore --input backup.json --mode Copy
# Custom prefix for dummy parentsramp-cli restore --input backup.json --mode Copy --dummy-prefix "[IMPORTED]"Overwrite Mode
Section titled “Overwrite Mode”Behavior: Entities are restored with their original GUIDs. If an entity with the same ID already exists, it is overwritten.
Advantages:
- Preserves original IDs and relationships
- True disaster recovery — restores to exact previous state
Requirements:
- All referenced parent entities must exist in the target database
- Fails if required references are missing (use Copy mode as a fallback)
Use cases:
- Disaster recovery to the same database
- Restoring after accidental deletion
- Rolling back to a previous state
ramp-cli restore --input backup.json --mode OverwriteDry Run
Section titled “Dry Run”Use --dry-run to validate the restore without making any changes:
ramp-cli restore --input backup.json --mode Overwrite --dry-runThe dry run performs all validation checks and reports what would be restored, including entity counts and any warnings, without modifying the database.
Restore Output
Section titled “Restore Output”After a successful restore, the CLI displays statistics:
Restore completed!
Entity Type Count───────────────────────────Systems 1Stages 4Templates 3Versions 6Instances 12Steps 148Variables 36Dummy Parents Created 2
ID mappings created: 210Old IDs -> New IDs have been remappedWarnings
Section titled “Warnings”The restore process may generate warnings for non-critical issues:
- Missing user references: Users referenced in the backup do not exist in the target database
- Missing category references: Categories referenced in the backup do not exist
- Dummy parents created: Placeholder entities were created for missing parent references
Errors
Section titled “Errors”If the restore fails, the CLI displays specific error messages:
- Missing required references: In Overwrite mode, a required parent entity does not exist
- Schema mismatch: The backup format version is incompatible with the current RAMP version
- Data integrity violations: Foreign key constraints would be violated
Hierarchical Backup Strategy
Section titled “Hierarchical Backup Strategy”For comprehensive disaster recovery, back up data at the System level. This captures the entire hierarchy:
System Backup ├── System metadata ├── All Stages ├── All Templates (linked to this system) │ ├── All Versions │ │ ├── Steps │ │ └── Variables │ └── All Instances │ ├── Instance Steps │ ├── Instance Variables │ └── Attachments └── User and Category referencesRecommended Backup Schedule
Section titled “Recommended Backup Schedule”| Backup Type | Frequency | Retention | Format |
|---|---|---|---|
| Full backup | Weekly | 4 weeks | ZIP |
| System-level backup | Daily | 2 weeks | ZIP |
| Instance backup (after completion) | Per instance | Permanent | JSON |
Best Practices
Section titled “Best Practices”Test Restores Regularly
Section titled “Test Restores Regularly”Periodically restore backups to a test environment to verify they are complete and functional. Use --dry-run first, then perform a full restore to a non-production database.
Use ZIP for Attachments
Section titled “Use ZIP for Attachments”When backing up instances with evidence files, use ZIP format. Attachments are stored as separate files in the archive rather than Base64-encoded inline, which is more efficient and allows direct file access without parsing.
Document Your Backup Strategy
Section titled “Document Your Backup Strategy”Maintain a record of:
- Backup schedule and retention policy
- Storage locations for backup files
- Restore procedures and contact information
- Last successful restore test date
Validate Before Restoring
Section titled “Validate Before Restoring”Always run validate before restore in production:
# Step 1: Validateramp-cli validate --input backup.json --mode Copy
# Step 2: Dry runramp-cli restore --input backup.json --mode Copy --dry-run
# Step 3: Actual restore (only after validation passes)ramp-cli restore --input backup.json --mode CopySecure Backup Files
Section titled “Secure Backup Files”Backup files contain the complete state of your RAMP data, including step instructions, variable values, user references, and execution history. Store them in a secure location with appropriate access controls and encryption.