TechPrufer
Get started
PlanetScale
PlanetScale logoPlanetScale · Feature trail

Database Connection Management

13 posts · Aug 2021 – Aug 2026

What this trail covers

PlanetScale offers enhanced database connection management tools for Postgres and MySQL, including dashboard and CLI commands to inspect and terminate connections. This feature aims to prevent and resolve database downtime caused by unhandled exceptions, open transactions, and schema change locks. The post details how connection poolers like PgBouncer can lead to 'poisoned' pools due to stale session states, causing write errors. It introduces `DISCARD ALL` as a quick fix and recommends using `i` PgBouncer for all application traffic, with options for local, dedicated primary, and dedicated replica PgBouncers. The post details configuration options like `max_client_conn`, `default_pool_size`, `max_db_connections`, and `max_user_connections`, and provides tuning examples for small and large servers, as well as single-tenant configurations, to optimize connection pooling and prevent exceeding PostgreSQL's `max_connections`.

All PlanetScale trails
  1. How one connection kills a databaseThis post introduces the ability to view and kill connections in Postgres and MySQL databases on PlanetScale. It details how unhandled exceptions can lead to stuck transactions and blocked queries, causing downtime. The PlanetScale dashboard now provides a live list of connections with columns for Process ID, State, Duration, and Blocked Queries. Users can click into a connection to see more details and choose to Cancel query, Terminate transaction, or Terminate connection. For Vitess, options include canceling the query or terminating the connection, with visibility per keyspace and shard. The CLI offers `pscale branch connections top` for a live, interactive view and `pscale branch connections show --format json` for JSON output, with commands to cancel queries or terminate connections.
  2. Poisoned Postgres connection poolsThis post introduces the concept of 'poisoned' connection pools in Postgres, where stale session states from previous client connections can cause subsequent queries to fail. It details how PgBouncer in transaction mode can lead to this issue, specifically when session characteristics like `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY` are left active. The post explains the error code `25006` and differentiates it from cluster-level read-only errors. It offers `DISCARD ALL` as a quick fix and suggests using `pscale branch connections top` to identify and kill problematic sessions. Furthermore, it introduces PlanetScale's MCP server as a tool to help agents find and fix the root cause of these leaks in application code, and recommends sending read traffic to replicas or ensuring strict timeouts and avoiding session variable modifications on primary transactions to prevent future occurrences.
  3. When the Postgres query planner goes rogueThis post details an incident where the PostgreSQL query planner caused a sudden and severe CPU spike, leading to query failures. It explains how the planner's cost estimation can go awry, causing queries to abandon index usage and resort to full table scans. The post demonstrates how PlanetScale's Database Traffic Control feature was used to immediately block the problematic query pattern, restoring database health and providing a window to investigate and fix the underlying issue.
  4. Deadlocks and downtimeThis post details how deadlocks occur in Postgres, the damage they cause (backed-up transactions and retry storms), strategies to reduce their likelihood in queries (consistent lock ordering, shorter transactions, reducing latency via indexing), application-level retry logic with backoff and jitter, observing deadlock errors in the PlanetScale dashboard, and using Traffic Control with Resource Budgets to mitigate deadlocks at the database level by limiting concurrent query execution.
  5. One Postgres cluster, many appsThis post details how to manage multiple applications within a single PlanetScale Postgres database cluster by creating and isolating logical databases and roles. It explains the concepts of database clusters, branches, logical databases, and roles, and provides manual steps for creating logical databases, revoking public connect permissions, creating application-specific roles, and granting granular permissions. It then introduces Infrastructure as Code (IaC) tools like Terraform, Pulumi, and SST as more robust methods for automating this process, focusing on a Pulumi example to manage roles via the PlanetScale API and logical databases/grants within Postgres.
  7. See what your database is doing right now with ConnectionsIntroduces the 'Connections' CLI feature for real-time inspection and management of database connections in PlanetScale Postgres and Vitess. This feature provides a live, interactive view of sessions, including PIDs, status, wait events, and blocking relationships, with keyboard shortcuts for navigation and inspection. It offers history buffering, pausing, stepping, and session capture capabilities. A reserved administrative connection ensures the tool remains available even when application connections are exhausted. For Vitess, it supports keyspace and shard-specific monitoring.
  8. Scaling Postgres connections with PgBouncerThis post details how to tune PgBouncer for optimal connection pooling with PostgreSQL. It explains the benefits of PgBouncer over direct connections, introduces PlanetScale's three PgBouncer deployment options (local, dedicated primary, dedicated replica), and elaborates on the three pooling modes (session, statement, transaction), recommending transaction pooling. The core contribution is a deep dive into PgBouncer's configuration parameters (`max_client_conn`, `default_pool_size`, `max_db_connections`, `max_user_connections`) and their interaction with PostgreSQL's `max_connections`, providing concrete tuning examples for different server sizes and tenancy models.
  9. Faster PlanetScale Postgres connections with Cloudflare HyperdriveThis post details the integration of Cloudflare Hyperdrive with PlanetScale Postgres Metal to optimize database connections and enable real-time applications. It explains how Hyperdrive automates connection pooling and caching, reducing latency. The post also outlines the architecture for a real-time application using Cloudflare Workers, Durable Objects, and WebSockets, emphasizing the separation of concerns between the authoritative database and the low-latency notification layer. It discusses performance considerations like 'smart placement' and the trade-offs in real-time update reliability.
  10. Serverless Laravel applications with AWS Lambda and PlanetScaleThis post details the integration of PlanetScale with serverless Laravel applications running on AWS Lambda using Bref. It covers setting up the Laravel application, deploying it to Lambda, configuring the PlanetScale database connection (including SSL certificate handling), and running database migrations within Lambda. The post also demonstrates a load test to showcase Lambda's autoscaling capabilities and PlanetScale's performance under load. A key contribution is the optimization section, which introduces Laravel Octane and session persistence to significantly reduce latency by keeping the application in memory and reusing database connections across requests.
  11. Connection pooling in VitessThis post details the evolution of Vitess's connection pooling. It explains the benefits of application-level connection pooling (performance, scalability, traffic shaping) and its limitations. It then describes how Vitess, through Vttablet, addressed these limitations by centralizing connection management. The post further elaborates on the challenges introduced by ORMs requiring `SET` statements, leading to 'reserved connections' that bypass pooling. It outlines two techniques to mitigate the impact of reserved connections and introduces the 'settings pool' in Vitess 15 as a solution to handle modified connections without compromising pooling benefits.
  12. Common MySQL errors and how to fix themThis post details common MySQL error codes and non-coded errors, providing explanations and solutions. It specifically addresses 'Too many connections' (Error 1040) by explaining the `max_connections` variable and mentioning PlanetScale's support for unlimited connections. Other covered errors include 'Access denied' (1045), 'Syntax error' (1064), 'Table is full' (1114), connection timeouts (2006, 2013), client memory issues (2008), 'Packet too large', 'Can't create/write file', 'Commands out of sync', 'Hostname is blocked', and 'Aborted connections'.
  13. One million connectionsThis post details a test where PlanetScale successfully maintained one million active MySQL connections by combining Vitess connection pooling at the VTTablet level with PlanetScale's Global Routing Infrastructure. It explains the challenges of database connection limits in serverless architectures, the role of `max_connections` in MySQL, and the limitations of application-side connection pools. The test involved using AWS Lambda with a fan-out pattern, where 1000 worker functions each established 1000 connections, demonstrating the scalability of the architecture to handle massive connection concurrency.
  14. Connect any MySQL client to PlanetScale using Connection StringsIntroduces connection strings for all PlanetScale users, allowing connection to databases with popular MySQL clients and serverless platforms. Highlights security features like branch-specific passwords and GitHub Secret Scanning integration. Mentions support for native MySQL authentication and Caching SHA-2 authentication.