# Backup API for Rust

Every public type, trait and function of the Backup engine in `tinystore::backup`, generated from its source. The [Backup guide](https://tinyshed.org/tinystore/docs/guides/backup) explains how to use them, and the [Bun and Node](https://tinyshed.org/tinystore/docs/reference/bun/backup), [Python](https://tinyshed.org/tinystore/docs/reference/python/backup) and [Go](https://tinyshed.org/tinystore/docs/reference/go/backup) pages list the same API.

## Store

```rust
impl Store
```

### Store.backup

```rust
pub fn backup(&self) -> BackupBuilder
```

A backup of every engine of the store, made while it keeps working.

## restore

```rust
pub fn restore(archive: impl AsRef<Path>, dir: impl AsRef<Path>) -> Result<Backup>
```

Restores the backup at `archive` into `dir`, which is empty or absent,
before a store opens there; the store's `LOCK` is held meanwhile, so that
none opens before the restore ends. A file that does not match what the
backup says of it fails the restore `Corrupt`, and leaves `dir` empty.

## Backup

```rust
pub struct Backup {
    pub files: usize,
    pub bytes: u64,
    pub key_left_out: bool,
}
```

What a backup holds.

## BackupBuilder

```rust
pub struct BackupBuilder { /* private fields */ }
```

A backup about to be made: the files of the program's it takes beside
the engines', and whether it takes the store's encryption key.

### BackupBuilder.include

```rust
pub fn include(self, name: &str) -> Self
```

Includes a file of the program's, by its path inside the store's
directory, such as `secret.key`, which a restore puts back where it
was. A backup holds no file but the engines' unless one is named.

### BackupBuilder.include_encryption_key

```rust
pub fn include_encryption_key(self) -> Self
```

Includes the store's encryption key, as it is, which a backup leaves
out otherwise: the zip is not encrypted, so a backup with the key
opens every value it holds, and is kept as safely as the key.

### BackupBuilder.write

```rust
pub fn write(self, path: impl AsRef<Path>) -> Result<Backup>
```

Writes the backup to `path` whole: beside it first, then renamed once
synced, so that a backup that fails leaves no zip.

### BackupBuilder.write_to

```rust
pub fn write_to(self, out: impl Write) -> Result<Backup>
```

Writes the backup to `out` as it is made, for a program that sends it
elsewhere: what `out` holds of a backup that fails is no backup.