Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AdoptCmd ¶
type AdoptCmd struct {
LockPath string `name:"lock" placeholder:"PATH" default:"w17/lock.yaml" help:"Path to the lock file."`
MigrationsDir string `name:"migrations" placeholder:"DIR" default:"w17/migrations" help:"Directory holding artifacts produced by fetch."`
Connections []string `` /* 276-byte string literal not displayed */
LogFormat string `name:"log-format" placeholder:"text|json" default:"text" enum:"text,json" help:"Per-migration log line format."`
}
AdoptCmd backs `w17ctl migrate adopt` — bringing a database that already HAS the schema under migration management, without running the DDL that would build it.
It is its own command rather than a flag on apply, and that is the whole design: an operation whose purpose is to skip the DDL must never be reached by inference. `apply` decides what to run; `adopt` is the operator saying "this database is already there", and the tool's job is to check that claim rather than take it.
The check is the console's: each artifact carries an `adopt_preflight_sql` that ensures the ledger exists and then fails unless the objects the migration introduces are present. A migration without one cannot be adopted — see migratesdk.RunAdopt for what that covers and why it refuses rather than waves through.
Offline, like apply. DSNs come from W17_TARGET_<CONN> exactly as they do there, so credentials stay off the flag surface.
type ApplyCmd ¶
type ApplyCmd struct {
LockPath string `name:"lock" placeholder:"PATH" default:"w17/lock.yaml" help:"Path to the lock file."`
MigrationsDir string `name:"migrations" placeholder:"DIR" default:"w17/migrations" help:"Directory holding artifacts produced by fetch."`
DryRun bool `name:"dry-run" help:"Print pending migrations without applying."`
LogFormat string `` /* 202-byte string literal not displayed */
Parallel int `` /* 221-byte string literal not displayed */
}
ApplyCmd applies pending migrations against each connection's target store. The DB-side wc_migrations table is the source of truth for what is already applied; pending = on-disk ∩ (id > applied_head, id ≤ target). Offline — never contacts the console. DSNs resolve from W17_TARGET_<CONN_UPPER> env vars ONLY (never a flag) so credentials don't leak into shell history / process listings / CI logs.
type Cmd ¶
type Cmd struct {
Generate GenerateCmd `` /* 226-byte string literal not displayed */
List ListCmd `cmd:"" help:"List migrations stored on the console for a project. Optional connection-name filter + pagination."`
PushRaw PushRawCmd `` /* 144-byte string literal not displayed */
Fetch FetchCmd `` /* 161-byte string literal not displayed */
Apply ApplyCmd `` /* 173-byte string literal not displayed */
Adopt AdoptCmd `` /* 322-byte string literal not displayed */
Rollback RollbackCmd `` /* 151-byte string literal not displayed */
Status StatusCmd `cmd:"" help:"Show each connection's pinned target migration + how many fetched artifacts are on disk. Offline, read-only."`
Reset ResetCmd `` /* 258-byte string literal not displayed */
VerifyHistory VerifyHistoryCmd `` /* 289-byte string literal not displayed */
Squash SquashCmd `` /* 265-byte string literal not displayed */
}
Cmd is the single `w17ctl migrate` parent — every migration-related verb lives here:
migrate generate — compile the proto schema + push it to the
console, which plans + stores the SQL
migrations and pins the lock target
migrate list — browse stored migration history (console)
migrate push-raw — push a hand-authored YAML body (escape hatch)
migrate reset — DEV-ONLY destructive recreate: drop the DB,
discard the console's migration history, and
push a fresh baseline
migrate verify-history — ask whether the recorded history reproduces
the stored schema (the clean-gate; read-only)
migrate squash — freeze a change request with its migrations:
collapse the history into one baseline the
collapsed rows point at (they are KEPT, which
is what separates this from reset)
The console is the single source of truth: it diffs the schema and emits the migrations. The old offline migrator tools (a local SQL `generate`, `verify`, `inspect`) are gone — there is no offline migration pipeline; `migrate generate` always goes through the console.
type FetchCmd ¶
type FetchCmd struct {
LockPath string `name:"lock" placeholder:"PATH" default:"w17/lock.yaml" help:"Path to the lock file."`
Console string `` /* 236-byte string literal not displayed */
MigrationsDir string `name:"out" placeholder:"DIR" default:"w17/migrations" help:"Output directory for fetched migrations."`
}
FetchCmd downloads every migration up to each connection's pinned target from the console's public MigrationFetch service, writing one artifact set per migration into the migrations directory ready for an offline `apply`. This is the only online step — everything after it (apply / rollback) runs without console reachability.
It dials the public MigrationFetch service (NOT the private registry client), so w17ctl's apply path carries zero console/client (registrypb) dependency.
type GenerateCmd ¶
type GenerateCmd struct {
Protos []string `` /* 160-byte string literal not displayed */
Imports []string `` /* 206-byte string literal not displayed */
ProjectID string `name:"project" placeholder:"ID" required:"" help:"Project identifier matching the consuming repo's w17/lock.yaml project_id."`
Console string `` /* 217-byte string literal not displayed */
LockPath string `` /* 202-byte string literal not displayed */
NoLock bool `` /* 153-byte string literal not displayed */
Initial bool `` /* 205-byte string literal not displayed */
Decide []string `` /* 273-byte string literal not displayed */
Initiative string `` /* 257-byte string literal not displayed */
}
GenerateCmd backs `w17ctl migrate generate` — the compiled-IR push to the console (formerly `w17ctl schema create/update`). It auto-detects create vs update by probing whether the project already has a stored schema, so the caller never picks the mode by hand; --initial forces the initial (create) push. The push machinery lives in internal/schema (RunSchemaPush).
func (*GenerateCmd) Run ¶
func (c *GenerateCmd) Run() error
type ListCmd ¶
type ListCmd struct {
ProjectID string `name:"project" short:"p" placeholder:"ID" required:"" help:"Project identifier."`
Connection string `` /* 153-byte string literal not displayed */
From string `name:"from" placeholder:"MIGRATION_ID" help:"Optional pagination cursor. Returned list starts strictly after this ID."`
UpTo string `name:"up-to" placeholder:"MIGRATION_ID" help:"Optional upper bound. Stream stops after emitting this ID."`
Console string `` /* 217-byte string literal not displayed */
}
ListCmd backs `w17ctl migrate list` — it queries the console's stored migration history.
type PushRawCmd ¶
type PushRawCmd struct {
ProjectID string `` /* 160-byte string literal not displayed */
Connection string `` /* 148-byte string literal not displayed */
BodyPath string `` /* 174-byte string literal not displayed */
Console string `` /* 217-byte string literal not displayed */
Initiative string `` /* 284-byte string literal not displayed */
}
PushRawCmd backs `w17ctl migrate push-raw` — a single- migration escape hatch (D-iter3-26) for hand-authored YAML bodies the schema-driven planner can't auto-emit, typically TRANSFORM_FIELD ops carrying author-supplied Starlark scripts. Reads the YAML body from a file, ships it to console via the PushRawMigration RPC. Console validates + signs + stores; returns the assigned migration id.
Use case: TRANSFORM_FIELD with a Starlark script the auto-emit path can't produce from a schema diff. Operator authors the YAML by hand; this command pushes it as the next migration on (project, connection).
**Escape hatch caveat:** the supplied body's effect must be consistent with the project's stored schema. Console doesn't verify the YAML's ops align with column / table state — that's the author's responsibility.
func (*PushRawCmd) Run ¶
func (c *PushRawCmd) Run() error
type ResetCmd ¶
type ResetCmd struct {
Force bool `` /* 221-byte string literal not displayed */
Up bool `` /* 129-byte string literal not displayed */
ProjectID string `name:"project" placeholder:"ID" help:"Project whose migration history is discarded. Empty = read project_id from the lock."`
Console string `` /* 215-byte string literal not displayed */
Protos []string `` /* 239-byte string literal not displayed */
Imports []string `` /* 145-byte string literal not displayed */
LockPath string `` /* 149-byte string literal not displayed */
NoLock bool `name:"no-lock" help:"Skip the lock-file write on the baseline push. Only read when --proto is given."`
LocalOnly bool `` /* 249-byte string literal not displayed */
}
ResetCmd implements `w17ctl migrate reset`.
type RollbackCmd ¶
type RollbackCmd struct {
LockPath string `name:"lock" placeholder:"PATH" default:"w17/lock.yaml" help:"Path to the lock file."`
MigrationsDir string `name:"migrations" placeholder:"DIR" default:"w17/migrations" help:"Directory holding artifacts produced by fetch."`
To string `` /* 189-byte string literal not displayed */
DryRun bool `name:"dry-run" help:"Print migrations that would roll back without running them."`
LogFormat string `` /* 181-byte string literal not displayed */
Parallel int `` /* 221-byte string literal not displayed */
}
RollbackCmd walks every applied migration with id strictly greater than --to, in REVERSE order, and runs each migration's down body against the per-connection target. Offline — never contacts the console. `--to` is the highest id to KEEP applied; --to="" rolls back everything currently applied. DSNs are env-only, same as apply.
func (*RollbackCmd) Run ¶
func (c *RollbackCmd) Run() error
type SquashCmd ¶
type SquashCmd struct {
Force bool `` /* 126-byte string literal not displayed */
Initiative string `` /* 273-byte string literal not displayed */
All bool `` /* 198-byte string literal not displayed */
ProjectID string `name:"project" placeholder:"ID" help:"Project whose history is collapsed. Empty = read project_id from the lock."`
Console string `` /* 215-byte string literal not displayed */
Protos []string `` /* 245-byte string literal not displayed */
Imports []string `` /* 145-byte string literal not displayed */
LockPath string `` /* 149-byte string literal not displayed */
NoLock bool `name:"no-lock" help:"Skip the lock-file write on the baseline push. Only read when --proto is given."`
}
SquashCmd implements `w17ctl migrate squash`.
type StatusCmd ¶
type StatusCmd struct {
MigrationsDir string `` /* 153-byte string literal not displayed */
}
StatusCmd reports, per lock-listed connection, the pinned target migration and how many fetched artifacts sit on disk. Fully OFFLINE + read-only — the local counterpart absorbed from w17migrate's `status`.
type VerifyHistoryCmd ¶
type VerifyHistoryCmd struct {
ProjectID string `name:"project" placeholder:"ID" help:"Project to check. Empty = read project_id from the lock."`
Console string `` /* 162-byte string literal not displayed */
Strict bool `` /* 286-byte string literal not displayed */
}
VerifyHistoryCmd implements `w17ctl migrate verify-history` — the clean-gate, asked out loud.
The predicate has existed server-side since revisions landed and had NO client surface: it ran only as `UpdateSchema`'s own drift guard, so the only way an operator ever met the answer was a push refused with it quoted in the error. That is late and back-to-front — the question "does my recorded history actually reproduce my stored schema" is one you want answered BEFORE deciding to squash, reset or import, not as the reason a push you already meant to make was rejected.
Import (docs/decisions/project-import.md) is what forced it: only a history that provably reproduces its schema may be re-signed under a new scope, because after the re-signing nobody can tell the difference.
func (*VerifyHistoryCmd) Run ¶
func (c *VerifyHistoryCmd) Run() error
Source Files