Articles

Neon Max Connections: Understand and Raise Limits (2026)

April 18, 2026 5 min read

Neon’s default max_connections limit is a surprisingly small number, and hitting it isn’t just an inconvenience; it’s a hard stop that can cascade into application instability.

Let’s see it in action. Imagine you’ve got a simple Python app using psycopg2 to connect to Neon. You spin up a few instances, maybe in parallel, and BAM:

import psycopg2
import os
import time

DB_HOST = os.environ.get("NEON_HOST")
DB_USER = os.environ.get("NEON_USER")
DB_PASSWORD = os.environ.get("NEON_PASSWORD")
DB_NAME = os.environ.get("NEON_DBNAME")

def create_connection():
    try:
        conn = psycopg2.connect(
            host=DB_HOST,
            user=DB_USER,
            password=DB_PASSWORD,
            dbname=DB_NAME
        )
        print("Connection successful!")
        return conn
    except psycopg2.OperationalError as e:
        print(f"Connection failed: {e}")
        return None

if __name__ == "__main__":
    connections = []
    for i in range(100): # Try to open 100 connections
        conn = create_connection()
        if conn:
            connections.append(conn)
            time.sleep(0.1) # Small delay to avoid overwhelming instantly
        else:
            print(f"Failed to create connection {i+1}")
            break
    print(f"Successfully created {len(connections)} connections.")
    # Keep connections open for a bit
    time.sleep(10)
    for conn in connections:
        conn.close()
    print("Connections closed.")

If you run this script without adjusting Neon’s limits, you’ll likely see output like:

Connection successful!
...
Connection successful!
Failed to create connection 70
Connection failed: connection to server at "ep-wild-thunder-123456.us-east-1.aws.neon.tech" (X.Y.Z.W), port 5432 failed: FATAL: sorry, too many clients already
Successfully created 69 connections.
Connections closed.

The FATAL: sorry, too many clients already is the tell-tale sign. Neon, by default, is configured to accept a limited number of concurrent connections per branch. This isn’t arbitrary; it’s a safeguard to prevent resource exhaustion on the shared infrastructure and to manage costs. For a free tier or a small project, this might be perfectly fine. But as your application scales, or if you have connection pooling misconfigurations, you’ll hit this wall.

The max_connections setting in PostgreSQL, and by extension Neon, dictates the maximum number of simultaneous client connections allowed to a database instance. When this limit is reached, any new connection attempts will be rejected with a too many clients error. This limit is crucial for maintaining database stability and preventing resource starvation, as each connection consumes memory and CPU.

Here’s how to diagnose and raise it:

  1. Check Current Limit:

    • Diagnosis: Connect to your Neon database using psql or any SQL client and run:
      SHOW max_connections;
    • Typical Default: You’ll likely see 70 or a similarly low number on free tier branches.

  2. Understand Connection Pooling:

    • Diagnosis: Review your application’s connection management. Are you using a connection pooler like PgBouncer, or is each application instance opening its own direct connection? Are you closing connections properly? A common mistake is to have many short-lived, unmanaged connections opened by application instances that don’t close them quickly enough, or to have a pooler configured too aggressively. Check your application logs for repeated connection attempts and failures.
    • Why it’s Important: Even if Neon’s max_connections is high, an inefficient pooling strategy can exhaust it. For instance, if your pool has a max_size of 100 but your application instances are also trying to open direct connections, you can easily exceed the database’s limit.

  3. Identify Your Neon Project and Branch:

    • Diagnosis: Go to your Neon dashboard. Find the specific project and the branch that is experiencing the connection limit. Note the Branch ID or name.
    • Why it’s Important: max_connections is a per-branch setting in Neon. You need to know which branch to modify.

  4. Increase max_connections in Neon:

    • Diagnosis: In the Neon console, navigate to the Branch you identified. Click on the Settings tab for that branch. You’ll find a section for Database Size or Connection Limits.
    • Fix: Under the max_connections parameter, you can adjust the slider or input a new value. For a typical application with a moderately sized connection pool, values like 200, 500, or even 1000 are common. For example, to set it to 500:
      • In the Neon UI, find the max_connections setting for your branch.
      • Change the value to 500.
      • Click "Save".
    • Why it Works: This directly tells Neon’s underlying PostgreSQL configuration to allow more concurrent client connections to this specific branch. Neon handles the infrastructure adjustments required to support this higher limit.

  5. Configure Your Application’s Connection Pool:

    • Diagnosis: If you’re using a connection pooler (like PgBouncer, HikariCP for Java, or psycopg2’s built-in pooling), review its configuration.
    • Fix:
      • PgBouncer: In pgbouncer.ini, adjust max_client_conn and default_pool_size. For example, if you want to support 500 connections from your application and your pooler is configured for session pooling, you might set max_client_conn = 500 and default_pool_size = 500.
      • HikariCP (Java): In your application.properties or YAML, set spring.datasource.hikari.maximum-pool-size=500.
      • psycopg2 (Python): If using psycopg2.pool.ThreadedConnectionPool, set maxConnections to your desired value, e.g., pool = ThreadedConnectionPool(minconn=1, maxConnections=500, ...).
    • Why it Works: This ensures your application requests connections from the pool up to the new limit you’ve set in Neon, and that the pool itself is sized appropriately to handle the expected load without creating more connections than the database can sustain.

  6. Consider Neon’s Compute Size:

    • Diagnosis: If you’re consistently hitting connection limits even after increasing max_connections and optimizing pooling, and your application is performing slowly overall, your compute might be the bottleneck.
    • Fix: In the Neon console, under your project’s Settings, you can scale up the Compute size (e.g., from small to medium or large). This provides more CPU and memory resources, which can indirectly help manage a higher number of connections more efficiently.
    • Why it Works: A higher compute size allows the PostgreSQL server process on Neon to handle the overhead of managing more connections, executing queries for them, and managing their states without becoming a performance bottleneck itself.

After increasing max_connections and ensuring your application’s connection management is sound, new connection attempts should succeed. If you encounter issues with query performance or latency, the next bottleneck you’ll likely face is related to the compute resources available to your Neon branch.

Want structured learning?

Take the full Neon course →