Operator Commands

Commands for running a cluster live under bzrk admin. Changing anything with them takes an admin or a maintainer. Install the CLI and sign in first: Berserk CLI.

bzrk admin vidx status: vector-index format levelsCopy Anchor Link

Every replica that opens segments reports its vector-index format level to meta: 0 predates release 1, 1 reads and drops the new format, 2 writes it. bzrk admin vidx status lists each live replica with its pod (when it registered one), its level and when it last reported, then how many replicas of each kind meta can see and how many of those are at level 0:

• nursery — from its poll of meta, or from its registration heartbeat while it is not polling
• janitor — from its registration heartbeat, which keeps running through a long merge
• qws-cloud, qws-nursery — query workers, from their registration
• query — the query service itself, which reads segments when it runs its workers in process

bzrk admin vidx status
bzrk admin vidx status --json

The last line is the verdict:

• level-0 replicas are live — at least one replica below release 1 is running.
• No level-0 replica is live — every replica meta can see is at level 1 or above.
• Unknown — meta restarted too recently to have heard from every live replica (its list is complete after the longest liveness window it uses, which the output names). Run it again once that has passed.

The verdict covers only replicas meta can see. One that cannot register at all, say a pod with no address meta can record, is missing from the list without making the verdict unknown. Before relying on "no level-0 replica", check the per-kind counts against the replica counts of the deployment. A meta older than this command answers with an error that says so.

The floor: line is the environment's vector-index floor (vidxFloor), which meta enforces: a nursery below it holds no lease, a janitor below it is given no merge task, and a query worker below it stays registered but is left out of the pool coordinators draw from. Replicas below the floor are still listed, marked below floor, and a closing line counts them. --json carries the same as vidx_floor, below_floor and a below_floor flag per replica.

After the verdict come the write gate, as bzrk admin vidx writes status prints it, and every table's live segments, named database.table, by vector-index format: unknown (published before meta recorded formats), none, legacy (the VCEN/VTPH/VTPC artifacts) and v1, with how many v1 segments left a field unindexed for a transient reason. A closing line counts the segments the rewrite has yet to reach: anything but v1 on a table with vector fields, and anything unknown or legacy elsewhere. --json carries them as writes and inventory; both are null from a meta that predates them.

bzrk admin vidx writes: whether writers may write the new formatCopy Anchor Link

bzrk admin vidx writes status
bzrk admin vidx writes open
bzrk admin vidx writes close

Writes of the new format are closed until they are opened, and who opens them is the environment's vidxWrites (BZRK_VIDX_WRITES on meta). In auto, the default, the gate authority opens writes itself the first time open would succeed, and logs it with vidx.reason=auto_opened. In manual, only open opens them. close holds writes closed in either mode: meta in auto does not reopen them, across restarts and changes of authority, until an operator runs open, which releases the hold even when it is refused. close on writes that never opened holds them too, which keeps auto from opening them in the first place. status prints the mode on its mode: line, says when an operator's close holds writes, and lists what keeps them from opening; --json carries writes_mode and closed_by_operator_at_nanos.

open succeeds only when the floor is at least 1, one grant period has passed since the last close, and a window has held on meta: every nursery holding a lease reports level 2, every query worker level 1 or more, and a level-2 janitor has polled for a merge task within every grant period. Any lapse starts the window again, and so does a meta restart. Otherwise meta refuses and names every unmet condition; status lists the same conditions without trying.

Meta hands each level-2 nursery and janitor a grant with every poll while writes are open. A writer starts a new-format build only under an unexpired grant, timed from when it sent its poll, so close stops new builds within one grant period; builds already started finish. A restarted meta grants nothing until its window has held again, and meta stops granting while any nursery holding a lease is below level 2 or any query worker below level 1. While writes are open, meta refuses a lease to a nursery below level 2. Open only after a deploy in which every meta pod runs this release has settled: meta checks the gate protocol of every meta that registers one, but cannot see a meta that predates it. open prints this reminder. One meta at a time is the gate authority, the holder of a Postgres advisory lock; only it opens writes and grants, and status says when the meta you reached is not it. Any meta closes writes. Meta gives merge tasks with a v1 input only to level-2 janitors, and while writes are open, tasks for tables with vector fields too. The window (vidx_window_secs, 300 by default) and the grant period (vidx_grant_period_secs, 30 by default) are meta configuration.