Control stream maintenance

Suspend(ctx context.Context) error
Unsuspend(ctx context.Context) error
Status(ctx context.Context) (*WorkerSnapshot, error)

Controls the worker selected by stream.Janitor() or stream.Vacuum(). Janitor performs retention cleanup. Vacuum maintains the stream’s idempotency-key table. Settings remain declared through StreamConfig.

Example

Inspect the janitor for the payments.requested stream using an initialized client.

payments := client.Stream[sqlstreams.RawPayload]("payments.requested")
status, err := payments.Janitor().Status(ctx)
if err != nil {
  return err
}
fmt.Println(status.Status, status.LiveInstances, status.Attempts)

Parameters

Parameter	Type	Required	Description
`ctx`	`context.Context`	Yes	Cancellation or its deadline interrupts the read or target update.

Operations

Operation	Effect
Suspend	Sets the instance target to zero. Prevents new claims and requests running work to stop at its next successful heartbeat. Returns without waiting for shutdown.
Unsuspend	Sets the instance target to one. A running manager can then claim the worker.
Status	Reads suspension, live claims, and recorded consecutive failures.

New streams start with an active janitor and suspended vacuum. Registering stream configuration again preserves those targets.

Returns

Operation and condition	Return value
Suspend or Unsuspend succeeds	`nil`.
Status succeeds	`(snapshot, nil)`.
Stream or worker is absent	The corresponding not-found error, with a `nil` snapshot for Status.
An operation fails	A non-`nil` error, with a `nil` snapshot for Status.

WorkerSnapshot

Field	Type	JSON name	Description
`Owner`	`*Owner`	`owner`	Resource owning the worker.
`Name`	`string`	`worker`	Worker kind.
`Status`	`WorkerStatus`	`status`	The state below. Suspension takes precedence over live claims or failures.
`TargetInstances`	`int`	`target_instances`	Allowed instances. Zero means suspended, -1 means unlimited.
`LiveInstances`	`int`	`live_instances`	Instance claims whose expiry is still in the future.
`Attempts`	`int`	`attempts`	Largest consecutive-failure count across live instances.
`UnclaimedFor`	`time.Duration`	`unclaimed_for`	Time since the newest expired claim while unclaimed. Zero when live or when expired claim rows have been removed.

WorkerStatus

Constant	Value	Meaning
`WorkerSuspended`	`"suspended"`	Target is zero.
`WorkerClaimed`	`"claimed"`	A live instance exists without a recorded failure streak.
`WorkerFailing`	`"failing"`	A live instance reports consecutive failures.
`WorkerUnclaimed`	`"unclaimed"`	No live instance exists and the worker is not suspended.

CLI

sqlstreams stream janitor status payments.requested
sqlstreams stream vacuum unsuspend payments.requested

Both janitor and vacuum support status, suspend, and unsuspend. All support --output json. Status formats UnclaimedFor as a duration string.

Errors

Error	When
Validation error	The stream name is empty.
`ErrStreamNotFound`	The stream is absent.
`ErrWorkerNotFound`	The selected maintenance worker has no declaration.
Database or context error	A read or update fails or is interrupted.

Register a stream — Janitor and vacuum configuration.
Run the system manager — Execute eligible maintenance workers.
Message retention — When the janitor may remove messages.
Worker is not running — Investigate suspended, unclaimed, or failing maintenance.