db

package
v0.4.5 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrNotFound = errors.New("record not found")
)

Functions

This section is empty.

Types

type APIKey 

type APIKey struct {
	ID         uuid.UUID  `json:"id"`
	Name       string     `json:"name"`
	KeyHash    string     `json:"-"`
	CreatedBy  string     `json:"created_by"`
	CreatedAt  time.Time  `json:"created_at"`
	LastUsedAt *time.Time `json:"last_used_at"`
	ExpiresAt  *time.Time `json:"expires_at"`
	RevokedAt  *time.Time `json:"revoked_at"`
}

APIKey is an admin credential for fallbck-ctl and scripts. The raw key is never stored.

type Agent 

type Agent struct {
	ID         uuid.UUID   `json:"id" db:"id"`
	Hostname   string      `json:"hostname" db:"hostname"`
	IPAddress  string      `json:"ip_address" db:"ip_address"`
	OS         string      `json:"os" db:"os"`
	Arch       string      `json:"arch" db:"arch"`
	Version    string      `json:"version" db:"version"`
	TaskQueue  string      `json:"task_queue" db:"task_queue"`
	Status     AgentStatus `json:"status" db:"status"`
	LastSeenAt *time.Time  `json:"last_seen_at" db:"last_seen_at"`
	CreatedAt  time.Time   `json:"created_at" db:"created_at"`
	UpdatedAt  time.Time   `json:"updated_at" db:"updated_at"`
}

Agent represents a registered backup agent host

type AgentAuthState 

type AgentAuthState struct {
	ID           uuid.UUID
	TaskQueue    string
	TokenVersion int
	Revoked      bool
}

AgentAuthState is the subset of agent state needed to validate an agent bearer token

type AgentStatus 

type AgentStatus string

AgentStatus represents the lifecycle state of an agent 

const (
	AgentStatusOnline  AgentStatus = "online"
	AgentStatusOffline AgentStatus = "offline"
	AgentStatusBusy    AgentStatus = "busy"
	AgentStatusError   AgentStatus = "error"
)

type BackupJob 

type BackupJob struct {
	ID              uuid.UUID       `json:"id" db:"id"`
	Name            string          `json:"name" db:"name"`
	AgentID         uuid.UUID       `json:"agent_id" db:"agent_id"`
	TargetID        uuid.UUID       `json:"target_id" db:"target_id"`
	ScheduleCron    string          `json:"schedule_cron" db:"schedule_cron"`
	BackupPaths     []string        `json:"backup_paths" db:"backup_paths"`
	ExcludePaths    []string        `json:"exclude_paths" db:"exclude_paths"`
	RetentionPolicy RetentionPolicy `json:"retention_policy" db:"retention_policy"`
	Enabled         bool            `json:"enabled" db:"enabled"`
	CreatedAt       time.Time       `json:"created_at" db:"created_at"`
	UpdatedAt       time.Time       `json:"updated_at" db:"updated_at"`

	// Joined fields for display
	AgentName  string `json:"agent_name,omitempty"`
	TargetName string `json:"target_name,omitempty"`
}

BackupJob defines what, when, and where an agent backs up

type BackupRun 

type BackupRun struct {
	ID            uuid.UUID  `json:"id" db:"id"`
	JobID         uuid.UUID  `json:"job_id" db:"job_id"`
	AgentID       uuid.UUID  `json:"agent_id" db:"agent_id"`
	TargetID      uuid.UUID  `json:"target_id" db:"target_id"`
	WorkflowID    string     `json:"workflow_id" db:"workflow_id"`
	RunID         string     `json:"run_id" db:"run_id"`
	Status        RunStatus  `json:"status" db:"status"`
	StartTime     *time.Time `json:"start_time" db:"start_time"`
	EndTime       *time.Time `json:"end_time" db:"end_time"`
	BytesScanned  int64      `json:"bytes_scanned" db:"bytes_scanned"`
	BytesUploaded int64      `json:"bytes_uploaded" db:"bytes_uploaded"`
	DedupRatio    float64    `json:"dedup_ratio" db:"dedup_ratio"`
	ChunkCount    int        `json:"chunk_count" db:"chunk_count"`
	ErrorMessage  string     `json:"error_message" db:"error_message"`
	PBSSnapshotID string     `json:"pbs_snapshot_id" db:"pbs_snapshot_id"`
	CreatedAt     time.Time  `json:"created_at" db:"created_at"`

	// Joined fields
	JobName   string `json:"job_name,omitempty"`
	AgentName string `json:"agent_name,omitempty"`
}

