Help
Slow queries, high CPU, memory and full disks
Tested with:Databasezy API v1 · zb CLI 0.1
When queries get slow, first find out what the instance is short of: CPU, memory or disk. The Metrics tab shows all three against your size’s limits. A query problem (a missing index, a huge scan) needs a query fix. A capacity problem needs a larger size or more storage. A full disk needs action straight away, because writes fail until there is room.
Read the Metrics tab
Section titled “Read the Metrics tab”Open the instance and go to Metrics. The cell samples every 5 minutes. You get:
- CPU, against the vCPU limit of your size.
- Memory, the highest working set, against your size’s memory.
- Storage used, against the provisioned storage.
- Egress and New connections.
Concurrent connections, queries per second and replication lag are not collected yet. For alerts, scrape the organization’s Prometheus endpoint; see Observability exports.
CPU is at the limit
Section titled “CPU is at the limit”Sustained CPU at the limit means queries are queuing for CPU. Look for the heaviest queries first: on PostgreSQL,
pg_stat_statements (if it is enabled on your instance, see Extensions) or EXPLAIN ANALYZE
on the slow query. Missing indexes and full table scans are the usual causes. If the workload is simply bigger than
the size, resize.
Free-plan f0 instances reserve only a small CPU share and burst up to one core when the cell has spare capacity, so
their speed varies under sustained load.
Memory is at the limit
Section titled “Memory is at the limit”Memory close to the size’s limit, with slow queries or restarts, means the working set does not fit. Large sorts, many connections each using memory, and big result sets add up. Reduce connections with a pool (see Too many connections), or move to a size with more memory.
The disk is full
Section titled “The disk is full”Writes fail with engine errors such as PostgreSQL’s could not extend file ... No space left on device or MySQL’s
The table is full. Storage does not grow automatically yet, so grow it yourself:
-
In the portal: Instance → Settings → Size and storage.
-
With the API:
shell zb api GET /v1/orgs/{org}/instances/<instance_id>/options # what you can change to, and why notzb api PATCH /v1/orgs/{org}/instances/<instance_id> -d '{"storage_gb": 60}'
Storage grows without a restart, in whole GB, up to your size’s ceiling, your plan’s per-instance limit and your
storage quota. It never shrinks; to shrink, restore into a smaller instance. Deleting data helps only after the
engine frees the space (for example PostgreSQL VACUUM FULL on the affected table, which locks it). On the Free plan
the volume is 1 GB and cannot grow; upgrade the plan for more. See Resize.
canceling statement due to statement timeout on the Free plan
Section titled “canceling statement due to statement timeout on the Free plan”Free-plan PostgreSQL and TimescaleDB instances stop any single statement after 60 seconds. Make the query faster (an index, a smaller batch) or move to a paid plan, which has no default statement timeout.
Cancelling a query from the client does not work
Section titled “Cancelling a query from the client does not work”PostgreSQL cancel requests (Ctrl+C in psql, a driver’s cancel call) cannot pass through the gateway. To stop a
running query, open a second connection and run SELECT pg_cancel_backend(<pid>);, using the pid from
pg_stat_activity. Use pg_terminate_backend(<pid>) to end the whole session.
Connections closed after 5 minutes idle in a transaction
Section titled “Connections closed after 5 minutes idle in a transaction”PostgreSQL closes sessions that stay idle inside an open transaction for 5 minutes, with terminating connection due to idle-in-transaction timeout. Commit or roll back promptly; long open transactions also block cleanup and make
other queries slower.
Resize to a larger size
Section titled “Resize to a larger size”zb instances resize <instance_id> --size m4A resize takes a backup first, then restarts the database. PostgreSQL and MySQL with high availability fail over in a
few seconds; single-node instances are unavailable for about 20 to 60 seconds. The status is modifying until it is
ready again. Only one resize runs at a time; a second request is refused with 409. Billing switches to the new
size when the change completes. The sizes and their limits are in the size catalogue; details
are on Resize.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket). Include the instance id, the region, its size, what is slow (a query plan helps, with data values removed), the exact error text, and the time it happened in UTC. Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.