Help us shape the future of Go! Take the 2026 Go Developer Survey

backup

package
v1.4.5 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 42 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	HookTypeStop       = "stop"
	HookTypeStart      = "start"
	HookTypeFlushRedis = "flush_redis"
	HookTypeFlushMySQL = "flush_mysql"
	HookTypeExec       = "exec"
)
View Source 
const (
	MaxHooks          = 20
	MaxHookTimeout    = 3600 // seconds
	MaxHookCommandLen = 4096
)

Limits on stored hooks, checked on save and again before a run.

View Source 
const (
	PreHookPhase  = "Pre-backup"
	PostHookPhase = "Post-backup"
)

Phase names for ValidateHooks.

View Source 
const AllowPrivateS3Env = "SIMPLEDEPLOY_ALLOW_PRIVATE_S3"

AllowPrivateS3Env, when set to "1", lets custom S3 endpoints resolve to private/loopback/reserved addresses (e.g. a MinIO on the same host).

View Source 
const NoDecompressedLimit int64 = -1

NoDecompressedLimit as RestoreOpts.MaxDecompressedBytes disables the restore size cap.

View Source 
const RestoreMaxGBEnv = "SIMPLEDEPLOY_RESTORE_MAX_GB"

RestoreMaxGBEnv overrides the restore size cap, in whole GiB.

Variables

View Source 
var ErrS3EndpointBlocked = errors.New("S3 endpoint points to a private or reserved network address")

ErrS3EndpointBlocked is returned (wrapped) when a custom S3 endpoint resolves to a private or reserved address.

Functions

func HooksJSON added in v1.4.5 

func HooksJSON(hooks []Hook) string

HooksJSON is the canonical stored form of hooks.

func SetSpoolDir added in v1.4.3 

func SetSpoolDir(dir string)

SetSpoolDir sets the directory restore archives are staged in.

func UploadRestoreMaxBytes added in v1.4.3 

func UploadRestoreMaxBytes() int64

UploadRestoreMaxBytes is the size cap for archives uploaded through the API: RestoreMaxGBEnv when set, else 8 GiB.

func ValidateCron added in v1.4.3 

func ValidateCron(expr string) error

ValidateCron parses expr with the same parser the scheduler's cron runner uses. An empty expression (no schedule) is valid.

func ValidateHooks added in v1.4.5 

func ValidateHooks(phase string, hooks []Hook, services, strategyServices []string) error

ValidateHooks checks one hook list; phase (PreHookPhase, PostHookPhase) prefixes messages. services, when non-nil, lists the app's compose services every hook must name. A pre-hook may not stop any of strategyServices (the services the backup and restore commands may run inside), since those commands need it running. Errors are human-readable.

func ValidatePath added in v1.4.3 

func ValidatePath(p string) error

ValidatePath checks a container path that ends up as a tar/cp operand. It must be absolute, printable, in clean form apart from an optional trailing '/' (no '//', '.' or '..' parts), not "/" itself, and no element may start with '-' (so it can never be parsed as a command-line flag).

func ValidatePaths added in v1.4.3 

func ValidatePaths(strategy string, paths []string) error

ValidatePaths validates paths for the given strategy. SQLite paths get the extra character check.

func ValidatePathsConfig added in v1.4.3 

func ValidatePathsConfig(strategy, raw string) error

ValidatePathsConfig parses a stored paths value (JSON array or comma-separated list, same as the scheduler) and validates it.

func ValidateS3Endpoint added in v1.4.3 

func ValidateS3Endpoint(ctx context.Context, endpoint string) error

ValidateS3Endpoint checks a custom S3 endpoint before it is saved. Empty (AWS default) is always allowed. Otherwise it must be an http(s) URL and, unless SIMPLEDEPLOY_ALLOW_PRIVATE_S3=1, every address the host resolves to must be public. The connection-time dialer re-checks this.

func ValidateSQLitePath added in v1.4.3 

func ValidateSQLitePath(p string) error

ValidateSQLitePath applies ValidatePath, refuses quotes, backslash, backtick and '$', and requires a file name (no trailing '/').

func VerifyChecksum 

func VerifyChecksum(r io.Reader, expectedHex string) error

Types

type BackupAlertFunc 

type BackupAlertFunc func(appID int64, appName, strategy, message, eventType string)