BackupRun records a single execution of a backup job

type BackupTarget 

type BackupTarget struct {
	ID                 uuid.UUID `json:"id" db:"id"`
	Name               string    `json:"name" db:"name"`
	TargetType         string    `json:"target_type" db:"target_type"` // "pbs"
	Endpoint           string    `json:"endpoint" db:"endpoint"`
	Datastore          string    `json:"datastore" db:"datastore"`
	Namespace          string    `json:"namespace" db:"namespace"`
	AuthTokenEncrypted string    `json:"-" db:"auth_token_encrypted"`
	Fingerprint        string    `json:"fingerprint" db:"fingerprint"`
	TLSVerify          bool      `json:"tls_verify" db:"tls_verify"`
	CreatedAt          time.Time `json:"created_at" db:"created_at"`
	UpdatedAt          time.Time `json:"updated_at" db:"updated_at"`
}

BackupTarget represents a remote backup repository such as Proxmox Backup Server

type DB 

type DB struct {
	Pool *pgxpool.Pool
}

DB wraps the pgx connection pool and exposes repository operations

func New 

func New(ctx context.Context, cfg config.DatabaseConfig) (*DB, error)

New creates a new database connection pool and applies migrations if enabled

func (*DB) BumpAgentTokenVersion 

func (d *DB) BumpAgentTokenVersion(ctx context.Context, id uuid.UUID) (int, error)

BumpAgentTokenVersion invalidates every previously issued token for the agent and returns the new version that must be embedded in freshly issued tokens.

func (*DB) Close 

func (d *DB) Close()

Close closes the underlying pool

func (*DB) CreateAPIKey 

func (d *DB) CreateAPIKey(ctx context.Context, key *APIKey) error

func (*DB) CreateAgent 

func (d *DB) CreateAgent(ctx context.Context, agent *Agent) error

func (*DB) CreateEnrollmentToken 

func (d *DB) CreateEnrollmentToken(ctx context.Context, token *EnrollmentToken) error

func (*DB) CreateJob 

func (d *DB) CreateJob(ctx context.Context, job *BackupJob) error

func (*DB) CreateRun 

func (d *DB) CreateRun(ctx context.Context, run *BackupRun) error

func (*DB) CreateTarget 

func (d *DB) CreateTarget(ctx context.Context, target *BackupTarget) error

func (*DB) DeleteAgent 

func (d *DB) DeleteAgent(ctx context.Context, id uuid.UUID) error

func (*DB) DeleteJob 

func (d *DB) DeleteJob(ctx context.Context, id uuid.UUID) error

func (*DB) DeleteTarget 

func (d *DB) DeleteTarget(ctx context.Context, id uuid.UUID) error

func (*DB) GetAPIKeyByHash 

func (d *DB) GetAPIKeyByHash(ctx context.Context, hash string) (*APIKey, error)

func (*DB) GetAgentAuthState 

func (d *DB) GetAgentAuthState(ctx context.Context, id uuid.UUID) (*AgentAuthState, error)

GetAgentAuthState returns the token version and revocation state of an agent. Returns ErrNotFound if the agent does not exist (e.g. it was deleted).

func (*DB) GetAgentByID 

func (d *DB) GetAgentByID(ctx context.Context, id uuid.UUID) (*Agent, error)

func (*DB) GetJobByID 

func (d *DB) GetJobByID(ctx context.Context, id uuid.UUID) (*BackupJob, error)

func (*DB) GetRunByID added in v0.3.1 

func (d *DB) GetRunByID(ctx context.Context, id uuid.UUID) (*BackupRun, error)

GetRunByID returns a single run

func (*DB) GetRunByWorkflowID added in v0.3.1 

func (d *DB) GetRunByWorkflowID(ctx context.Context, workflowID string) (*BackupRun, error)

GetRunByWorkflowID returns the run record created for a Temporal workflow execution

func (*DB) GetTargetByID 

func (d *DB) GetTargetByID(ctx context.Context, id uuid.UUID) (*BackupTarget, error)

func (*DB) ListAPIKeys 

func (d *DB) ListAPIKeys(ctx context.Context) ([]*APIKey, error)

func (*DB) ListAgents 

func (d *DB) ListAgents(ctx context.Context) ([]*Agent, error)

func (*DB) ListEnrollmentTokens 

