Database connection and performance problems

Resolve database connection errors, too-many-connections, slow queries, a database that won't start, and buffer-pool sizing on TurboStack - for MySQL/MariaDB and PostgreSQL.

Database trouble shows up in two main ways: the application cannot connect, or queries are slow. This page covers both, plus a database service that fails to start, and how to size database memory safely. It applies to both MySQL/MariaDB (Percona Server) and PostgreSQL on TurboStack.

Symptoms

The app shows "connection refused", "too many connections", or authentication errors.
Pages that read or write the database are slow while the rest of the site is fine.
The database service is down and the host's Health check for it is Critical.
The database fails to start after a deploy, a version change, or a full disk.

Diagnose it on TurboStack

Open the host's Health tab. Check the Services list for the database check (status and latest output) and the Host Monitoring cards for RAM, Memory swap, and Disk - a full disk or memory pressure is a common root cause of database failures.
Review Top Issues for any ranked database problem and its recommended fix.
For query-level insight, enable Advanced Database Monitoring and review its query-performance dashboards - see Monitoring (concepts).
Check History (Revisions / Deploys) - a recent publish that changed the database version, sizing, or bind address is a likely trigger, and you can roll it back.
For anything deeper, connect over SSH to read logs and run client commands (below).

Connection refused or "too many connections"

These are connection-layer problems, not query problems.

Connection refused / cannot reach the database

The service is down. Check the database service on the Health tab. If it is not running, see Database service won't start below.
You are connecting from off-host. TurboStack does not expose a public database port. To reach the database from your machine, use an SSH tunnel - see Connect to MySQL remotely and Connect to PostgreSQL remotely.
Bind address / listen address. If the app is on another host, the database must listen on the right interface. These keys are security-sensitive - keep them as tight as possible. See mysql_bindaddress in Configure MySQL and postgresql_listen_addresses / postgresql_extra_access in Configure PostgreSQL.
Credentials. A wrong user, password, or database name returns an authentication error rather than "refused". Confirm the app's configured credentials.

Too many connections

The database has a maximum number of simultaneous connections; once it is reached, new connections are rejected. This is almost always caused by the application opening more connections than it closes - for example too many PHP-FPM workers, a connection leak, or a missing connection pool - rather than the limit being too low.

Check how many PHP-FPM workers can run; each busy worker can hold a database connection. See Performance tuning for PHP-FPM worker sizing.
Look for long-running or stuck queries holding connections open (see below) and for code paths that open connections without closing them.
Raising the connection limit only masks a leak and costs memory. Fix the cause first; if you have evidence the limit is genuinely too low for legitimate concurrency, contact Support.

Slow queries and how to spot them

When database-backed pages are slow but the server has CPU and RAM headroom, the cause is usually a specific query - often unindexed, or scanning far more rows than it returns.

Advanced Database Monitoring gives you a query analytics view that ranks the slowest and most frequent queries; this is the easiest starting point. See Monitoring (concepts).
MySQL/MariaDB: inspect live activity with SHOW FULL PROCESSLIST; to catch queries that are running long right now. The slow query log records queries that exceed a time threshold.
PostgreSQL: inspect live activity with SELECT * FROM pg_stat_activity;. The pg_stat_statements extension aggregates query timings, and slow statements can be logged.
Once you have identified a slow query, examine its plan (EXPLAIN / EXPLAIN ANALYZE) and add or fix indexes in the application's schema/migrations.

A slow query in the admin or at checkout often points to a single missing index - fix that before considering more memory or a bigger server.

Database service won't start

If the database does not come up, work through the most common causes in order:

Out of disk. A database cannot start (or stay up) when the volume holding its data or logs is full. Check the Disk card on the Health tab and free space - see Disk space.
Out of memory. If the host is under memory pressure or the kernel OOM-killer stopped the process, the service can fail to start or get killed shortly after. See Out of memory. An InnoDB buffer pool or shared_buffers set too large for the host is a frequent cause of startup OOM (see sizing below).
A recent version change. A major-version change is a migration, not an in-place switch, and an incomplete or untested one can leave the service unable to start. Check History and the configure pages: Configure MySQL, Configure PostgreSQL. Downgrades are not supported.
Corruption. After a crash or a full disk, data files can be inconsistent and the service refuses to start cleanly. Recovery is risky to attempt blind - capture the startup error from the logs and contact Support; you may need to restore from the host Backups tab.

The exact reason is almost always in the database error log (below) - read it before taking action.

Buffer pool and memory sizing

The single most important database performance setting is how much memory it uses to cache data and indexes. When this is too small, the database constantly reads from disk; when it is too large for the host, the database (or another service) is starved and may be OOM-killed.

Engine	Sizing key	What it controls
MySQL/MariaDB	`mysql_innodb_size`	InnoDB buffer pool - cached table and index data
PostgreSQL	`postgresql_shared_buffers`	Shared memory used for caching data

TurboStack auto-tunes both keys to the size of the server. Override them only with measured evidence - for example Advanced Database Monitoring showing a low buffer-pool / cache hit ratio together with spare RAM on the Health tab. Guessing larger values commonly causes memory pressure and swapping, which makes the whole host slower. See Performance tuning, then set the override on the Configure MySQL or Configure PostgreSQL page and publish.

Where to find the database logs

The database error log is where startup failures, crashes, and corruption messages appear. The quickest way to read it is the TurboStack CLI over SSH, which finds the right log for you:

tscli logs mysql error                          # recent MySQL/MariaDB error log
tscli logs mysql find error from 2 hours ago    # scope the search by time

Use the matching service name for your database. The latest check output on the Health Services entry also points you at the current problem, and Advanced Database Monitoring dashboards complement the logs with query-level history.

Prevent it

Leave memory sizing auto-tuned unless Advanced Database Monitoring and the Health graphs give you a clear reason to change it; change one thing at a time and re-measure.
Index the queries your application runs most; review Advanced Database Monitoring regularly.
Keep the database bind/listen address restricted and connect remotely over an SSH tunnel.
Keep disk headroom so logs and data files never fill the volume (see Disk space).
Back up before any major version change, and make permanent changes in the TurboStack Platform and a publish.

When to contact support

If the database will not start, you suspect corruption, or you need to restore from a backup, open a ticket at Support. Include the host and database engine/version, what changed (and when), the Health status, and the exact error from the database log.