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
- Variables
- type Counts
- type File
- type Gate
- type Libraries
- type Migrations
- type Pending
- type Plan
- type Preparer
- func (p *Preparer) Named(ctx context.Context, a *application.Application) (Counts, error)
- func (p *Preparer) Plan(ctx context.Context, a *application.Application, caller scriptsave.Caller) (*Plan, error)
- func (p *Preparer) Save(ctx context.Context, a *application.Application, caller scriptsave.Caller, ...) (*Plan, error)
- type Scripts
- type Value
Constants ¶
const ( KindScript = "script" KindLibrary = "library" KindMigration = "migration" )
The kinds of file a plan lists.
Variables ¶
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.
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 ¶
func (p *Preparer) Named(ctx context.Context, a *application.Application) (Counts, error)
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.