BackupAlertFunc is a callback for backup-related alerts.

type BackupOpts 

type BackupOpts struct {
	ContainerName string
	Paths         []string
	Credentials   map[string]string
}

type BackupResult 

type BackupResult struct {
	Reader   io.ReadCloser
	Filename string
}

type BackupStore 

type BackupStore interface {
	ListBackupConfigs(appID *int64) ([]store.BackupConfig, error)
	GetBackupConfig(id int64) (*store.BackupConfig, error)
	CreateBackupRun(configID int64) (*store.BackupRun, error)
	UpdateBackupRunSuccess(id int64, sizeBytes int64, filePath, checksum string) error
	UpdateBackupRunFailed(id int64, errMsg string) error
	ListOldBackupRuns(configID int64, keepCount int) ([]store.BackupRun, error)
	ListOldBackupRunsByTime(configID int64, maxAgeDays int) ([]store.BackupRun, error)
	GetAppByID(id int64) (*store.App, error)
	GetBackupRun(id int64) (*store.BackupRun, error)
	DeleteBackupRun(id int64) error
}

BackupStore is the subset of store.Store needed by Scheduler.

type ChecksumWriter 

type ChecksumWriter struct {
	// contains filtered or unexported fields
}

func NewChecksumWriter 

func NewChecksumWriter() *ChecksumWriter

func (*ChecksumWriter) Sum 

func (c *ChecksumWriter) Sum() string

func (*ChecksumWriter) TeeReader 

func (c *ChecksumWriter) TeeReader(r io.Reader) io.Reader

type ContainerExecutor 

type ContainerExecutor interface {
	ExecInService(ctx context.Context, project, service, command string) (string, error)
	StopService(ctx context.Context, project, service string) error
	StartService(ctx context.Context, project, service string) error
}

ContainerExecutor runs hook actions on one compose service of one compose project. Implementations must act only on containers labeled with both the project and the service, so a hook can never reach another app's containers, SimpleDeploy itself, or other containers on the host.

type ContainerLister added in v1.4.5 

type ContainerLister interface {
	ContainerList(ctx context.Context, opts container.ListOptions) ([]container.Summary, error)
}

ContainerLister is the part of docker.Client the hook executor needs.

type DetectedService 

