backup

package
v1.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package backup provides path validation helpers for backup operations.

Usage: 

absPath, err := backup.ValidateBackupPath(cfg.Backup.Dir, userSuppliedPath)

Package backup provides backup creation, listing, restoration, verification, pruning, and WAL archiving for nSelf projects.

Package backup — Hasura metadata export.

BackupHasuraMetadata calls the Hasura v1/metadata export_metadata API and writes the result to <backupDir>/hasura-metadata-<YYYY-MM-DD>.json. The file is mode 0600.

Package backup — streaming encrypted backup to remote destinations.

The pipeline runs three concurrent goroutines: 

pg_dump (streaming) | age (encrypt) | rclone (multipart upload)

No temp files are written. Encryption recipients may be age public keys, SSH public keys, or GitHub user keys (fetched via github.com/users/<user>/keys). The upload destination is any rclone-supported remote: s3://, r2://, b2://, gcs://, az://.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ArchiveWAL added in v1.0.6 

func ArchiveWAL(ctx context.Context, opts ArchiveWALOptions) error

ArchiveWAL encrypts and uploads a single WAL file to the remote. This is the core logic for the nself-backup-archive helper binary.

func BackupHasuraMetadata added in v1.0.14 

func BackupHasuraMetadata(ctx context.Context, opts HasuraMetadataOptions) (string, error)

BackupHasuraMetadata exports Hasura metadata and saves it to BackupDir. Returns the path of the written file.

func ConfigView added in v1.0.6 

func ConfigView(cfg *config.Config, format string) (string, error)

ConfigView returns the current backup configuration as a formatted string.

func Create added in v1.0.6 

func Create(ctx context.Context, cfg *config.Config, opts CreateOptions) error

Create performs a backup of the specified type. It writes the backup to the local backup directory and optionally uploads to the configured remote.

func FormatList added in v1.0.6 

func FormatList(backups []BackupEntry, format string) (string, error)

FormatList renders backup entries as a table or JSON string.

func FormatPruneJSON added in v1.0.6 

func FormatPruneJSON(result *PruneResult, keepDaily int) error

FormatPruneJSON prints a PruneResult as JSON to stdout.

func FormatStatus added in v1.0.6 

func FormatStatus(info *StatusInfo, format string) (string, error)

FormatStatus renders status info as a string.

func InitKey added in v1.0.6 

func InitKey(cfg *config.Config) (string, error)

InitKey generates an age keypair for backup encryption. Private key: ~/.config/nself/{project}-age.key (mode 0600) Public key: written to BACKUP_AGE_RECIPIENTS in the project .env.

func InstallSystemdUnits added in v1.0.6 

func InstallSystemdUnits(cfg *config.Config, opts SystemdInstallOptions) error

InstallSystemdUnits renders and writes unit files, then runs `systemctl daemon-reload` and enables each timer. Requires root.

func ListBackups 

func ListBackups(backupDir string) ([]string, error)

ListBackups returns the names of all regular files in backupDir. The returned slice is empty (not nil) when the directory contains no files. Directories and other non-regular entries are skipped.

func Restore added in v1.0.6 

func Restore(ctx context.Context, cfg *config.Config, opts RestoreOptions) error

Restore recovers a backup by ID or "latest".

func RestoreFromRemote added in v1.0.12 

func RestoreFromRemote(ctx context.Context, cfg *config.Config, from, keyPath string) error

RestoreFromRemote decrypts and restores a backup directly from a remote URL. It streams: rclone cat | age -d | pg_restore. No local temp file.

func ScheduleStream added in v1.0.12 

func ScheduleStream(cfg *config.Config, cron, to, recipient, unitDir string, dryRun bool) error

ScheduleStream adds a systemd timer for nself backup stream. It delegates to the existing systemd infrastructure via a dedicated unit.

func ValidateBackupPath 

func ValidateBackupPath(backupDir, userPath string) (string, error)

ValidateBackupPath resolves userPath relative to backupDir and verifies that the resolved absolute path is contained within backupDir. This prevents path traversal attacks (e.g. "../../../etc/passwd").

