SWITCH COLD STORAGE ROLE

Moves the cold storage manager role between instances at runtime, and reports the role an instance currently holds. Exactly one instance in a cluster owns uploads, manifest writes, and remote garbage collection; these statements move that ownership without restarting either instance, which is how a manager is replaced during maintenance or after a failure.

note

Cold storage is available in QuestDB Enterprise only.

Syntax​

Switch role
SWITCH COLD STORAGE ROLE TO { MANAGER | REFRESHER }
    [FORCE]
    [TIMEOUT milliseconds];
Report role
SWITCH COLD STORAGE STATUS;

Description​

Both statements act on the instance that executes them, not on the cluster. Issue them against the specific node whose role you want to change or inspect.

ClauseEffect
TO MANAGERClaims the manager lock and opens manager work on this instance
TO REFRESHERFlushes pending manifest state, releases the lock, and drops to read-only mirroring
FORCEDeletes an existing foreign lock before claiming it
TIMEOUTBounds how long the calling session waits, in milliseconds

The role is independent of the replication primary and replica roles. Promoting a replica to primary does not move the manager role, and moving the manager role does not affect replication.

A role set this way does not survive a restart. Update cold.storage.role in server.conf after a durable handoff, otherwise the instance boots back into its configured role.

Status columns​

SWITCH COLD STORAGE STATUS returns a single row with two columns:

ColumnTypeDescription
stateSTRINGREFRESHER, PROMOTING, MANAGER, or DEMOTING
termLONGOwnership term, positive only while manager work is being accepted

PROMOTING and DEMOTING are transient. A stable role is REFRESHER or MANAGER; treat a MANAGER state with a non-positive term as not yet accepting work.

Timeout behaviour​

TIMEOUT bounds only the calling session. The transition itself continues to a stable state regardless, and a timeout never rolls it back. If a statement times out, poll SWITCH COLD STORAGE STATUS to see where the transition settled rather than reissuing the switch.

Permissions​

Both statements require database administrator (system admin) privileges, including with FORCE. They are not grantable through RBAC permissions.

Examples​

The supported handoff is two steps, on two different instances, in this order:

1. Demote the current manager
SWITCH COLD STORAGE ROLE TO REFRESHER;
2. Confirm it released the role
SWITCH COLD STORAGE STATUS;
stateterm
REFRESHER0
3. Promote the replacement
SWITCH COLD STORAGE ROLE TO MANAGER;
4. Confirm it is accepting work
SWITCH COLD STORAGE STATUS;
stateterm
MANAGER4

Bound the caller's wait to 30 seconds:

SWITCH COLD STORAGE ROLE TO REFRESHER TIMEOUT 30000;

Take over when the previous manager cannot demote itself:

SWITCH COLD STORAGE ROLE TO MANAGER FORCE;
danger

FORCE deletes the existing manager lock and claims ownership. It is a recovery path, not a fencing protocol: stop the previous manager, or prove it is dead, before issuing it. Two active managers write byte-divergent Parquet for the same partition and corrupt cold reads.

See also​