Documentation
¶
Overview ¶
Package backup copies the SQLite database safely: a consistent snapshot with VACUUM INTO (copying the file of a live database can corrupt the copy), a rolling set of automatic snapshots while the server runs, and a restore that never overwrites data (ADR 0009, ADR 0020).
Files are named <kind>-<UTC timestamp>.db. Only automatic backups (kind "auto") are ever deleted by this package.
Index ¶
- Constants
- Variables
- func Prune(dir string, keep int) ([]string, error)
- func Restore(ctx context.Context, src, dataDir string, force bool, now time.Time) (dst, replaced string, err error)
- func Snapshot(ctx context.Context, db *sql.DB, dir, kind string, now time.Time) (string, error)
- func Verify(ctx context.Context, path string) error
- type File
- type Service
Constants ¶
const ( KindAuto = "auto" // made by the server, pruned to the newest N KindManual = "manual" // made by `exhale backup`, never deleted )
Kinds of backup. The kind is the first part of the file name.
const DBName = "exhale.db"
DBName is the database file inside the data directory.
const (
DefaultKeep = 14
)
Defaults of the automatic backups.
Variables ¶
var ErrExists = errors.New("backup: the data directory already has a database")
ErrExists is returned by Restore when the data directory already has a database and force is not set.
var ErrInUse = errors.New("backup: the database is in use")
ErrInUse is returned by Restore when another process has the database open.
Functions ¶
func Prune ¶
Prune deletes the automatic backups in dir beyond the newest keep and returns the paths it removed. keep <= 0 keeps everything. Files of any other kind (manual, pre-migrate, or anything else in dir) are never touched.
func Restore ¶
func Restore(ctx context.Context, src, dataDir string, force bool, now time.Time) (dst, replaced string, err error)
Restore copies the backup file src into dataDir as the database.
It refuses when dataDir already has a database, unless force is set; and even then it refuses when another process (a running Exhale) has that database open. Nothing is deleted: the database it replaces is renamed next to the new one and its path is returned in replaced.
Types ¶
type Service ¶
type Service struct {
DB *sql.DB
Dir string
Keep int // automatic backups to keep; 0 keeps all
Log *slog.Logger
Every time.Duration // time between backups; default 24 h
Delay time.Duration // wait after start before the first check; default 1 min
// Now and Sleep are the clock; tests replace them.
Now func() time.Time
Sleep func(ctx context.Context, d time.Duration) bool
}
Service makes one automatic backup a day while the server runs and keeps the newest Keep. It is a supervised service (platform.Service).
It decides from the files on disk, not from memory: a backup is due when the newest automatic one is at least Every old. Restarting the server therefore never produces extra backups, and a day missed while the machine was off is made up soon after start.
Source Files