migrationview

package
v0.2.13 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package migrationview reads what the operator stored about one migration.

It is the read side of the migration path: what the database's own history said when it was last read, which sequence the operator would run next, and what the last run did. It connects to no database and reads no Secret.

Beside the migration it lists the PtahMigrationApprovals and the PtahMigrationRunAcknowledgments that name it: the decisions people made about its plans and about a run nobody accounted for. Listing them takes a permission reading the migration does not, so a reader without it still gets the migration, and a line that says why the decisions are missing.

Index

Constants

This section is empty.

Variables

View Source
var ErrMigrationNotFound = errors.New("no PtahMigration by that name")

ErrMigrationNotFound is returned when the named PtahMigration is not there. It is separate from a read failure: "there is nothing by that name" is an answer.

View Source
var Formats = []Format{Text, JSON}

Formats are the accepted values, in the order the help lists them.

Functions

func Render

func Render(out io.Writer, view View, format Format) error

Render writes one view in the requested format.

Types

type AcknowledgmentView added in v0.2.9

type AcknowledgmentView struct {
	Name        string      `json:"name"`
	CreatedAt   metav1.Time `json:"createdAt"`
	OperationID string      `json:"operationID"`
	// NamesUnresolvedRun says the acknowledgment names the run the migration
	// records as unresolved now. One that names any other run settles nothing.
	NamesUnresolvedRun bool                              `json:"namesUnresolvedRun"`
	AcknowledgedBy     operatorv1alpha1.ApprovalIdentity `json:"acknowledgedBy"`
	AcknowledgedAt     metav1.Time                       `json:"acknowledgedAt"`
	Conditions         []ConditionView                   `json:"conditions,omitempty"`
}

AcknowledgmentView is one PtahMigrationRunAcknowledgment that names this migration: the run it settles, who made the statement, and whether the controller took it.

type ApprovalView added in v0.2.9

type ApprovalView = statusview.Approval

ApprovalView is one PtahMigrationApproval that names this migration. A migration approval carries only Consumed, or Stale when a read withdrew it; whether it matches the plan is what CurrentPlan and the migration's own ApprovalRequired say.

type ArtifactView

type ArtifactView = sourceview.View

ArtifactView is the resolved, credential-free source binding: an OCI artifact, a ConfigMap and its snapshot, or a Git commit.

type ConditionView

type ConditionView = statusview.Condition

ConditionView is one published condition: what it says, and when and for which generation it was written.

type Details added in v0.2.11

type Details struct {
	// ReadRequested is the operator.ptah.run/read-requested-at annotation as
	// the migration holds it now. status.lastReadRequest is the last value
	// the controller answered.
	ReadRequested string                               `json:"readRequested,omitempty"`
	Status        operatorv1alpha1.PtahMigrationStatus `json:"status"`
}

Details is what --details adds: the status, and the read request the resource holds now, which the status answers.

Status is decoded into the API types this plugin was built with, so it holds every field this plugin's API version knows; a field a newer operator added to the stored object is not in it. The text prints every record of Status the view does not already print in full; the JSON carries Status as decoded, so a script reads the fields the API reference of this version documents.

type Format

type Format string

Format is how a reader asked to see a migration.

const (
	// Text is the default: the state, the history, the sequence, the last run.
	Text Format = "text"
	// JSON is the same view as a document, for a script.
	JSON Format = "json"
)

type HistoryView

type HistoryView struct {
	ObservedAt        metav1.Time `json:"observedAt"`
	CurrentVersion    int64       `json:"currentVersion"`
	CheckpointVersion int64       `json:"checkpointVersion,omitempty"`
	AppliedCount      int32       `json:"appliedCount"`
	PendingCount      int32       `json:"pendingCount"`
	Dirty             bool        `json:"dirty,omitempty"`
	ModifiedVersions  []int64     `json:"modifiedVersions,omitempty"`
	// OutOfOrderVersions names migrations that sort below the current version.
	// Linear execution refuses them, so a reader of this view has to see which
	// ones rather than a phase that says the history is blocked.
	OutOfOrderVersions []int64 `json:"outOfOrderVersions,omitempty"`
	Fingerprint        string  `json:"fingerprint,omitempty"`
}

