Describe a Database

Describe is the main way to understand what is happening to a database right now and whether you need to take any action.

Which fields to look at first

state

The main lifecycle field: creating, booting, ready, stopped, deleting, error.

status

A compatibility alias for older clients and scripts.

size

The public size label visible to the user.

current_scale and target_scale

Show whether the writer is running. In the managed contract, this is essentially a binary 0/1 status.

current_profile

The profile on which the active writer is actually running.

target_profile

The profile the platform is trying to reach during the current autoscale handoff.

candidate_profile

The profile of the prepared candidate generation.

scale_state

The current stage of the autoscaler state machine. If it differs from STEADY, a handoff, cooldown, or failure is in progress.

freeze_new_checkouts

Shows whether Gateway has frozen new checkouts before cutover.

candidate_worker_id and candidate_writer_term

Useful for diagnosing the new writer generation during a transition.

scale_failure_reason

If the autoscale handoff failed, this field provides the best short diagnosis.

worker_id

Useful for diagnostics when the database is active. It should not be used as business logic.

active_connections

Helps you understand whether the database is being used right now.

last_used_at

Useful for analyzing idle behavior and general activity.

How to interpret the result

• state=ready and scale_state=STEADY — normal steady-state operation.
• state=stopped — the database is not lost; the writer is simply off right now.
• scale_state=PREPARING/FREEZING/DRAINING/... — a controlled handoff between writer generations is in progress.
• scale_state=FAILED — the transition failed and metrics/logs must be inspected.
• freeze_new_checkouts=true — not an outage, but a normal cutover phase.

Practical meaning

Describe is useful not only for API automation. It is also the fastest way for an operator or developer to understand what is actually happening to the resource:

• a normal cold start;
• an idle stop;
• a controlled autoscale handoff;
• or a real error.