backupDir is the trusted root directory for backups (e.g. "/var/backups"). userPath is the caller-supplied relative or absolute path.

Returns the resolved absolute path on success, or an error if the path escapes backupDir.

Types

type ArchiveWALOptions added in v1.0.6 

type ArchiveWALOptions struct {
	WALFile       string // path to local WAL file
	Remote        string // rclone remote path
	AgeRecipient  string // age public key for encryption
	Timeline      string // PG timeline ID
	MaxRetries    int    // max upload retries (default: 3)
	RetryInterval time.Duration
}

ArchiveWALOptions holds configuration for WAL file archiving.

type BackupEntry added in v1.0.6 

type BackupEntry struct {
	ID        string    `json:"id"`
	Date      time.Time `json:"date"`
	Size      int64     `json:"size"`
	Type      string    `json:"type"`      // full, metadata, minio, wal
	Tag       string    `json:"tag"`       // user tag if present
	Encrypted bool      `json:"encrypted"` // .age suffix
}

BackupEntry holds parsed metadata for a single backup file.

func List added in v1.0.6 

func List(cfg *config.Config, opts ListOptions) ([]BackupEntry, error)

List returns backup entries from the local backup directory.

type BackupType added in v1.0.6 

type BackupType string

BackupType identifies the kind of backup to create. 

const (
	BackupTypeFull     BackupType = "full"
	BackupTypeWAL      BackupType = "wal"
	BackupTypeMetadata BackupType = "metadata"
	BackupTypeMinio    BackupType = "minio"
	BackupTypeAll      BackupType = "all"
)

type CreateOptions added in v1.0.6 

type CreateOptions struct {
	Type      BackupType // full, wal, metadata, minio, all
	Remote    string     // remote name override
	Encrypt   bool       // force encryption on
	NoEncrypt bool       // force encryption off
	Tag       string     // human label for this backup
	DryRun    bool       // preview only
}

CreateOptions holds flags for `nself backup create`.

type EmbeddedBackupResult added in v1.1.3 

type EmbeddedBackupResult struct {
	// ArtifactPath is the absolute path of the produced backup file.
	ArtifactPath string
	// Format is "pgdump-custom" when pg_dump was used, or "sql-plain" when
	// the wire-protocol COPY fallback was used.
	Format string
}

EmbeddedBackupResult describes the outcome of an embedded PG backup operation.

func BackupEmbedded added in v1.1.3 

func BackupEmbedded(ctx context.Context, cfg *config.Config) (*EmbeddedBackupResult, error)

BackupEmbedded creates a backup of the embedded pglite database. It first attempts to use pg_dump (pointing at the UDS socket) to produce a pg_dump-custom-format artifact compatible with pg_restore. If pg_dump is not available on PATH, it falls back to a wire-protocol SQL dump via lib/pq.

The artifact is written atomically (to a temp file then renamed) to prevent partial backup files from being visible to concurrent readers.

The backup file name format: <timestamp>-embedded.dump (pg custom format) 

or: <timestamp>-embedded.sql   (SQL fallback)

type HasuraMetadataOptions added in v1.0.14 

type HasuraMetadataOptions struct {
	// HasuraURL is the base URL of the Hasura instance, e.g.
	// "http://localhost:8080". Defaults to "http://localhost:8080".
	HasuraURL string
	// AdminSecret is the Hasura admin secret used for authentication.
	AdminSecret string
	// BackupDir is the directory where the JSON file will be written.
	// Defaults to "./backups".
	BackupDir string
}

HasuraMetadataOptions holds parameters for BackupHasuraMetadata.

type ListOptions added in v1.0.6 

type ListOptions struct {
	Remote string        // filter by remote name
	Env    string        // filter by environment
	Since  time.Duration // only show backups newer than this
	Format string        // table or json
}

ListOptions holds flags for `nself backup list`.

type PruneJSONEntry added in v1.0.6 

