forgedb 0.2.1

ForgeDB — an application database generator. Compiles a declarative .forge schema into tailored Rust database code, a TypeScript SDK, and a REST API.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

use crate::commands::compact::format_bytes;
use crate::error::CliError;
use std::path::PathBuf;

pub struct CreateOptions {
    pub data_dir: PathBuf,
    pub output: PathBuf,
    pub incremental: bool,
    pub base: Option<PathBuf>,
}

pub struct RestoreOptions {
    /// A single full archive, or a base followed by its incrementals in order.
    pub archives: Vec<PathBuf>,
    pub output: PathBuf,
    pub overwrite: bool,
}

pub struct ListOptions {
    pub archive: PathBuf,
    pub json: bool,
}

fn map_err(e: forgedb_backup::BackupError) -> CliError {
    CliError::Backup(e.to_string())
}

/// Create a snapshot archive of a database directory — a full lock-free
/// snapshot, or an incremental byte-tail delta against a base (`--incremental`).
pub fn create(opts: CreateOptions) -> Result<(), CliError> {
    let (summary, kind) = if opts.incremental {
        let base = opts.base.ok_or_else(|| {
            CliError::Backup(
                "--incremental requires --base <archive> (the base or prior delta to build on)"
                    .to_string(),
            )
        })?;
        (
            forgedb_backup::create_incremental(&opts.data_dir, &base, &opts.output)
                .map_err(map_err)?,
            "Incremental backup",
        )
    } else {
        (
            forgedb_backup::create(&opts.data_dir, &opts.output).map_err(map_err)?,
            "Backup",
        )
    };

    println!("\n✓ {} created: {}\n", kind, summary.archive_path.display());
    println!("{:<24} {:>12} {:>10}", "Model", "Rows", "Epoch");
    println!("{}", "=".repeat(48));
    for m in &summary.models {
        println!("{:<24} {:>12} {:>10}", m.dir, m.row_count, m.compaction_epoch);
    }
    println!("{}", "=".repeat(48));
    println!(
        "{} model(s), {} of {}",
        summary.models.len(),
        format_bytes(summary.total_bytes),
        if opts.incremental {
            "appended-tail data"
        } else {
            "committed data"
        }
    );
    Ok(())
}

/// Restore a snapshot archive (or a base + incremental chain) into a data
/// directory (atomic temp + rename). Pass the base first, then each delta.
pub fn restore(opts: RestoreOptions) -> Result<(), CliError> {
    let summary =
        forgedb_backup::restore_chain(&opts.archives, &opts.output, opts.overwrite)
            .map_err(map_err)?;

    println!("\n✓ Restored to: {}\n", summary.out_dir.display());
    if opts.archives.len() > 1 {
        println!(
            "Applied {} archive(s) (1 base + {} incremental).",
            opts.archives.len(),
            opts.archives.len() - 1
        );
    }
    println!("{:<24} {:>12}", "Model", "Rows");
    println!("{}", "=".repeat(38));
    for m in &summary.models {
        println!("{:<24} {:>12}", m.dir, m.row_count);
    }
    println!("{}", "=".repeat(38));
    println!(
        "{} model(s), {} restored",
        summary.models.len(),
        format_bytes(summary.total_bytes)
    );
    Ok(())
}

/// Inspect an archive's header without materializing it.
pub fn list(opts: ListOptions) -> Result<(), CliError> {
    let header = forgedb_backup::read_header(&opts.archive).map_err(map_err)?;

    if opts.json {
        let json = serde_json::to_string_pretty(&header)
            .map_err(|e| CliError::Backup(e.to_string()))?;
        println!("{}", json);
        return Ok(());
    }

    println!("\nArchive: {}", opts.archive.display());
    println!("Container version: {}", header.container_version);
    if header.is_incremental() {
        print!("Kind: incremental (chain sequence {}", header.sequence);
        if let Some(base) = &header.base {
            print!(", base sequence {}", base.sequence);
        }
        println!(")");
    } else {
        println!("Kind: full base (chain sequence 0)");
    }
    if !header.chain_id.is_empty() {
        println!("Chain id: {}", header.chain_id);
    }
    println!();
    println!(
        "{:<24} {:>10} {:>10} {:>8}",
        "Model", "Rows", "Epoch", "SchemaV"
    );
    println!("{}", "=".repeat(56));
    for m in &header.models {
        println!(
            "{:<24} {:>10} {:>10} {:>8}",
            m.dir, m.row_count, m.compaction_epoch, m.schema_version
        );
    }
    Ok(())
}