ruvector/crates/ruvector-snapshot

Ruvector Snapshot

Point-in-time snapshots and backup for Ruvector vector databases.

ruvector-snapshot provides efficient snapshot creation, storage, and restoration for Ruvector databases. Supports incremental snapshots, compression, and integrity verification. Part of the Ruvector ecosystem.

Why Ruvector Snapshot?

• Point-in-Time Recovery: Restore to any snapshot
• Incremental Snapshots: Only store changed data
• Compression: GZIP compression for storage efficiency
• Integrity Verification: SHA-256 checksums
• Async I/O: Non-blocking snapshot operations

Features

Core Capabilities

• Full Snapshots: Complete database backup
• Incremental Snapshots: Delta-based backups
• Compression: GZIP compression support
• Checksums: SHA-256 integrity verification
• Async Operations: Tokio-based async I/O

Advanced Features

• Snapshot Scheduling: Automated snapshot creation
• Retention Policies: Automatic cleanup of old snapshots
• Remote Storage: S3/GCS compatible storage (planned)
• Streaming Restore: Progressive restoration
• Parallel Processing: Multi-threaded snapshot creation

Installation

Add ruvector-snapshot to your Cargo.toml:

[dependencies]
ruvector-snapshot = "0.1.1"

Quick Start

Create Snapshot

use ruvector_snapshot::{SnapshotManager, SnapshotConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure snapshot manager
    let config = SnapshotConfig {
        snapshot_dir: "./snapshots".into(),
        compression: true,
        verify_checksum: true,
        ..Default::default()
    };

    let manager = SnapshotManager::new(config)?;

    // Create a full snapshot
    let snapshot = manager.create_snapshot(&db, "backup-2024-01").await?;
    println!("Created snapshot: {} ({} bytes)",
        snapshot.id,
        snapshot.size_bytes
    );

    Ok(())
}

Restore from Snapshot

use ruvector_snapshot::SnapshotManager;

// List available snapshots
let snapshots = manager.list_snapshots().await?;
for snapshot in &snapshots {
    println!("{}: {} ({})",
        snapshot.id,
        snapshot.created_at,
        snapshot.size_bytes
    );
}

// Restore from snapshot
let restored_db = manager.restore_snapshot(&snapshots[0].id).await?;
println!("Restored {} vectors", restored_db.len()?);

Incremental Snapshots

use ruvector_snapshot::{SnapshotManager, SnapshotType};

// Create base snapshot
let base = manager.create_snapshot(&db, "base").await?;

// ... database modifications ...

// Create incremental snapshot
let incremental = manager.create_incremental_snapshot(
    &db,
    "incremental-1",
    &base.id
).await?;

println!("Incremental snapshot: {} bytes (vs {} full)",
    incremental.size_bytes,
    base.size_bytes
);

API Overview

Core Types

// Snapshot configuration
pub struct SnapshotConfig {
    pub snapshot_dir: PathBuf,
    pub compression: bool,
    pub compression_level: u32,
    pub verify_checksum: bool,
    pub max_concurrent_io: usize,
}

// Snapshot metadata
pub struct Snapshot {
    pub id: String,
    pub created_at: DateTime<Utc>,
    pub size_bytes: u64,
    pub checksum: String,
    pub snapshot_type: SnapshotType,
    pub vector_count: usize,
    pub metadata: serde_json::Value,
}

// Snapshot types
pub enum SnapshotType {
    Full,
    Incremental { base_id: String },
}

Manager Operations

impl SnapshotManager {
    pub fn new(config: SnapshotConfig) -> Result<Self>;

    // Snapshot creation
    pub async fn create_snapshot(&self, db: &VectorDB, name: &str) -> Result<Snapshot>;
    pub async fn create_incremental_snapshot(
        &self,
        db: &VectorDB,
        name: &str,
        base_id: &str
    ) -> Result<Snapshot>;

    // Listing and info
    pub async fn list_snapshots(&self) -> Result<Vec<Snapshot>>;
    pub async fn get_snapshot(&self, id: &str) -> Result<Option<Snapshot>>;

    // Restoration
    pub async fn restore_snapshot(&self, id: &str) -> Result<VectorDB>;
    pub async fn verify_snapshot(&self, id: &str) -> Result<bool>;

    // Management
    pub async fn delete_snapshot(&self, id: &str) -> Result<()>;
    pub async fn cleanup_old_snapshots(&self, keep: usize) -> Result<usize>;
}

Snapshot Format

snapshot-{id}/
├── metadata.json       # Snapshot metadata
├── vectors.bin.gz      # Compressed vector data
├── index.bin.gz        # HNSW index data
├── metadata.bin.gz     # Vector metadata
└── checksum.sha256     # Integrity checksum

Related Crates

• ruvector-core - Core vector database engine
• ruvector-replication - Data replication

Documentation

• Main README - Complete project overview
• API Documentation - Full API reference
• GitHub Repository - Source code

License

MIT License - see LICENSE for details.

---

Part of Ruvector - Built by rUv

Documentation | Crates.io | GitHub