How to Configure Connection Pool Size and Timeout Settings in neomodel

Configure connection pool size and timeout settings in neomodel by setting environment variables like NEOMODEL_MAX_CONNECTION_POOL_SIZE or by modifying the NeomodelConfig dataclass programmatically before initializing the database connection.

The neo4j-contrib/neomodel library centralizes all driver-related configuration in a dedicated configuration system. Understanding how to configure connection pool size and timeout settings ensures your Neo4j applications can handle high concurrency and network latency appropriately.

Understanding neomodel's Configuration Architecture

The NeomodelConfig Dataclass

All connection settings are defined in the NeomodelConfig dataclass located in neomodel/config.py. This configuration object validates settings on instantiation and provides a centralized source of truth for the Neo4j driver options.

The relevant fields for pool and timeout management include:

Setting	Type	Default	Environment Variable
max_connection_pool_size	int	100	NEOMODEL_MAX_CONNECTION_POOL_SIZE
connection_acquisition_timeout	float	60.0 (seconds)	NEOMODEL_CONNECTION_ACQUISITION_TIMEOUT
connection_timeout	float	30.0 (seconds)	NEOMODEL_CONNECTION_TIMEOUT
max_connection_lifetime	int	3600 (seconds)	NEOMODEL_MAX_CONNECTION_LIFETIME

Where Configuration Meets the Driver

When neomodel establishes a connection, the Database class in neomodel/sync_/database.py constructs the driver options dictionary using the current global configuration. Around lines 340-345, the code maps these configuration values directly to the official Neo4j Python driver parameters:

options = {
    "auth": basic_auth(username, password),
    "connection_acquisition_timeout": config.connection_acquisition_timeout,
    "connection_timeout": config.connection_timeout,
    "keep_alive": config.keep_alive,
    "max_connection_lifetime": config.max_connection_lifetime,
    "max_connection_pool_size": config.max_connection_pool_size,
    "max_transaction_retry_time": config.max_transaction_retry_time,
    "resolver": config.resolver,
    "user_agent": config.user_agent,
}
self.driver = GraphDatabase.driver(parsed_url.scheme + "://" + hostname, **options)

The NeomodelConfig._validate_config method enforces constraints such as requiring max_connection_pool_size to be greater than 0, raising ValueError for invalid inputs.

Methods to Configure Pool Size and Timeouts

Environment Variable Configuration

The most common approach for production deployments uses environment variables. neomodel reads these automatically when the configuration is first accessed:

export NEOMODEL_MAX_CONNECTION_POOL_SIZE=200
export NEOMODEL_CONNECTION_TIMEOUT=45
export NEOMODEL_CONNECTION_ACQUISITION_TIMEOUT=120
export NEOMODEL_MAX_CONNECTION_LIFETIME=7200

When your application imports neomodel and initializes the database connection, these values override the defaults.

Runtime Programmatic Configuration

For dynamic configuration or testing scenarios, modify the global configuration object before establishing the database connection:

from neomodel import get_config, set_config

# Retrieve the current configuration

cfg = get_config()

# Update connection pool and timeout settings

cfg.max_connection_pool_size = 150
cfg.connection_timeout = 40.0
cfg.connection_acquisition_timeout = 80.0
cfg.max_connection_lifetime = 3600

# Apply the configuration globally

set_config(cfg)

Any Database instances created after this modification will use the updated parameters.

Legacy Configuration API

Previous versions of neomodel exposed module-level attributes directly. This approach still functions through the _ConfigModule proxy but emits deprecation warnings:

import neomodel as nm

# Legacy approach - still works but not recommended

nm.MAX_CONNECTION_POOL_SIZE = 250
nm.CONNECTION_TIMEOUT = 50.0

The proxy forwards these assignments to the underlying NeomodelConfig singleton and validates the values, but you should migrate to the modern get_config()/set_config() API for future compatibility.

Validating Your Configuration

After setting your desired pool size and timeouts, verify the active configuration to ensure the values were applied correctly:

from neomodel import get_config

cfg = get_config()
print(f"Pool size: {cfg.max_connection_pool_size}")
print(f"Connection timeout: {cfg.connection_timeout}")
print(f"Acquisition timeout: {cfg.connection_acquisition_timeout}")
print(f"Max connection lifetime: {cfg.max_connection_lifetime}")

This verification step is particularly important when using environment variables, as it confirms that neomodel successfully parsed the values before the driver initializes.

Summary

• Configuration location: All pool and timeout settings reside in the NeomodelConfig dataclass in neomodel/config.py.
• Environment variables: Use NEOMODEL_MAX_CONNECTION_POOL_SIZE, NEOMODEL_CONNECTION_TIMEOUT, NEOMODEL_CONNECTION_ACQUISITION_TIMEOUT, and NEOMODEL_MAX_CONNECTION_LIFETIME for deployment-time configuration.
• Programmatic control: Use get_config() and set_config() to modify settings at runtime before database initialization.
• Driver integration: Settings are passed to the official Neo4j Python driver in neomodel/sync_/database.py around lines 340-345.
• Validation: The configuration system validates inputs (e.g., pool size must be positive) and raises ValueError for invalid values.

Frequently Asked Questions

What is the default connection pool size in neomodel?

The default max_connection_pool_size is 100 connections. This value is defined in the NeomodelConfig dataclass in neomodel/config.py and is passed directly to the Neo4j driver when establishing the database connection.

How do I increase the connection timeout for slow networks?

Set the NEOMODEL_CONNECTION_TIMEOUT environment variable to a higher value (in seconds), or programmatically modify config.connection_timeout using get_config() before initializing the database. For example, setting it to 60.0 or 90.0 seconds accommodates high-latency network conditions.

Can I configure neomodel without using environment variables?

Yes. Use the modern configuration API by importing get_config from neomodel, modifying the returned NeomodelConfig object attributes (such as max_connection_pool_size and connection_timeout), and applying it with set_config(). This approach works entirely within your Python code without requiring shell environment variables.

Where does neomodel validate configuration settings?

Validation occurs in the NeomodelConfig._validate_config method within neomodel/config.py. This method checks constraints such as ensuring max_connection_pool_size is greater than zero, raising ValueError with descriptive messages if validation fails. The validation runs both when creating a new configuration instance and when modifying values through the legacy attribute proxy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}