HistoryView is what the revision table said when it was last read.

type PlanView

type PlanView struct {
	Name           string                 `json:"name"`
	UID            string                 `json:"uid,omitempty"`
	Fingerprint    string                 `json:"fingerprint"`
	CurrentVersion int64                  `json:"currentVersion"`
	CreatedAt      metav1.Time            `json:"createdAt"`
	Migrations     []PlannedMigrationView `json:"migrations"`
}

PlanView is the sequence the operator would run next. A migration plan holds versions and checksums rather than SQL: the statements live in the artifact, and printing them here would mean fetching it.

type PlannedMigrationView

type PlannedMigrationView struct {
	Version         int64  `json:"version"`
	VersionKey      string `json:"versionKey,omitempty"`
	Description     string `json:"description,omitempty"`
	Checksum        string `json:"checksum"`
	Checkpoint      bool   `json:"checkpoint,omitempty"`
	TransactionMode string `json:"transactionMode,omitempty"`
}

PlannedMigrationView is one migration of the sequence.

type PolicyView added in v0.2.9

type PolicyView struct {
	Apply string `json:"apply,omitempty"`
}

PolicyView is the spec's apply mode: whether a planned sequence runs never, with an approval, or as soon as it is planned.

type ResolvedRunView added in v0.2.9

type ResolvedRunView struct {
	OperationID        string      `json:"operationID"`
	Outcome            string      `json:"outcome"`
	Resolution         string      `json:"resolution"`
	AcknowledgmentName string      `json:"acknowledgmentName,omitempty"`
	AcknowledgedBy     string      `json:"acknowledgedBy,omitempty"`
	ResolvedAt         metav1.Time `json:"resolvedAt"`
}

ResolvedRunView is how the most recent unresolved run was settled: by a history read, or by a person's acknowledgment.

type RunView

type RunView struct {
	Outcome         string       `json:"outcome"`
	JobName         string       `json:"jobName,omitempty"`
	JobUID          string       `json:"jobUID,omitempty"`
	StartedAt       metav1.Time  `json:"startedAt"`
	FinishedAt      *metav1.Time `json:"finishedAt,omitempty"`
	AppliedVersions []int64      `json:"appliedVersions,omitempty"`
	Message         string       `json:"message,omitempty"`
	// Failure is where a failed or partial run stopped, when a statement
	// reached the database and failed there.
	Failure *operatorv1alpha1.MigrationRunFailureStatus `json:"failure,omitempty"`
	// MigrationLog is what the run's writes to schema_migrations_log came to,
	// where the run reported it.
	MigrationLog *operatorv1alpha1.MigrationLogStatus `json:"migrationLog,omitempty"`
	// OperationID, PlanRef, PlanFingerprint, Authorization, ArtifactDigest,
	// Source, TargetIdentityDigest, ExecutionBindingID and Verification are what
	// the run's record says it carried out, who allowed it and what the reading
	// after it found. Each is absent where the record does not hold it, which is
	// every one of them on a run a release before those fields recorded.
	OperationID          string                                            `json:"operationID,omitempty"`
	PlanRef              *operatorv1alpha1.ImmutableObjectReference        `json:"planRef,omitempty"`
	PlanFingerprint      string                                            `json:"planFingerprint,omitempty"`
	Authorization        *operatorv1alpha1.MigrationRunAuthorizationStatus `json:"authorization,omitempty"`
	ArtifactDigest       string                                            `json:"artifactDigest,omitempty"`
	Source               *operatorv1alpha1.PlanSourceBinding               `json:"source,omitempty"`
	TargetIdentityDigest string                                            `json:"targetIdentityDigest,omitempty"`
	ExecutionBindingID   string                                            `json:"executionBindingID,omitempty"`
	Verification         *operatorv1alpha1.MigrationRunVerificationStatus  `json:"verification,omitempty"`
}

