Documentation
¶
Overview ¶
Package flags holds the command-line flags shared by the migrate, move and sync commands.
The three commands used to declare these separately, with defaults, help text and validation that drifted apart (move's --threads defaulted to 2, the others to 4; only migrate had the TLS flags). Common is embedded in each command's Kong struct, so each flag, its default and its validation are declared once. Cutover holds the flags of the two commands that end in a cutover (migrate and move); sync runs continuously and has none.
The autoscaling setup that turns these flags into thread counts is concurrency.Engage.
Index ¶
Constants ¶
const ( DefaultThreads = 4 DefaultWriteThreads = 4 DefaultMaxConnections = dbconn.DefaultMaxConnections DefaultCheckpointMaxAge = 7 * 24 * time.Hour )
The defaults below must match the `default:` Kong tags on Common, so a programmatic caller that leaves a field unset (Normalize) lands on the same value the CLI does.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Common ¶
type Common struct {
// Threads is the number of read workers: the copier's read side and the
// checksum's workers.
Threads int `` /* 213-byte string literal not displayed */
// WriteThreads is the number of apply (write) workers, per target.
WriteThreads int `` /* 216-byte string literal not displayed */
// MaxConnections is the size of each connection pool spirit opens to a
// source or target server, set verbatim and never recomputed. Its
// connections are the server's max_connections, shared with the
// production workload, so it is spirit's claim on someone else's budget
// and spirit does not derive it from anything: worker counts never grow it.
MaxConnections int `` /* 199-byte string literal not displayed */
// TargetChunkSize is the in-memory byte budget the copier sizes each copy
// chunk against (the memory signal; see table.DefaultTargetChunkBytes and
// pkg/table/README.md). Zero means "use the default" (Normalize fills it in).
TargetChunkSize uint64 `` /* 209-byte string literal not displayed */
// MaxCommitLatency throttles when a target's average commit latency exceeds
// this threshold. Auto-enabled only on Aurora targets; zero disables it.
// See issue #468. It also decides whether autoscaling may grow write
// threads past their start on a redo-aware signal (see
// throttler.ResolveMaxWriteThreads).
MaxCommitLatency time.Duration `` /* 160-byte string literal not displayed */
// SkipAutoscaling turns off dynamic thread scaling driven by the targets'
// Aurora load signal, which is on by default. When autoscaling engages
// (concurrency.Engage) it takes over both thread counts: Threads and
// WriteThreads are replaced with instance-derived starting sizes, and each
// pool scales between bounds derived from the instance. An Aurora target
// below autoscale.MinVCPUs gets small-instance mode instead, which also
// replaces both counts. It only engages on Aurora; on other servers this
// flag has no effect. See issue #831.
SkipAutoscaling bool `` /* 408-byte string literal not displayed */
// ThreadsAreBaseline declares that Threads and WriteThreads are the
// caller's baseline for servers autoscaling does not engage on, not a load
// cap. It is for programmatic callers that embed spirit and pass their own
// non-default counts on every run. Autoscaling and small-instance mode
// still replace the counts on Aurora; this only silences the warning that
// they did, which otherwise fires on every Aurora run and names a CLI flag
// (--skip-autoscaling) such a caller may not expose. A caller whose counts
// are a cap sets SkipAutoscaling instead. It is not a CLI flag: a
// non-default count passed on the command line is an explicit choice.
ThreadsAreBaseline bool `kong:"-"`
// CheckpointMaxAge is the oldest checkpoint a run will resume from. Its
// age is the time since the checkpoint row was last written, i.e. how long
// the previous run has been stopped. What happens to a checkpoint that is
// too old is per-command: migrate starts fresh, move and sync fail (their
// targets are not empty) and point at --force or a larger value. Zero
// means the default (Normalize fills it in).
CheckpointMaxAge time.Duration `name:"checkpoint-max-age" help:"Maximum age of a checkpoint before refusing to resume from it" optional:"" default:"168h"`
// InterpolateParams sets the driver's interpolateParams on every
// connection: client-side placeholder interpolation instead of
// server-side prepared statements.
InterpolateParams bool `name:"interpolate-params" help:"Enable interpolate params for DSN" optional:"" default:"false" hidden:""`
// TLS Configuration. Empty keeps the connection config's own value
// (dbconn's PREFERRED default, or what a conf file supplied), and a DSN's
// own tls= parameter takes precedence over both.
TLSMode string `` /* 142-byte string literal not displayed */
TLSCertificatePath string `name:"tls-ca" help:"Path to custom TLS CA certificate file" optional:""`
}
Common is the configuration shared by migrate, move and sync. It is embedded (anonymously) in each command's Kong struct, so its fields are promoted: m.Threads keeps working, but a composite literal must name the embedded struct, e.g. migration.Migration{Common: flags.Common{Threads: 8}}.
Zero thread counts, connection counts and chunk sizes mean "use the default" (Normalize fills them in); negative ones are rejected by Validate. A zero MaxCommitLatency is not replaced: it disables the commit-latency throttler.
func (*Common) ApplyTo ¶
ApplyTo copies the connection-level flags onto a connection config: the pool size, TLS and parameter interpolation. Zero or empty values leave the config's own value alone, so a programmatic caller that never set one keeps dbconn's default. Callers that want a different pool size for a dedicated pool (a monitor, a replica) override MaxOpenConnections afterwards.
func (*Common) Normalize ¶
func (c *Common) Normalize()
Normalize fills in the defaults for zero counts, so a programmatic caller that leaves a field unset gets what the CLI does.
func (*Common) Validate ¶
Validate rejects explicitly negative thread counts and durations. Zero values are accepted and mean "use the default". Each command validates MaxConnections itself, because the smallest usable pool depends on what the command runs on it (dbconn.ValidateMaxConnections vs dbconn.ValidateConnectionLimit).
func (*Common) ValidationThreads ¶
ValidationThreads is the read-thread count a run will start with, for validating MaxConnections before Normalize has run.
func (*Common) WarnZeroWriteThreads ¶
WarnZeroWriteThreads warns when WriteThreads is zero, before Normalize replaces it with the default. In migrate and move a zero used to mean "auto-size from the instance", so anyone who relied on that would otherwise see their apply pool quietly drop from the instance vCPU count to the default. Sync always treated zero as the default, so it does not call this. (Kong's default is non-zero, so a literal 0 was either passed explicitly or left unset by a programmatic caller.)
type Cutover ¶
type Cutover struct {
// ForceKillAfter and LockWaitTimeout bound how long spirit's DDL and table
// locks wait on the workload, and when spirit kills the transactions
// blocking them. A zero ForceKillAfter means 90% of LockWaitTimeout; a zero
// LockWaitTimeout keeps dbconn's default.
ForceKillAfter time.Duration `` /* 150-byte string literal not displayed */
LockWaitTimeout time.Duration `name:"lock-wait-timeout" help:"The DDL lock_wait_timeout required for checksum and cutover" optional:"" default:"30s"`
// DeferCutOver creates the sentinel table before the copy, so the run
// blocks before cutover (running a continuous checksum) until an operator
// drops it. Only a deferred run waits on the sentinel: see WaitsOnSentinel.
DeferCutOver bool `` /* 131-byte string literal not displayed */
}
Cutover is the configuration shared by the commands that end in a cutover: migrate and move. Sync runs continuously, takes no table locks and has no sentinel, so it does not embed it. Like Common it is embedded anonymously, so a composite literal must name it, e.g. move.Move{Cutover: flags.Cutover{DeferCutOver: true}}.
func (*Cutover) ApplyTo ¶
ApplyTo copies the lock timeouts onto a connection config. A zero LockWaitTimeout leaves the config's own value alone.
func (*Cutover) Validate ¶
Validate rejects a negative LockWaitTimeout (ApplyTo would silently keep the default) and a ForceKillAfter that leaves no time to acquire a lock.
func (*Cutover) WaitsOnSentinel ¶
WaitsOnSentinel reports whether the run blocks before cutover while the sentinel table exists. Only a deferred run does, and DeferCutOver is fixed when the run starts. A run that did not ask to defer cuts over even if a sentinel is present, whether an operator created it during the run or an earlier deferred run that was cancelled or failed left it behind, so a stray sentinel never holds a cutover nobody deferred.
Source Files