appprepare

package
v1.166.0 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package appprepare prepares an application written for one schema to run in environments of their own (#2709). An application's environments each run in a schema of their own, with the search path set to it, so SQL that names the application's schema, and migrations that name its roles, would reach another environment's data from whichever environment runs them. While anything in the application does, a new environment is refused, and prepare proposes the same text with the schema qualifier and the role statements removed. In the application's current schema the search path is already that schema, so the change does nothing there; the save gate replays each changed script's recent recorded runs to show the answers are the same, and a difference blocks the save.

Index

Constants

View Source
const (
	KindScript    = "script"
	KindLibrary   = "library"
	KindMigration = "migration"
)

The kinds of file a plan lists.

Variables

View Source
var ErrNotReady = errors.New("prepare saves nothing while the save gate refuses a file; see each file's refusal and differences")

ErrNotReady refuses saving a plan the save gate refuses a file of.

Functions

This section is empty.

Types

type Counts

type Counts struct {
	Scripts    int `json:"scripts"`
	Libraries  int `json:"libraries"`
	Migrations int `json:"migrations"`
}

Counts is how many of an application's files name its schema or roles.

func (Counts) Total

func (c Counts) Total() int

Total is every file counted.

type File

type File struct {
	Kind string `json:"kind" example:"script"`
	// ID is a script's or library's id, a migration's version.
	ID   string `json:"id" example:"5b0c..."`
	Name string `json:"name" example:"orders-api"`
	// Version is the version changed: a script's current version, a
	// migration's own.
	Version int `json:"version" example:"4"`
	// Names is how many names of the schema or its roles it holds.
	Names  int    `json:"names" example:"3"`
	Before string `json:"before"`
	After  string `json:"after"`
	// Replayed is the recorded runs the save gate replayed against the new
	// text, and Differences what any of them answered differently.
	Replayed    []string                    `json:"replayed"`
	Differences []scriptbehavior.Difference `json:"differences"`
	// Refusal is why the save gate refuses the new text, empty when it does
	// not.
	Refusal string `json:"refusal,omitempty"`
	// Saved is the version saved, 0 until it is.
	Saved int `json:"saved,omitempty"`
}

File is one file prepare changes: what it names, the text before and after, and for a script or library what the save gate made of the new text.

type Gate

type Gate interface {
	Check(ctx context.Context, req scriptsave.Request) scriptsave.Result
}

Gate is the save gate a script's new source crosses.

type Libraries

type Libraries interface {
	LibrarySource(ctx context.Context, name string, version int) (string, error)
	LibraryNamed(ctx context.Context, name string) (*script.Script, error)
}

Libraries reads a library's version and its record by name.

type Migrations

type Migrations interface {
	List(ctx context.Context, connection, schema string) ([]postgreskit.Migration, error)
	Put(ctx context.Context, m postgreskit.Migration) (bool, error)
}

Migrations reads and replaces the application's migrations.

type Pending

type Pending interface {
	StateIn(ctx context.Context, at appschema.Target) (*appschema.State, error)
}

Pending reads which of the application's migrations its schema has not applied.

type Plan

type Plan struct {
	Application string `json:"application" example:"shop"`
	Schema      string `json:"schema" example:"orders"`
	Files       []File `json:"files"`
	// Values is each qualified name inside a quoted SQL value: data, such as
	// an outbox row's source table, that prepare leaves as written. Each
	// environment needs its own text there (current_schema() || '.invoices'),
	// so a person changes it; it does not block an environment.
	Values []Value `json:"values"`
	Counts Counts  `json:"counts"`
	// Ready is true when nothing names the schema or its roles, so an
	// environment can be added.
	Ready bool `json:"ready"`
	// Saved is true when the plan's changes were saved.
	Saved bool `json:"saved"`
}

Plan is what prepare does to one application.

type Preparer

type Preparer struct {
	Scripts    Scripts
	Libraries  Libraries
	Migrations Migrations
	Schema     Pending
	Gate       Gate
	// Recordings is where a script's recorded runs are kept: the ones its
	// tests and the save gate replay are stored again with the same
	// statements rewritten once its new version is saved, so the next save
	// still replays them (#2709). Nil rewrites none.
	Recordings scriptrec.Store
}

Preparer prepares applications.

func (*Preparer) Named

Named counts the files of a that name its schema or its roles: its scripts, the libraries they load and its pending migrations. An application holding no schema names none.

func (*Preparer) Plan

func (p *Preparer) Plan(ctx context.Context, a *application.Application, caller scriptsave.Caller) (*Plan, error)

Plan is what prepare would change in a, each changed script and library put through the save gate without saving.

func (*Preparer) Save

func (p *Preparer) Save(ctx context.Context, a *application.Application, caller scriptsave.Caller, author script.Author) (*Plan, error)

Save saves what Plan proposes: each library a new version, each script a new version loading the libraries' new versions, each pending migration replaced. Nothing is saved while the save gate refuses a script or a library; a library saved before a script it is loaded by is refused stays a version nothing loads.

type Scripts

type Scripts interface {
	GetByID(ctx context.Context, id string) (*script.Script, error)
	UpdateWithVersion(ctx context.Context, sc *script.Script, author script.Author) error
}

Scripts reads an application's scripts and saves their new versions.

type Value

type Value struct {
	Kind string `json:"kind" example:"script"`
	Name string `json:"name" example:"orders-api"`
	Line int    `json:"line" example:"86"`
	Text string `json:"text" example:"orders.invoices"`
}

Value is one qualified name inside a quoted SQL value of a file.

Jump to

Keyboard shortcuts

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