RunView is what the database accounted for after the last execution, and which Job that execution was. The Job's UID is what tells a replacement Job with the same name apart from the run it replaced.

type UnresolvedRunView added in v0.2.9

type UnresolvedRunView struct {
	Outcome     string `json:"outcome"`
	OperationID string `json:"operationID"`
	// JobName and JobUID are empty where the API server never confirmed the
	// Job was created: the reserved name is not evidence that anything ran.
	JobName string                                    `json:"jobName,omitempty"`
	JobUID  string                                    `json:"jobUID,omitempty"`
	PlanRef operatorv1alpha1.ImmutableObjectReference `json:"planRef"`
	// TargetIdentityDigest is the credential-free identity of the database
	// the run's result named, or the one its plan was computed against where
	// it named none.
	TargetIdentityDigest string      `json:"targetIdentityDigest,omitempty"`
	RecordedAt           metav1.Time `json:"recordedAt"`
}

UnresolvedRunView is the execution whose effect on the database nobody has established. While it is recorded nothing is planned and nothing runs.

type View

type View struct {
	Namespace string `json:"namespace"`
	Migration string `json:"migration"`
	UID       string `json:"uid,omitempty"`
	// Generation is the spec's, and ObservedGeneration the one the status
	// was written for. They differ while the controller has not yet acted
	// on a spec change.
	Generation         int64         `json:"generation,omitempty"`
	ObservedGeneration int64         `json:"observedGeneration,omitempty"`
	Phase              string        `json:"phase,omitempty"`
	Suspended          bool          `json:"suspended,omitempty"`
	Policy             *PolicyView   `json:"policy,omitempty"`
	Artifact           *ArtifactView `json:"artifact,omitempty"`
	History            *HistoryView  `json:"history,omitempty"`
	Plan               *PlanView     `json:"plan,omitempty"`
	// LastRun is the most recent execution. UnresolvedRun is a different
	// record: the execution nobody has accounted for, which holds the
	// resource whatever the last run or the conditions say. ResolvedRun is
	// how the most recent such record was settled.
	LastRun       *RunView           `json:"lastRun,omitempty"`
	UnresolvedRun *UnresolvedRunView `json:"unresolvedRun,omitempty"`
	ResolvedRun   *ResolvedRunView   `json:"resolvedRun,omitempty"`
	Conditions    []ConditionView    `json:"conditions,omitempty"`
	// Approvals and Acknowledgments are the newest decisions that name this
	// migration, by name and UID. Each is absent when it could not be listed,
	// and then its Unreadable field says why: no list is not an empty list.
	Approvals                 *statusview.Decisions[ApprovalView]       `json:"approvals,omitempty"`
	ApprovalsUnreadable       *statusview.Unreadable                    `json:"approvalsUnreadable,omitempty"`
	Acknowledgments           *statusview.Decisions[AcknowledgmentView] `json:"acknowledgments,omitempty"`
	AcknowledgmentsUnreadable *statusview.Unreadable                    `json:"acknowledgmentsUnreadable,omitempty"`
	// Details is the status as this plugin's API version decodes it, present
	// only when it was asked for, so the view without it reads as it always
	// has.
	Details *Details `json:"details,omitempty"`
}

View is everything this command prints, resolved before anything is written.

func Load

func Load(
	ctx context.Context,
	reader client.Reader,
	namespace, name string,
) (View, error)

Load reads one migration, the plan it names, and the decisions that name it.

A plan the migration no longer names is not shown: the status reference is what makes a stored plan the current one, and a plan read by name alone could be one the operator already discarded. A decision list that cannot be read leaves the rest of the view as it was.

func LoadWithDetails added in v0.2.11

func LoadWithDetails(ctx context.Context, reader client.Reader, namespace, name string) (View, error)

LoadWithDetails reads the view and the status beside it, from the same read of the migration.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL