Configuration¶

Neomodel provides a modern, type-safe configuration system for connecting to your Neo4j database. This guide covers the recommended approach using the new dataclass-based configuration system (available from version 6.0), with backward compatibility information for existing code.

Database Connection Setup¶

The primary way to configure neomodel is to set up your database connection. There are two approaches:

Neomodel-managed connection (recommended) - Let neomodel handle the driver lifecycle
Self-managed connection - Provide your own Neo4j driver instance

Neomodel-managed Connection (Recommended)¶

This is the simplest and most common approach. Neomodel will create and manage the Neo4j driver for you.

Basic connection setup:

from neomodel import get_config

config = get_config()
config.database_url = 'bolt://neo4j:password@localhost:7687'

You can also set the database name separately:

config.database_url = 'bolt://neo4j:password@localhost:7687'
config.database_name = 'mydatabase'

Advanced driver configuration, for example:

config.connection_timeout = 60.0
config.max_connection_pool_size = 50
config.encrypted = True
config.keep_alive = True

Self-managed Connection¶

If you need more control over the driver configuration, you can provide your own Neo4j driver:

from neo4j import GraphDatabase
from neomodel import get_config

# Create your own driver
driver = GraphDatabase.driver(
    'bolt://localhost:7687',
    auth=('neo4j', 'password'),
    encrypted=True,
    max_connection_lifetime=3600
)

# Pass it to neomodel
config = get_config()
config.driver = driver

Note

When using a self-managed driver, you are responsible for closing it when your application shuts down.

Modern Configuration System (Version 6.0+)¶

Neomodel 6.0 introduces a modern dataclass-based configuration system with the following benefits:

Type Safety: All configuration values are properly typed
Validation: Configuration values are validated at startup and when changed
Environment Variables: Automatic loading from environment variables
IDE Support: Better autocomplete and type checking

Using the Modern Configuration API¶

Access and modify configuration:

from neomodel import get_config, set_config, reset_config

# Get the current configuration
config = get_config()
print(config.database_url)
print(config.force_timezone)

# Update configuration
config.update(database_url='bolt://new:url@localhost:7687')

# Set a custom configuration
from neomodel import NeomodelConfig
custom_config = NeomodelConfig(
    database_url='bolt://custom:url@localhost:7687',
    force_timezone=True
)
set_config(custom_config)

# Reset to defaults (loads from environment variables or defaults)
reset_config()

Environment Variable Support¶

Configuration is automatically loaded from environment variables using the NEOMODEL_ prefix:

NEOMODEL_DATABASE_URL - Database connection URL
NEOMODEL_DATABASE_NAME - Database name for custom driver
NEOMODEL_CONNECTION_ACQUISITION_TIMEOUT - Connection acquisition timeout
NEOMODEL_CONNECTION_TIMEOUT - Connection timeout
NEOMODEL_ENCRYPTED - Enable encrypted connections
NEOMODEL_KEEP_ALIVE - Enable keep-alive connections
NEOMODEL_MAX_CONNECTION_LIFETIME - Maximum connection lifetime
NEOMODEL_MAX_CONNECTION_POOL_SIZE - Maximum connection pool size
NEOMODEL_MAX_TRANSACTION_RETRY_TIME - Maximum transaction retry time
NEOMODEL_USER_AGENT - User agent string
NEOMODEL_FORCE_TIMEZONE - Force timezone-aware datetime objects
NEOMODEL_SOFT_CARDINALITY_CHECK - Enable soft cardinality checking
NEOMODEL_CYPHER_DEBUG - Enable Cypher debug logging
NEOMODEL_SLOW_QUERIES - Threshold in seconds for slow query logging (0 = disabled)

Note

For boolean values, the following strings are supported: true, 1, yes, on, false, 0, no, off.

Example:

# Set environment variables
export NEOMODEL_DATABASE_URL='bolt://neo4j:password@localhost:7687'
export NEOMODEL_FORCE_TIMEZONE='true'
export NEOMODEL_CONNECTION_TIMEOUT='60.0'

# Configuration will be automatically loaded from environment
from neomodel import config
print(config.DATABASE_URL)  # 'bolt://neo4j:password@localhost:7687'
print(config.FORCE_TIMEZONE)  # True
print(config.CONNECTION_TIMEOUT)  # 60.0

neomodel.config.get_config() → NeomodelConfig¶: Get the global configuration instance.

See also the NeomodelConfig dataclass for a full list of fields, typing and options:

class neomodel.config.NeomodelConfig(database_url: str = 'bolt://neo4j:foobarbaz@localhost:7687', driver: Driver | None = None, database_name: str | None = None, connection_acquisition_timeout: float = 60.0, connection_timeout: float = 30.0, encrypted: bool = False, keep_alive: bool = True, max_connection_lifetime: int = 3600, max_connection_pool_size: int = 100, max_transaction_retry_time: float = 30.0, resolver: Any | None = None, trusted_certificates: Any = <factory>, user_agent: str = 'neomodel/v6.0.1', force_timezone: bool = False, soft_cardinality_check: bool = False, cypher_debug: bool = False, slow_queries: float = 0.0)¶

Bases: object

Neomodel configuration using dataclasses with validation and environment variable support.

This class provides a modern, type-safe configuration system that can be loaded from environment variables and validated at startup.

connection_acquisition_timeout: float = 60.0¶

connection_timeout: float = 30.0¶

cypher_debug: bool = False¶

database_name: str | None = None¶

database_url: str = 'bolt://neo4j:foobarbaz@localhost:7687'¶

driver: Driver | None = None¶

encrypted: bool = False¶

force_timezone: bool = False¶

classmethod from_env() → NeomodelConfig¶: Create configuration from environment variables.

keep_alive: bool = True¶

max_connection_lifetime: int = 3600¶

max_connection_pool_size: int = 100¶

max_transaction_retry_time: float = 30.0¶

resolver: Any | None = None¶

slow_queries: float = 0.0¶

soft_cardinality_check: bool = False¶

to_dict() → Dict[str, Any]¶: Convert configuration to dictionary.

trusted_certificates: Any¶

update(**kwargs) → None¶: Update configuration values.

user_agent: str = 'neomodel/v6.0.1'¶

Configuration Validation¶

The configuration system validates values when they are set:

from neomodel import get_config

config = get_config()

# This will raise a ValueError
try:
    config.connection_timeout = -1
except ValueError as e:
    print(f"Validation error: {e}")

# Invalid database URLs are also caught
try:
    config.database_url = "invalid-url"
except ValueError as e:
    print(f"Validation error: {e}")

Legacy Configuration (Backward Compatibility)¶

Warning

The legacy configuration approach described below is deprecated and will be removed in a future version. Deprecation warnings are shown when using the legacy API to encourage migration to the modern configuration system.

Note

The following section describes the legacy configuration approach, available in neomodel 5.5.3 and earlier. While still supported for backward compatibility, we recommend using the modern configuration system described above.

For existing code, the traditional uppercase configuration attributes are still available:

from neomodel import config

# Legacy approach (still works but shows deprecation warnings)
config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687'
config.MAX_CONNECTION_POOL_SIZE = 100
config.CONNECTION_ACQUISITION_TIMEOUT = 60.0
config.CONNECTION_TIMEOUT = 30.0
config.ENCRYPTED = False
config.KEEP_ALIVE = True
config.MAX_CONNECTION_LIFETIME = 3600
config.MAX_TRANSACTION_RETRY_TIME = 30.0
config.RESOLVER = None
config.TRUST = neo4j.TRUST_SYSTEM_CA_SIGNED_CERTIFICATES
config.USER_AGENT = 'neomodel/v5.5.1'

Setting the database name with legacy approach:

# Using the URL only
config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687/mydb'

# Using config option
config.DATABASE_URL = 'bolt://neo4j:neo4j@localhost:7687'
config.DATABASE_NAME = 'mydb'

Legacy self-managed driver setup:

from neo4j import GraphDatabase
my_driver = GraphDatabase().driver('bolt://localhost:7687', auth=('neo4j', 'password'))
config.DRIVER = my_driver

Note

Only the synchronous driver works with the legacy self-managed approach. For async drivers, use the modern configuration system.

Deprecation Warnings¶

When using the legacy configuration API, deprecation warnings are shown to encourage migration:

import warnings
from neomodel import config

# This will show a deprecation warning
config.DATABASE_URL = 'bolt://neo4j:password@localhost:7687'
# DeprecationWarning: Setting config.DATABASE_URL is deprecated and will be removed in a future version.
# Use the modern configuration API instead:
# from neomodel import get_config; config = get_config(); config.database_url = value

To suppress deprecation warnings temporarily (not recommended for production):

import warnings
warnings.filterwarnings('ignore', category=DeprecationWarning, module='neomodel.config')

# Now legacy config access won't show warnings
config.DATABASE_URL = 'bolt://neo4j:password@localhost:7687'

Migration Guide¶

To migrate from legacy to modern configuration:

Before (Legacy):

from neomodel import config
config.DATABASE_URL = 'bolt://neo4j:password@localhost:7687'
config.FORCE_TIMEZONE = True
config.MAX_CONNECTION_POOL_SIZE = 50

After (Modern):

from neomodel import get_config
config = get_config()
config.database_url = 'bolt://neo4j:password@localhost:7687'
config.force_timezone = True
config.max_connection_pool_size = 50

Managing Connections¶

Changing Connections¶

You can change the connection at any time using the modern configuration API:

from neomodel import get_config

config = get_config()
config.database_url = 'bolt://new:url@localhost:7687'

# Using self-managed driver
db.set_connection(driver=my_driver)

Or using the legacy approach:

from neomodel import db
# Using URL - auto-managed
db.set_connection(url='bolt://neo4j:neo4j@localhost:7687')

Closing Connections¶

Since Neo4j version 5, driver auto-close is deprecated. Make sure to close the connection when your application shuts down:

from neomodel import db
db.close_connection()

This will close the Neo4j driver and clean up neomodel’s internal resources.

Security Best Practices¶

Protect Your Credentials¶

You should avoid setting database access credentials in plain sight.

Recommended approach using environment variables:

# Set environment variables
export NEOMODEL_DATABASE_URL='bolt://neo4j:password@localhost:7687'

# Configuration automatically loads from environment
from neomodel import get_config
config = get_config()

Additional Configuration Options¶

Force Timezone on DateTime Properties¶

Ensure all DateTimes are provided with a timezone before being serialized to UTC epoch:

from neomodel import get_config

config = get_config()
config.force_timezone = True  # default False

Enable Soft Cardinality Checking¶

Enable warnings instead of errors for relationship cardinality violations:

config.soft_cardinality_check = True  # default False

Enable Cypher Debug Logging¶

Log all Cypher queries for debugging:

config.cypher_debug = True  # default False

Enable Slow Query Logging¶

Log queries that take longer than the specified threshold:

config.slow_queries = 1.0  # Log queries taking more than 1 second

Index and Constraint Management¶

Neomodel provides the neomodel_install_labels script for automatic index and constraint creation.

Install indexes and constraints for a single class:

from neomodel import install_labels
install_labels(YourClass)

Or for an entire schema:

import yourapp  # make sure your app is loaded
from neomodel import install_all_labels

install_all_labels()
# Output:
# Setting up labels and constraints...
# Found yourapp.models.User
# + Creating unique constraint for name on label User for class yourapp.models.User
# ...

Note

config.AUTO_INSTALL_LABELS has been removed from neomodel in version 5.3