Skip to main content
Read-only mode preserves cluster functionality while preventing operations that could lead to instability, allowing you to remediate issues before they become critical. When read-only mode is enabled, attempts to write to the cluster will see the following error:
We will also pause all logical replication subscriptions writing data into the cluster. Once your cluster is out of read-only mode you can unpause the subscribers by running
on each subscription. There’s no way for a PlanetScale customer to enter or exit read-only mode, except by remediating the conditions that caused the cluster to enter that mode. Here are the reasons we’ll put the cluster into read-only mode:

​
Insufficient space

To protect your cluster from crashing, if a cluster has very little space left (typically 5% or less), we will automatically move it into read-only mode. The specific scenarios are: Once you have remediated the issue, your cluster will automatically exit read-only mode.
PlanetScale will send notifications via email and webhook (if enabled) when your storage exceeds 60, 75, 85, 90, and 95 percent, respectively. You can also track disk utilization via Metrics. Emails are sent to all Organization and Database administrators. It is critical that these email addresses are monitored regularly.
If the issue was temporary, say due to errant data being written by mistake, you could remove the data, perform a vacuum, and then reverse the remediation action. See Cluster storage configuration for more on reducing storage usage.

​
Single Node Archiver lag

Single node Postgres clusters offer decreased durability compared to HA offerings. In HA, we use Postgres synchronous replication to guarantee every committed transaction reaches the primary and at least one replica. As part of our usual (we do this on HA too) durability posture, we archive postgres Write-Ahead Logs (WAL) to durable object storage (S3, GCP Cloud Storage). For single-node, we will enter read-only mode if this archiving process falls too far behind writes on your cluster. If you see this happening frequently, we recommend sizing your cluster up, or moving to an HA cluster.

​
Read-only transactions vs cluster read-only mode

Cluster read-only mode and read-only transactions are different failure modes with different error messages. A transaction becomes read only through BEGIN READ ONLY, SET TRANSACTION READ ONLY, session characteristics, role defaults, default_transaction_read_only, and similar settings in application code, an ORM, or a database driver. If only some writes fail while others succeed on the same branch, the branch is likely not in read-only mode. PgBouncer runs in transaction pooling mode and reuses server connections across clients. When session parameters such as default_transaction_read_only are not tracked, read-only state from a prior client can persist on a server connection and affect the next client. A plain SET can leak across transactions (including BEGIN; SET ...; COMMIT); only SET LOCAL is limited to the current transaction. See limitations of transaction pooling and PgBouncer error messages for more on pooled connection behavior. To resolve read-only transaction errors:
  1. Search application code, ORM configuration, and driver options for read-only transaction modes, session characteristics, or replica routing that sets read-only sessions on a write connection.
  2. Remove the setting if writes should use the same connection, use SET LOCAL when a per-transaction setting is required, or route read-only traffic through a separate role and connection (for example, a replica PgBouncer) instead of toggling read-only on a shared pooled connection.