Documentation
¶
Overview ¶
Package migrate upgrades and repairs a project's .cloop directory.
The project database belongs to pkg/statedb, which migrates it every time anything opens it: numbered migrations embedded in the binary, recorded in schema_migrations. This package used to run a second schema system beside that one (Task 187) — its own version number in metadata.schema_version, its own CREATE TABLE for a converted state.json, its own ALTER TABLE on plan_tasks — and the two disagreed (Task 20374):
- statedb never wrote schema_version, so every project created by a current binary read as version 1 of 2, and every interactive command told its user to run `cloop migrate` on a project that was up to date;
- the state.json conversion created three of the six tables statedb's first migration does, so statedb adopted the result as version 1 and then failed on the first later migration that touched a missing table — and every command that opened the project failed with it;
- the ALTER TABLE added plan_tasks columns statedb did not know about until migration 0054 had to adopt them.
So this package no longer has a schema. It reports what a project's state storage is without writing to it (Inspect), says whether the project needs `cloop migrate` (NeedsUpgrade), and when it does, Run hands the work to the code that owns the schema: pkg/state converts a legacy state.json, through statedb, exactly as Load would; statedb.Open adopts a database its framework has never seen and applies whatever migrations are pending.
Two kinds of project need it, and only these: a legacy one whose state exists only in state.json, and one whose state.db predates statedb's migration framework. Every other database is statedb's own, and is migrated whenever anything opens it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NeedsUpgrade ¶
NeedsUpgrade reports whether workDir holds a project that needs `cloop migrate`: one whose state exists only in a legacy state.json, or whose state.db predates statedb's migrations. A database statedb owns is migrated whenever anything opens it and never needs this, whatever its version. Any doubt — no project, an unreadable database — answers false: this decides whether every command prints a warning, and a wrong warning on every command is the defect it was rewritten for.
Types ¶
type Kind ¶ added in v0.0.5
type Kind string
Kind is what a project's state storage is.
const ( // KindNone is a directory with no project state. KindNone Kind = "none" // KindLegacyJSON is a project whose state exists only in state.json: no // state.db, or one that holds no project. KindLegacyJSON Kind = "legacy-json" // KindPreStatedb is a state.db that statedb's migration framework has // never opened: it has no schema_migrations table. KindPreStatedb Kind = "pre-statedb" // KindStatedb is a state.db statedb owns, which is migrated whenever // anything opens it. KindStatedb Kind = "statedb" )
type RepairReport ¶
type RepairReport struct {
Kind string // "orphan_snapshot", "invalid_config_key"
Detail string
Fixed bool
}
RepairReport describes a single repair action.
type Report ¶
type Report struct {
DryRun bool
// Before is the state storage Run found; After is what it left, which on
// a dry run is Before again.
Before Status
After Status
Steps []StepReport
// Warnings are conditions Run did not change and the operator should
// know about.
Warnings []string
}
Report summarises what Run did, or on a dry run would do.
type Status ¶ added in v0.0.5
type Status struct {
Kind Kind
// DBPath and JSONPath are where the database and the legacy file are, or
// would be — the active session's when one is active.
DBPath string
JSONPath string
// SchemaVersion is the highest statedb migration the database records;
// zero when it records none.
SchemaVersion int
// LatestVersion is the highest migration this binary carries.
LatestVersion int
// LegacyNewer reports a state.json beside a database it is newer than:
// something older than this binary is still writing the legacy file, and
// loading the project converts it again.
LegacyNewer bool
}
Status describes a project's state storage. Inspect produces it without writing anything.
func Inspect ¶ added in v0.0.5
Inspect reports what workDir's state storage is. It never writes: the database is read through a read-only handle, so asking cannot migrate it, create it, or wait on anything but another process's lock.
func (Status) Ahead ¶ added in v0.0.5
Ahead reports a database migrated past this binary, which statedb refuses to open (see statedb's schema guard).
type StepReport ¶
StepReport is one thing Run did or would do.
Source Files