type PruneJSONEntry struct {
	Path    string `json:"path"`
	AgeDays int    `json:"age_days"`
}

PruneJSONEntry is one entry in the would_delete or kept arrays.

type PruneJSONReport added in v1.0.6 

type PruneJSONReport struct {
	DryRun      bool             `json:"dry_run"`
	KeepDaily   int              `json:"keep_daily"`
	WouldDelete []PruneJSONEntry `json:"would_delete"`
	Kept        []PruneJSONEntry `json:"kept"`
}

PruneJSONReport is the machine-readable output of `backup prune --format json`.

type PruneOptions added in v1.0.6 

type PruneOptions struct {
	DryRun      bool
	KeepDaily   int
	KeepWeekly  int
	KeepMonthly int
}

PruneOptions holds flags for `nself backup prune`.

type PruneResult added in v1.0.6 

type PruneResult struct {
	Kept   []string
	Pruned []string
	DryRun bool
}

PruneResult summarizes what was (or would be) pruned.

func Prune added in v1.0.6 

func Prune(cfg *config.Config, opts PruneOptions) (*PruneResult, error)

Prune removes old backups according to the retention policy. Retention: keep last N daily, N weekly (Sundays), N monthly (1st of month). Backups tagged "keep" are never deleted. WAL segments newer than the oldest surviving base backup are never deleted.

type RestoreOptions added in v1.0.6 

type RestoreOptions struct {
	BackupID   string   // backup ID or "latest"
	ToDir      string   // restore to alternate directory
	Only       []string // pg, minio, metadata — subset to restore
	DecryptKey string   // path to age identity file
	Yes        bool     // skip confirmation
}

RestoreOptions holds flags for `nself backup restore`.

Note: PointInTime (PITR) is NOT supported in v1.0.9. The field is retained for forward compatibility but any non-empty value returns an explicit error directing users to v1.1.0 + pgbackrest integration. Remove this note when PITR ships.

type ResumeOptions added in v1.0.12 

type ResumeOptions struct {
	BackupID string
}

ResumeOptions holds flags for `nself backup resume`.

type ResumeState added in v1.0.12 

type ResumeState struct {
	BackupID    string    `json:"backup_id"`
	Destination string    `json:"destination"`
	Key         string    `json:"key"`
	Recipients  []string  `json:"recipients"`
	StartedAt   time.Time `json:"started_at"`
	// For rclone-based multipart, we store the partial object key prefix.
	// rclone handles actual part tracking internally; we record enough to
	// invoke rclone copyto from a local temp file on resume.
	PartialPath string `json:"partial_path,omitempty"`
}

ResumeState holds the persisted state for a resumable streaming backup.

type StatusInfo added in v1.0.6 

type StatusInfo struct {
	LastRun          string `json:"last_run"`
	NextRun          string `json:"next_run"`
	Health           string `json:"health"` // healthy, warning, error
	TotalSize        string `json:"total_size"`
	BackupCount      int    `json:"backup_count"`
	RetentionDaily   int    `json:"retention_daily"`
	RetentionWeekly  int    `json:"retention_weekly"`
	RetentionMonthly int    `json:"retention_monthly"`
}

StatusInfo holds backup subsystem status.

func Status added in v1.0.6 

func Status(cfg *config.Config) (*StatusInfo, error)

Status computes and returns the current backup subsystem status.

type StreamConfig added in v1.0.12 

type StreamConfig struct {
	// PgURL is the postgres DSN used by pg_dump. If empty, derived from cfg.
	PgURL string

	// Destination is the rclone remote path, e.g. "s3:bucket/prefix/".
	Destination string

	// Recipients holds age/SSH public keys (one per entry). May also be
	// "github:<username>" to fetch the user's SSH public keys from GitHub.
	Recipients []string

	// Key is the object name appended to Destination. Auto-generated if empty.
	Key string

	// ChunkMB is the multipart chunk size. Defaults to 64.
	ChunkMB int
}

StreamConfig holds parameters for a streaming encrypted backup.

type StreamOptions added in v1.0.12 

type StreamOptions struct {
	To         string   // destination URL (rclone remote path)
	Recipients []string // --recipient flags (may be specified multiple times)
	DryRun     bool
}

StreamOptions holds CLI flag values for `nself backup stream`.

type StreamResult added in v1.0.12 

type StreamResult struct {
	BackupID    string    `json:"backup_id"`
	Destination string    `json:"destination"`
	StartedAt   time.Time `json:"started_at"`
	Duration    string    `json:"duration"`
	Encrypted   bool      `json:"encrypted"`
}

StreamResult is returned by Stream on success.

func Resume added in v1.0.12 

func Resume(ctx context.Context, cfg *config.Config, opts ResumeOptions) (*StreamResult, error)

Resume attempts to complete a previously interrupted streaming backup. Since rclone rcat cannot resume a partial upload, Resume re-streams from pg_dump through the full pipeline. The previous partial upload is overwritten at the same destination key.

func Stream added in v1.0.12 

func Stream(ctx context.Context, cfg *config.Config, opts StreamOptions) (*StreamResult, error)

Stream runs a three-stage concurrent pipeline:

  1. pg_dump stdout -> pgWriter
  2. age encrypts pgReader -> encWriter (skipped if no recipients)
  3. rclone rcat uploads encReader to Destination/Key

All three stages run in parallel goroutines. The first error from any stage cancels the others via context cancellation.

type SystemdInstallOptions added in v1.0.6 

type SystemdInstallOptions struct {
	FullAt      string // "HH:MM" UTC, e.g. "02:00"
	WALEvery    string // e.g. "15m"
	PruneAt     string // "HH:MM" UTC, default "04:30"
	VerifyOnDay string // systemd OnCalendar day name (Sun..Sat), default "Sun"
	VerifyAt    string // "HH:MM", default "05:00"
	UnitDir     string // default /etc/systemd/system
	EnvFile     string // default /etc/nself/backup.env
	BinaryPath  string // default /usr/local/bin/nself
	ProjectDir  string // working directory for nself commands
	Remote      string // e.g. b2-nclaw
	DryRun      bool
}

SystemdInstallOptions controls install of nself-backup systemd units.

type SystemdUnitFiles added in v1.0.6 

type SystemdUnitFiles map[string]string

SystemdUnitFiles maps filename -> unit contents.

func RenderSystemdUnits added in v1.0.6 

func RenderSystemdUnits(cfg *config.Config, opts SystemdInstallOptions) (SystemdUnitFiles, error)

RenderSystemdUnits produces the unit files needed for unattended backup, verify, and prune without writing to disk. Returns a map suitable for writing into /etc/systemd/system.

type VerifyOptions added in v1.0.6 

type VerifyOptions struct {
	BackupID    string // backup ID or "latest"
	RestoreTest bool   // spin up test container and restore
	Cleanup     bool   // remove test container after verify
	Keep        bool   // keep test container for inspection
}

VerifyOptions holds flags for `nself backup verify`.

type VerifyResult added in v1.0.6 

type VerifyResult struct {
	BackupID  string    `json:"backup_id"`
	Verified  bool      `json:"verified"`
	StartedAt time.Time `json:"started_at"`
	Duration  string    `json:"duration"`
	Method    string    `json:"method"` // checksum, restore-test
	Details   string    `json:"details"`
}

VerifyResult holds the outcome of a backup verification.

func Verify added in v1.0.6 

func Verify(ctx context.Context, cfg *config.Config, opts VerifyOptions) (*VerifyResult, error)

Verify checks backup integrity, optionally performing a restore test.

Source Files

View all Source files

Directories

Path Synopsis
Package destinations implements remote backup destination drivers for nSelf's PITR (Point-in-Time Recovery) system.
 Package destinations implements remote backup destination drivers for nSelf's PITR (Point-in-Time Recovery) system.
Package pitr implements point-in-time recovery via pg_basebackup and WAL archiving.
 Package pitr implements point-in-time recovery via pg_basebackup and WAL archiving.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.