snapshot

Documentation

Overview

Package snapshot turns the runtime SQLite DB into a content-addressed, checksummed, model-versioned artifact and restores one SAFELY.

Safety invariants (see internal docs/todo-architecture-saas-fleet.md and the plan):

• Restore is replace, never in-place execute. The dump SQL is never run against the live/migrated runtime DB. It is restored into a fresh temp DB, migrated + sanity-checked there, then atomically renamed into place.
• No silent downgrade. Bootstrap applies only when the runtime DB is fresh; replacing a populated DB requires an explicit force.
• Incompatible artifacts are rejected loudly (checksum + model/cache version + kind/format), never silently misrouted.

It reuses the existing sqlite3dump primitive (chassis/dbcache uses the same library) — this is codification of an existing capability, not new machinery.

Index

• Constants
• Variables
• func Bootstrap(data []byte, m Manifest, runtimeDBPath string, ...) error
• func IsFresh(runtimeDBPath string) bool
• func RestoreToTempDB(data []byte, m Manifest, destDir string) (string, error)
• func Verify(data []byte, m Manifest) error
• type Manifest
  • func Export(runtimeDBPath string) ([]byte, Manifest, error)

Constants

const (
	// KindBootstrapSQLiteDump is the only artifact kind this package
	// produces/consumes today. A different kind is rejected by Verify.
	KindBootstrapSQLiteDump = "bootstrap.sqlite.dump"
	// FormatSQLite3DumpSQL is the on-disk payload format (SQL text).
	FormatSQLite3DumpSQL = "sqlite3dump.sql"
)

Variables

var (
	// ErrVerify is returned when an artifact fails integrity/compatibility.
	ErrVerify = errors.New("snapshot: artifact verification failed")
	// ErrNotFresh is returned when Bootstrap would replace a populated DB
	// without force (the no-silent-downgrade invariant).
	ErrNotFresh = errors.New("snapshot: runtime DB is not fresh (use force to replace)")
)

Functions

func Bootstrap

func Bootstrap(data []byte, m Manifest, runtimeDBPath string,
	migrate func(dbPath string) error, force bool) error

Bootstrap is the safe end-to-end restore: verify → restore into a fresh temp DB → migrate that temp DB → sanity-check → atomically rename into place. The runtime DB is untouched until the final rename. migrate runs the chassis migrator against the given (temp) DB path.

If the runtime DB is not fresh, Bootstrap refuses unless force is true.

func IsFresh

func IsFresh(runtimeDBPath string) bool

IsFresh reports whether the runtime DB at path is empty/absent. A non-fresh DB must not be replaced without force (no-silent-downgrade).

func RestoreToTempDB

func RestoreToTempDB(data []byte, m Manifest, destDir string) (string, error)

RestoreToTempDB verifies data, then writes it into a BRAND-NEW sqlite file in destDir. It never touches the runtime DB. The returned path is the temp DB; the caller is responsible for migrating, sanity-checking and renaming (or removing) it. On any error nothing durable is left behind.

func Verify

func Verify(data []byte, m Manifest) error

Verify checks integrity and compatibility. Loud failure, never silent.

Types

type Manifest

type Manifest struct {
	Kind                 string `json:"kind"`
	Format               string `json:"format"`
	Checksum             string `json:"checksum"` // "sha256:<hex>"
	ControlModelVersion  int    `json:"control_model_version"`
	CacheSchemaVersion   int    `json:"cache_schema_version"`
	ControlVersion       uint64 `json:"control_version"`
	CreatedAt            string `json:"created_at"`
	SourceChassisVersion string `json:"source_chassis_version"`
	DBMigrationVersion   string `json:"db_migration_version"`
}

Manifest is the artifact sidecar. Every field is written now so a future incompatibility is rejected cleanly without a format change.

func Export

func Export(runtimeDBPath string) ([]byte, Manifest, error)

Export dumps runtimeDBPath into a self-contained artifact + manifest.