Neo4j Connection Pooling: Tune Driver for Performance (2026)

Neo4j driver connection pooling isn’t just about opening and closing connections; it’s about managing a finite resource to ensure your application doesn’t choke when Neo4j gets busy.

Let’s see it in action. Imagine we have a simple Node.js application that needs to fetch a user’s friends.

const neo4j = require('neo4j-driver');

const driver = neo4j.driver('bolt://localhost:7687', neo4j.auth.basic('neo4j', 'password'));

async function getFriends(userId) {
  const session = driver.session();
  try {
    const result = await session.run(
      'MATCH (u:User {id: $userId})-[:FRIENDS_WITH]->(friend:User) RETURN friend.name AS friendName',
      { userId }
    );
    return result.records.map(record => record.get('friendName'));
  } finally {
    session.close();
  }
}

// Simulate many concurrent requests
for (let i = 0; i < 100; i++) {
  getFriends(i % 10).then(friends => {
    console.log(`User ${i % 10} has friends:`, friends);
  });
}

In this snippet, neo4j.driver() creates a driver instance. This driver is the gateway to your Neo4j database and is responsible for managing the connection pool. When driver.session() is called, it either retrieves an existing idle connection from the pool or, if none are available and the pool hasn’t reached its maximum size, it establishes a new one. The session.close() call returns the connection to the pool, making it available for reuse.

The core problem connection pooling solves is preventing the overhead of establishing a new TCP connection and performing the Bolt handshake for every single database operation. For an application with frequent, short-lived database interactions, this overhead can become a significant performance bottleneck. A well-tuned connection pool keeps a set of ready-to-go connections, allowing your application to execute queries much faster by eliminating this setup time.

Internally, the Neo4j driver maintains a pool of connections. When you request a session, it checks if there’s an available connection in the pool. If yes, it hands it over. If not, and the pool isn’t full, it creates a new one. When a session is closed, the connection is returned to the pool. This is managed by configuration options passed during driver instantiation.

The most critical levers you have to tune this pool are:

• maxConnectionLifetime: This sets the maximum amount of time a connection can exist before it’s closed and replaced. It’s a good way to ensure connections don’t become stale due to long-running transactions or network issues. A common value might be 30 * 60 * 1000 (30 minutes) in milliseconds.
• maxTxRetryTime: While not strictly a connection pool setting, this impacts how long the driver will retry a transaction if the underlying connection is lost. A value like 5000 (5 seconds) means the driver will keep trying for 5 seconds before giving up, leveraging existing connections if possible.
• connectionAcquisitionTimeout: This is the maximum time the driver will wait for a connection to become available from the pool. If the pool is exhausted and the timeout is reached, an error is thrown. Setting this to 20000 (20 seconds) ensures your application doesn’t hang indefinitely if the database is overloaded.
• maxOpenSessions: This is a soft limit on the number of sessions that can be open concurrently. The driver will not create more sessions than this limit. A value of 50 can be a good starting point for many applications.
• connectionTimeout: The timeout for establishing a new connection to the database. A value of 15000 (15 seconds) is typical.

Here’s how you’d configure some of these options:

const driver = neo4j.driver('bolt://localhost:7687', neo4j.auth.basic('neo4j', 'password'), {
  maxConnectionLifetime: 60 * 60 * 1000, // 1 hour
  connectionAcquisitionTimeout: 30000,   // 30 seconds
  maxTxRetryTime: 10000                // 10 seconds
});

One common misconception is that simply increasing maxOpenSessions will solve all performance issues. However, if your Neo4j instance cannot handle the concurrent load generated by that many sessions, you’ll just end up with a slow Neo4j database and potentially more connection acquisition timeouts. The pool size needs to be balanced with your Neo4j server’s capacity and your application’s actual concurrency needs.

The next thing you’ll likely run into is understanding how to monitor the health and utilization of this connection pool.