restic

Documentation

Index

• func BuildTagArgs(tags map[string]string) []string
• func BuildTagFilter(tags map[string]string) []string
• type BackupSummary
• type Client
  • func NewClient(repository, password string) *Client
  • func (c *Client) BackupStdin(ctx context.Context, stdin io.Reader, stdinFilename string, ...) (*BackupSummary, error)
  • func (c *Client) Check(ctx context.Context) error
  • func (c *Client) Dump(ctx context.Context, snapshotID, path string, stdout io.Writer, ...) error
  • func (c *Client) Forget(ctx context.Context, tags map[string]string, policy RetentionPolicy, ...) ([]ForgetResult, error)
  • func (c *Client) ForgetGrouped(ctx context.Context, tags map[string]string, policy RetentionPolicy, ...) (keepCount, removeCount int, err error)
  • func (c *Client) ForgetSnapshot(ctx context.Context, snapshotID string) error
  • func (c *Client) Init(ctx context.Context) error
  • func (c *Client) Prune(ctx context.Context) error
  • func (c *Client) Run(ctx context.Context, args ...string) ([]byte, error)
  • func (c *Client) RunWithStdin(ctx context.Context, stdin io.Reader, args ...string) ([]byte, error)
  • func (c *Client) RunWithStdout(ctx context.Context, stdout io.Writer, args ...string) error
  • func (c *Client) Snapshots(ctx context.Context, tags map[string]string) ([]Snapshot, error)
  • func (c *Client) Stats(ctx context.Context) (*RepoStats, error)
  • func (c *Client) Unlock(ctx context.Context) error
• type ForgetResult
• type JobGroup
  • func ApplyGroupRetention(groups []JobGroup, policy RetentionPolicy) (keep, remove []JobGroup)
  • func GroupByJob(snapshots []Snapshot) []JobGroup
• type RepoStats
• type RetentionPolicy
• type Snapshot
  • func (s *Snapshot) TagMap() map[string]string

Functions

func BuildTagArgs

func BuildTagArgs(tags map[string]string) []string

BuildTagArgs builds --tag flags for adding tags to a snapshot (backup). Each tag is a separate --tag flag.

func BuildTagFilter

func BuildTagFilter(tags map[string]string) []string

BuildTagFilter builds a single --tag flag for filtering snapshots (AND semantics). Tags are comma-separated within one --tag flag for AND matching.

Types

type BackupSummary

type BackupSummary struct {
	SnapshotID    string  `json:"snapshot_id"`
	FilesNew      int     `json:"files_new"`
	FilesChanged  int     `json:"files_changed"`
	DataAdded     int64   `json:"data_added"`
	TotalSize     int64   `json:"total_bytes_processed"`
	TotalDuration float64 `json:"total_duration"`
}

BackupSummary holds the result of a restic backup --stdin --json operation.

type Client

type Client struct {
	// Binary is the path to the restic binary (default: "restic").
	Binary string
	// Repository is the restic repository location (path or s3:URL).
	Repository string
	// Password is the repository encryption password.
	Password string
	// Env holds additional environment variables (e.g., AWS_ACCESS_KEY_ID).
	Env map[string]string
}

Client wraps the restic binary for repository operations.

func NewClient

func NewClient(repository, password string) *Client

NewClient creates a new restic client.

func (*Client) BackupStdin

func (c *Client) BackupStdin(ctx context.Context, stdin io.Reader, stdinFilename string, tags map[string]string, jobTime time.Time) (*BackupSummary, error)

BackupStdin runs restic backup --stdin, reading data from the provided reader. stdinFilename sets the virtual file path in the snapshot. tags are key=value metadata added to the snapshot. jobTime sets the snapshot timestamp via --time (use the job start time for consistency).

func (*Client) Check

func (c *Client) Check(ctx context.Context) error

Check verifies repository integrity.

func (*Client) Dump

func (c *Client) Dump(ctx context.Context, snapshotID, path string, stdout io.Writer, tags map[string]string) error