func (d *DB) ListEnrollmentTokens(ctx context.Context) ([]*EnrollmentToken, error)

func (*DB) ListJobs 

func (d *DB) ListJobs(ctx context.Context) ([]*BackupJob, error)

func (*DB) ListRuns 

func (d *DB) ListRuns(ctx context.Context, limit int) ([]*BackupRun, error)

func (*DB) ListTargets 

func (d *DB) ListTargets(ctx context.Context) ([]*BackupTarget, error)

func (*DB) MarkRunStarted added in v0.3.1 

func (d *DB) MarkRunStarted(ctx context.Context, id uuid.UUID, temporalRunID string, startedAt time.Time) error

MarkRunStarted moves a pending run to running once the workflow has prepared the session

func (*DB) Migrate 

func (d *DB) Migrate(ctx context.Context) error

Migrate applies all pending schema migrations to PostgreSQL. Each migration runs in its own transaction and is recorded in schema_migrations so it is applied exactly once.

func (*DB) RevokeAPIKey 

func (d *DB) RevokeAPIKey(ctx context.Context, id uuid.UUID) error

func (*DB) RevokeAgent 

func (d *DB) RevokeAgent(ctx context.Context, id uuid.UUID) error

RevokeAgent marks the agent as revoked; its tokens stop validating immediately

func (*DB) SetRunStatus added in v0.3.1 

func (d *DB) SetRunStatus(ctx context.Context, id uuid.UUID, status RunStatus, message string, endTime *time.Time) error

SetRunStatus updates the status (and optionally end time / message) of a run

func (*DB) TouchAPIKey 

func (d *DB) TouchAPIKey(ctx context.Context, id uuid.UUID) error

TouchAPIKey records the last use of a key (best-effort, called on successful auth)

func (*DB) UpdateAgentHeartbeat 

func (d *DB) UpdateAgentHeartbeat(ctx context.Context, id uuid.UUID, status AgentStatus) error

func (*DB) UpdateRun 

func (d *DB) UpdateRun(ctx context.Context, run *BackupRun) error

func (*DB) UpsertAgent 

func (d *DB) UpsertAgent(ctx context.Context, agent *Agent) error

func (*DB) ValidateAndConsumeToken 

func (d *DB) ValidateAndConsumeToken(ctx context.Context, tokenHash string) (*EnrollmentToken, error)

type EnrollmentToken 

type EnrollmentToken struct {
	ID        uuid.UUID `json:"id" db:"id"`
	TokenHash string    `json:"-" db:"token_hash"`
	Name      string    `json:"name" db:"name"`
	MaxUses   int       `json:"max_uses" db:"max_uses"`
	UsesCount int       `json:"uses_count" db:"uses_count"`
	ExpiresAt time.Time `json:"expires_at" db:"expires_at"`
	CreatedAt time.Time `json:"created_at" db:"created_at"`
}

EnrollmentToken represents a one-time or multi-use token for agent onboarding

type Migration 

type Migration struct {
	Version int
	Name    string
	SQL     string
}

Migration is a single embedded SQL migration file

func LoadMigrations 

func LoadMigrations() ([]Migration, error)

LoadMigrations returns the embedded migrations ordered by version. Files are named NNN_description.sql; the numeric prefix is the version.

type RetentionPolicy 

type RetentionPolicy struct {
	KeepLast    int `json:"keep_last"`
	KeepDaily   int `json:"keep_daily"`
	KeepWeekly  int `json:"keep_weekly"`
	KeepMonthly int `json:"keep_monthly"`
	KeepYearly  int `json:"keep_yearly"`
}

RetentionPolicy defines backup retention counts

func (RetentionPolicy) ToJSON 

func (r RetentionPolicy) ToJSON() []byte

Helper to serialize RetentionPolicy to JSON bytes

type RunStatus 

type RunStatus string

RunStatus represents the state of a backup run 

const (
	RunStatusPending   RunStatus = "pending"
	RunStatusRunning   RunStatus = "running"
	RunStatusCompleted RunStatus = "completed"
	RunStatusFailed    RunStatus = "failed"
	// RunStatusCancelling: cancellation requested, waiting for the agent to stop
	RunStatusCancelling RunStatus = "cancelling"
	RunStatusCancelled  RunStatus = "cancelled"
)

func (RunStatus) IsActive added in v0.3.1 

func (s RunStatus) IsActive() bool

IsActive reports whether a run can still be cancelled

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.