type DetectedService struct {
	ServiceName   string            `json:"service_name"`
	ContainerName string            `json:"container_name"`
	Label         string            `json:"label"`
	Paths         []string          `json:"paths,omitempty"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

type DetectionResult 

type DetectionResult struct {
	StrategyType string            `json:"strategy_type"`
	Label        string            `json:"label"`
	Services     []DetectedService `json:"services"`
	Available    bool              `json:"available"`
	Description  string            `json:"description"`
}

DetectionResult summarizes what a single strategy found for an app.

type Detector 

type Detector struct {
	// contains filtered or unexported fields
}

Detector runs all registered strategies against a compose config.

func NewDetector 

func NewDetector() *Detector

func (*Detector) DetectAll 

func (d *Detector) DetectAll(cfg *compose.AppConfig) []DetectionResult

func (*Detector) Register 

func (d *Detector) Register(s Strategy)

type DockerHookExecutor added in v1.4.5 

type DockerHookExecutor struct {
	// contains filtered or unexported fields
}

DockerHookExecutor runs backup hooks with the docker CLI. It finds containers only by their compose project and service labels and acts on them by ID, so a hook's service can never name an arbitrary container (another app's, SimpleDeploy's, or any other on the host).

func NewDockerHookExecutor added in v1.4.5 

func NewDockerHookExecutor(client ContainerLister) *DockerHookExecutor

NewDockerHookExecutor returns an executor that lists containers through client and runs docker exec/stop/start for them.

func (*DockerHookExecutor) ExecInService added in v1.4.5 

func (e *DockerHookExecutor) ExecInService(ctx context.Context, project, service, command string) (string, error)

ExecInService runs command with sh -c in the service's first running container.

func (*DockerHookExecutor) StartService added in v1.4.5 

func (e *DockerHookExecutor) StartService(ctx context.Context, project, service string) error

StartService starts every container of the service.

func (*DockerHookExecutor) StopService added in v1.4.5 

func (e *DockerHookExecutor) StopService(ctx context.Context, project, service string) error

StopService stops every container of the service.

type EventPublisher added in v1.4.5 

type EventPublisher interface {
	Publish(ctx context.Context, e events.Event)
}

EventPublisher receives realtime notify-only events. *events.Bus satisfies it.

type Hook 

type Hook struct {
	Type    string `json:"type"`
	Service string `json:"service"`
	Command string `json:"command,omitempty"`
	Timeout int    `json:"timeout,omitempty"` // seconds, 0 = use default
}

func CheckHooks added in v1.4.5 

func CheckHooks(rawPre, rawPost string, composeCfg *compose.AppConfig, strategy Strategy) (pre, post []Hook, legacy int, err error)

CheckHooks parses and validates a config's stored pre and post hooks. With composeCfg (nil when the compose file can't be read) hooks must name one of its services, and with strategy too a pre-hook may not stop a service that strategy detects (it runs in one of them). legacy counts skipped entries from the old wizard format (see ParseHooks).

func ParseHooks added in v1.4.5 

func ParseHooks(raw string) (hooks []Hook, legacy int, err error)

ParseHooks decodes a stored hooks value: a JSON list, with "" or "null" meaning none. Entries whose service is an object were saved by an older backup wizard and never ran; they are skipped and counted in legacy.

type HookRunner 

type HookRunner struct {
	// contains filtered or unexported fields
}

func NewHookRunner 

func NewHookRunner(exec ContainerExecutor, project string, defaultTimeout time.Duration) *HookRunner

NewHookRunner returns a runner whose hooks act only on services of the compose project (simpledeploy-<slug>).

func (*HookRunner) RunPost 

func (hr *HookRunner) RunPost(ctx context.Context, hooks []Hook) []string

RunPost executes hooks sequentially, collecting warnings on failure.

func (*HookRunner) RunPre 

func (hr *HookRunner) RunPre(ctx context.Context, hooks []Hook) error

RunPre executes hooks sequentially, aborting on first failure.

type LocalTarget 

type LocalTarget struct {
	// contains filtered or unexported fields
}

LocalTarget stores backups on the local filesystem.

func NewLocalTarget 

func NewLocalTarget(dir string) *LocalTarget

func (*LocalTarget) Delete 

func (t *LocalTarget) Delete(ctx context.Context, path string) error

func (*LocalTarget) Download 

func (t *LocalTarget) Download(ctx context.Context, path string) (io.ReadCloser, error)

func (*LocalTarget) FilePath 

func (t *LocalTarget) FilePath(filename string) string

FilePath returns absolute filesystem path for download streaming.

func (*LocalTarget) Test 

func (t *LocalTarget) Test(ctx context.Context) error

func (*LocalTarget) Type 

func (t *LocalTarget) Type() string

func (*LocalTarget) Upload 

func (t *LocalTarget) Upload(ctx context.Context, filename string, data io.Reader) (string, int64, error)

type MongoStrategy 

type MongoStrategy struct{}

MongoStrategy backs up and restores MongoDB via mongodump/mongorestore.

func NewMongoStrategy 

func NewMongoStrategy() *MongoStrategy

func (*MongoStrategy) Backup 

func (s *MongoStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*MongoStrategy) Detect 

func (s *MongoStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*MongoStrategy) Restore 

func (s *MongoStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*MongoStrategy) Type 

func (s *MongoStrategy) Type() string

type MySQLStrategy 

type MySQLStrategy struct{}

MySQLStrategy backs up and restores MySQL/MariaDB via mysqldump.

func NewMySQLStrategy 

func NewMySQLStrategy() *MySQLStrategy

func (*MySQLStrategy) Backup 

func (s *MySQLStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*MySQLStrategy) Detect 

func (s *MySQLStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*MySQLStrategy) Restore 

func (s *MySQLStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*MySQLStrategy) Type 

func (s *MySQLStrategy) Type() string

type Pipeline 

type Pipeline struct {
	// contains filtered or unexported fields
}

Pipeline orchestrates backup and restore flows through strategy, target, and hooks.

func NewPipeline 

func NewPipeline(strategy Strategy, target Target, hooks *HookRunner) *Pipeline

NewPipeline creates a Pipeline with the given strategy, target, and optional hook runner.

func (*Pipeline) RunBackup 

func (p *Pipeline) RunBackup(ctx context.Context, opts BackupOpts, preHooks, postHooks []Hook) (*PipelineResult, error)

RunBackup: pre-hooks -> strategy.Backup -> tee through checksum -> target.Upload -> post-hooks

func (*Pipeline) RunRestore 

func (p *Pipeline) RunRestore(ctx context.Context, opts RestoreOpts, filePath, expectedChecksum string, preHooks, postHooks []Hook) error

RunRestore: download -> verify checksum -> pre-hooks -> strategy.Restore -> post-hooks

type PipelineResult 

type PipelineResult struct {
	FilePath  string
	SizeBytes int64
	Checksum  string
	Warnings  []string // post-hook failures; the backup itself succeeded
}

PipelineResult holds the outcome of a backup pipeline run.

type PostgresStrategy 

type PostgresStrategy struct{}

PostgresStrategy backs up and restores a Postgres container via pg_dump/psql.

func NewPostgresStrategy 

func NewPostgresStrategy() *PostgresStrategy

func (*PostgresStrategy) Backup 

func (s *PostgresStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*PostgresStrategy) Detect 

func (s *PostgresStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*PostgresStrategy) Restore 

func (s *PostgresStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*PostgresStrategy) Type 

func (s *PostgresStrategy) Type() string

type RedisStrategy 

type RedisStrategy struct{}

RedisStrategy backs up and restores Redis by triggering BGSAVE then copying the RDB file.

func NewRedisStrategy 

func NewRedisStrategy() *RedisStrategy

func (*RedisStrategy) Backup 

func (s *RedisStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*RedisStrategy) Detect 

func (s *RedisStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*RedisStrategy) Restore 

func (s *RedisStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*RedisStrategy) Type 

func (s *RedisStrategy) Type() string

type RestoreOpts 

type RestoreOpts struct {
	ContainerName string
	Paths         []string
	Credentials   map[string]string
	Reader        io.ReadCloser
	// MaxDecompressedBytes caps the bytes a strategy produces from the
	// (possibly gzipped) Reader, and the raw archive size where it is
	// staged on disk. 0 means defaultMaxDecompressed; NoDecompressedLimit
	// (any negative value) disables the cap.
	MaxDecompressedBytes int64
}

type S3Config 

type S3Config struct {
	Endpoint  string `json:"endpoint"`
	Bucket    string `json:"bucket"`
	Prefix    string `json:"prefix"`
	AccessKey string `json:"access_key"`
	SecretKey string `json:"secret_key"`
	Region    string `json:"region"`
}

S3Config holds connection settings for an S3-compatible object store.

Its JSON form (backup_configs.target_config_json and the test-s3 request body) uses the snake_case keys the UI and docs send: endpoint, bucket, prefix, access_key, secret_key, region. UnmarshalJSON also accepts the Go field names (Endpoint, AccessKey, ...) that older clients sent before the struct had tags, so configs stored that way keep working.

func (*S3Config) UnmarshalJSON added in v1.4.4 

func (c *S3Config) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes snake_case keys and falls back to the legacy AccessKey/SecretKey keys when the snake_case ones are missing or empty. The other legacy keys (Endpoint, Bucket, ...) already match their tags because encoding/json matches keys case-insensitively.

type S3Target 

type S3Target struct {
	// contains filtered or unexported fields
}

S3Target stores backups in an S3-compatible object store.

func NewS3Target 

func NewS3Target(cfg S3Config) (*S3Target, error)

func (*S3Target) Delete 

func (t *S3Target) Delete(ctx context.Context, path string) error

func (*S3Target) Download 

func (t *S3Target) Download(ctx context.Context, path string) (io.ReadCloser, error)

func (*S3Target) PresignedURL 

func (t *S3Target) PresignedURL(ctx context.Context, key string, expiry time.Duration) (string, error)

PresignedURL returns a pre-signed GET URL valid for the given duration.

func (*S3Target) Test 

func (t *S3Target) Test(ctx context.Context) error

func (*S3Target) Type 

func (t *S3Target) Type() string

func (*S3Target) Upload 

func (t *S3Target) Upload(ctx context.Context, filename string, data io.Reader) (string, int64, error)

type SQLiteStrategy 

type SQLiteStrategy struct{}

SQLiteStrategy backs up SQLite databases inside containers using the .backup command for consistency. Label-only detection (no image keywords).

func NewSQLiteStrategy 

func NewSQLiteStrategy() *SQLiteStrategy

func (*SQLiteStrategy) Backup 

func (s *SQLiteStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*SQLiteStrategy) Detect 

func (s *SQLiteStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*SQLiteStrategy) Restore 

func (s *SQLiteStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*SQLiteStrategy) Type 

func (s *SQLiteStrategy) Type() string

type Scheduler 

type Scheduler struct {
	// contains filtered or unexported fields
}

Scheduler runs scheduled backups and handles restore requests.

func NewScheduler 

func NewScheduler(st BackupStore, hookExec ContainerExecutor) *Scheduler

NewScheduler creates a new Scheduler backed by st.

func (*Scheduler) CheckMissed 

func (s *Scheduler) CheckMissed()

CheckMissed iterates configs and alerts if last run is overdue (>2x cron interval).

func (*Scheduler) GetDetector 

func (s *Scheduler) GetDetector() *Detector

GetDetector returns a Detector with all registered strategies.

func (*Scheduler) GetStrategy 

func (s *Scheduler) GetStrategy(name string) (Strategy, bool)

GetStrategy returns a registered strategy by name.

func (*Scheduler) RegisterStrategy 

func (s *Scheduler) RegisterStrategy(name string, strategy Strategy)

RegisterStrategy registers a named backup strategy.

func (*Scheduler) RegisterTargetFactory 

func (s *Scheduler) RegisterTargetFactory(name string, factory func(string) (Target, error))

RegisterTargetFactory registers a factory function for the named target type.

func (*Scheduler) RunBackup 

func (s *Scheduler) RunBackup(ctx context.Context, cfgID int64) error

RunBackup executes a backup for the given config ID using Pipeline.

func (*Scheduler) RunRestore 

func (s *Scheduler) RunRestore(ctx context.Context, runID int64) error

RunRestore restores data from the backup run identified by runID.

func (*Scheduler) ScheduleConfig 

func (s *Scheduler) ScheduleConfig(configID int64, cronExpr string) error

ScheduleConfig adds or replaces a cron entry for the given config.

func (*Scheduler) SetAlertFunc 

func (s *Scheduler) SetAlertFunc(fn BackupAlertFunc)

SetAlertFunc sets the callback for backup alerts.

func (*Scheduler) SetEventBus added in v1.4.5 

func (s *Scheduler) SetEventBus(b EventPublisher)

SetEventBus wires the realtime events bus, told when a backup or restore run starts and finishes so open Backups views refresh. nil disables it.

func (*Scheduler) Start 

func (s *Scheduler) Start() error

Start loads all backup configs and schedules cron entries, then starts the cron runner.

func (*Scheduler) Stop 

func (s *Scheduler) Stop()

Stop stops the cron scheduler.

func (*Scheduler) UnscheduleConfig 

func (s *Scheduler) UnscheduleConfig(configID int64)

UnscheduleConfig removes the cron entry for the given config.

type Strategy 

type Strategy interface {
	Type() string
	Detect(cfg *compose.AppConfig) []DetectedService
	Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)
	Restore(ctx context.Context, opts RestoreOpts) error
}

type Target 

type Target interface {
	Type() string
	Upload(ctx context.Context, filename string, data io.Reader) (path string, size int64, err error)
	Download(ctx context.Context, path string) (io.ReadCloser, error)
	Delete(ctx context.Context, path string) error
	Test(ctx context.Context) error
}

type TargetFactory 

type TargetFactory func(configJSON string) (Target, error)

type VolumeStrategy 

type VolumeStrategy struct{}

VolumeStrategy backs up and restores container volumes via tar.

func NewVolumeStrategy 

func NewVolumeStrategy() *VolumeStrategy

func (*VolumeStrategy) Backup 

func (s *VolumeStrategy) Backup(ctx context.Context, opts BackupOpts) (*BackupResult, error)

func (*VolumeStrategy) Detect 

func (s *VolumeStrategy) Detect(cfg *compose.AppConfig) []DetectedService

func (*VolumeStrategy) Restore 

func (s *VolumeStrategy) Restore(ctx context.Context, opts RestoreOpts) error

func (*VolumeStrategy) Type 

func (s *VolumeStrategy) Type() string

Source Files

View all Source files

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.