Documentation
¶
Overview ¶
Package router assigns every classified statement to an execution backend. It sits between the planner (which decides what must change and how PostgreSQL would treat it) and the executors (which decide how a change actually runs), and is the single place migration policy lives: which backends exist, which are available, and what happens to a statement whose backend is not built yet. Callers branch on the typed Backend and Disposition, never on prose.
This is a periphery package (see SAFETY.md): a routed plan is a request. Executors enforce their own protections regardless of the route.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend string
Backend identifies an execution strategy.
const ( // BackendNative runs the change as direct PostgreSQL DDL (the safer // online idiom when the planner constructed one) under bounded // lock_timeout / statement_timeout. BackendNative Backend = "native" // BackendCopyAndSwap performs the change as a shadow-table copy with a // logical-replication catch-up and a locked cutover swap. BackendCopyAndSwap Backend = "copy-and-swap" )
The backends the router can assign. A refused statement has no backend.
func Backends ¶
func Backends() []Backend
Backends returns the closed set of Backend values. It is part of the plan-report contract (docs/plan-report.md): the set changes only with a format_version bump, and a consumer that meets an unrecognized value must treat the statement as unknown and refuse it.
type Disposition ¶
type Disposition string
Disposition is what would happen to one statement if the routed plan were executed now.
const ( // DispositionExecute: the assigned backend is available; the statement // would run. DispositionExecute Disposition = "execute" // DispositionRewriteRequired: the planner says the submitted form // blocks and must run as a safer idiom, but no executable rewrite was // constructed (a multi-operation statement, or a pattern the planner // cannot build). The statement will be refused at execution rather // than run in its blocking form. DispositionRewriteRequired Disposition = "rewrite-required" // not implement; the statement would be refused at execution. DispositionUnavailable Disposition = "unavailable" // DispositionRefuse: the planner refused the statement; no backend is // assigned. DispositionRefuse Disposition = "refuse" )
The dispositions a routed statement can carry.
func Dispositions ¶
func Dispositions() []Disposition
Dispositions returns the closed set of Disposition values, in severity order. It is part of the plan-report contract (docs/plan-report.md): the set changes only with a format_version bump, and a consumer that meets an unrecognized value must treat the statement as unknown and refuse it.
type Plan ¶
type Plan struct {
// Statements are the routed statements, in input order.
Statements []Statement `json:"statements"`
// Disposition is the aggregate disposition.
Disposition Disposition `json:"disposition"`
}
Plan is the routed plan for an ordered statement list: one routed statement per input plan plus the aggregate disposition (the worst of its statements — one unavailable backend makes the whole plan unavailable, one refusal refuses it).
type Statement ¶
type Statement struct {
planner.Plan
// Backend is the assigned execution strategy; empty for refusals.
Backend Backend `json:"backend,omitempty"`
// Disposition is what execution would do with the statement now.
Disposition Disposition `json:"disposition"`
// ExecSQL is the ordered SQL the native backend would run: the
// planner's safer sequence when it constructed one, otherwise the
// submitted statement. Execution contract: the steps run one at a
// time, in order, each in its own implicit transaction — never wrapped
// in an enclosing transaction block, which the CONCURRENTLY forms
// refuse. Empty for non-native routes and for statements the engine
// will not run (DispositionRewriteRequired).
ExecSQL []string `json:"exec_sql,omitempty"`
}
Statement is one routed statement: the planner's classification plus the backend assignment and the literal SQL the native backend would execute.
Source Files