# How to Configure Connection Pool Size and Timeout Settings in neomodel

> Learn to configure neomodel connection pool size and timeout settings using environment variables or programmatically for optimal Neo4j performance. Optimize your database connections today.

- Repository: [Neo4j Contrib/neomodel](https://github.com/neo4j-contrib/neomodel)
- Tags: how-to-guide
- Published: 2026-03-08

---

**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`](https://github.com/neo4j-contrib/neomodel/blob/main/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`](https://github.com/neo4j-contrib/neomodel/blob/main/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:

```python
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:

```bash
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:

```python
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:

```python
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:

```python
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`](https://github.com/neo4j-contrib/neomodel/blob/main/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`](https://github.com/neo4j-contrib/neomodel/blob/main/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`](https://github.com/neo4j-contrib/neomodel/blob/main/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`](https://github.com/neo4j-contrib/neomodel/blob/main/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.