Errors and events

Every error SQLStreams returns with a SQL code is a *sqlstreams.DiagnosticError, and every coded log line is emitted from a *sqlstreams.DiagnosticEvent. Both are declared once as package variables, sqlstreams.ErrStreamNotFound, sqlstreams.EventLeaseReclaimed, and a raise attaches values to a copy. Branch with errors.Is against the variable, never on message text.

_, err := orders.Register(ctx, nil)
if errors.Is(err, sqlstreams.ErrStreamNameTaken) {
	// another stream already holds the name
}

Verbs

On a DiagnosticError:

accessor	returns	notes
GetCode()	string	the SQL code, the link to its page
Recovery()	DiagnosticRecovery	RecoveryTransient when an unchanged retry can succeed, else RecoveryPermanent
Problem(), Fix()	string	the declared problem and fix; the fix carries {attribute} placeholders that Error() fills from the attached values
Queries()	[]DiagnosticQuery	the diagnose queries, detached copies
With(pairs...), Wrap(cause)	*DiagnosticError	a copy with values or a cause attached; the shared declaration never changes
Error(), Unwrap(), Is(target)	the standard error surface	Is matches any copy of the same declaration
LogValue()	slog.Value	the parts as fields; pass the error itself as the error attribute, never .Error() first

On a DiagnosticEvent: GetCode(), Message(), Queries(), Docs().

Owner

Owner is the resource a worker row, an alert, or a lease belongs to. It exposes the ids, the name, and Kind(): OwnerSystem, OwnerStream, or OwnerConsumerGroup. A consumer-group owner carries system id 1, stream id 12, and group id 34 together, and Kind() says the group is the owning resource.

Gotchas

• With copies the error; arbitrary application values attached through it are not deep-copied.
• Recovery is read-only. A service can attach context to ErrStreamNotFound and still match it with errors.Is, and it cannot change the declaration’s retry classification.
• The SQL owner-column helpers are not on Owner; advanced datastore callers use pkg/datastore.NewOwnerColumns, outside the supported API.
• Every code has its thread on Troubleshooting, and sqlstreams explain SQL0005 prints the same page offline.