Dump extracts a file from a snapshot and writes its content to stdout. snapshotID can be a specific ID or "latest". path is the file path within the snapshot (e.g., "zeldas-lullaby/zitadel-postgres/pgdumpall.sql"). tags are used to filter which "latest" snapshot to select (AND semantics).

func (*Client) Forget

func (c *Client) Forget(ctx context.Context, tags map[string]string, policy RetentionPolicy, prune bool) ([]ForgetResult, error)

Forget removes snapshots according to the retention policy. If prune is true, unreferenced data is removed from the repository.

func (*Client) ForgetGrouped

func (c *Client) ForgetGrouped(ctx context.Context, tags map[string]string, policy RetentionPolicy, prune bool) (keepCount, removeCount int, err error)

ForgetGrouped applies group-aware retention for diverged snapshots. Snapshots sharing a "job" tag are treated as a single unit for retention. Returns the number of snapshots kept and removed.

func (*Client) ForgetSnapshot

func (c *Client) ForgetSnapshot(ctx context.Context, snapshotID string) error

ForgetSnapshot removes a single snapshot by ID.

func (*Client) Init

func (c *Client) Init(ctx context.Context) error

Init initializes a new restic repository. Returns nil if already initialized.

func (*Client) Prune

func (c *Client) Prune(ctx context.Context) error

Prune removes unreferenced data from the repository.

func (*Client) Run

func (c *Client) Run(ctx context.Context, args ...string) ([]byte, error)

Run executes a restic command and returns stdout.

func (*Client) RunWithStdin

func (c *Client) RunWithStdin(ctx context.Context, stdin io.Reader, args ...string) ([]byte, error)

RunWithStdin executes a restic command with stdin piped from the provided reader.

func (*Client) RunWithStdout

func (c *Client) RunWithStdout(ctx context.Context, stdout io.Writer, args ...string) error

RunWithStdout executes a restic command and writes stdout to the provided writer.

func (*Client) Snapshots

func (c *Client) Snapshots(ctx context.Context, tags map[string]string) ([]Snapshot, error)

Snapshots returns snapshots matching the given tag filters (AND semantics).

func (*Client) Stats

func (c *Client) Stats(ctx context.Context) (*RepoStats, error)

Stats returns repository statistics.

func (*Client) Unlock

func (c *Client) Unlock(ctx context.Context) error

Unlock removes stale repository locks.

type ForgetResult

type ForgetResult struct {
	Tags   []string   `json:"tags"`
	Keep   []Snapshot `json:"keep"`
	Remove []Snapshot `json:"remove"`
}

ForgetResult holds the result of a forget operation for a tag group.

type JobGroup

type JobGroup struct {
	JobID     string
	Time      time.Time
	Snapshots []Snapshot
}

JobGroup represents a set of diverged snapshots from the same repair job.

func ApplyGroupRetention

func ApplyGroupRetention(groups []JobGroup, policy RetentionPolicy) (keep, remove []JobGroup)

ApplyGroupRetention applies retention policies to job groups. Policies work on groups as units: keep-last keeps N most recent jobs, keep-daily/weekly/monthly keep one job per time window. If all policy values are zero, all groups are kept.

func GroupByJob

func GroupByJob(snapshots []Snapshot) []JobGroup

GroupByJob groups snapshots by their "job" tag value, sorted newest first. Snapshots without a job tag are each treated as their own group.

type RepoStats

type RepoStats struct {
	TotalSize      int64 `json:"total_size"`
	TotalFileCount int   `json:"total_file_count"`
}

RepoStats holds repository statistics from restic stats.

type RetentionPolicy

type RetentionPolicy struct {
	KeepLast    int
	KeepDaily   int
	KeepWeekly  int
	KeepMonthly int
}

RetentionPolicy defines how many snapshots to keep.

type Snapshot

type Snapshot struct {
	ID       string    `json:"id"`
	ShortID  string    `json:"short_id"`
	Time     time.Time `json:"time"`
	Hostname string    `json:"hostname"`
	Tags     []string  `json:"tags"`
	Paths    []string  `json:"paths"`
}

Snapshot represents a restic snapshot.

func (*Snapshot) TagMap

func (s *Snapshot) TagMap() map[string]string

TagMap returns snapshot tags as a key=value map.