{"id":8093,"library":"django-db-connection-pool","title":"Django DB Connection Pool","description":"django-db-connection-pool is a Python library that provides database connection pooling components for Django, supporting MySQL, Oracle, PostgreSQL, and JDBC-compatible databases. It is based on SQLAlchemy's connection pooling mechanisms, designed to improve performance and resource management in multiprocessing and multithreading Django projects by reusing database connections. The current version is 1.2.6, and it sees active maintenance.","status":"active","version":"1.2.6","language":"en","source_language":"en","source_url":"https://github.com/altairbow/django-db-connection-pool","tags":["django","database","connection pooling","performance","SQLAlchemy","MySQL","PostgreSQL","Oracle","JDBC"],"install":[{"cmd":"pip install django-db-connection-pool","lang":"bash","label":"Basic Installation"},{"cmd":"pip install django-db-connection-pool[all]","lang":"bash","label":"Install with all database engines"},{"cmd":"pip install django-db-connection-pool[mysql,postgresql]","lang":"bash","label":"Install with specific engines (e.g., MySQL, PostgreSQL)"}],"dependencies":[{"reason":"The library's connection pooling is based on SQLAlchemy's pooling mechanisms.","package":"SQLAlchemy","optional":false},{"reason":"Required for MySQL backend support.","package":"mysqlclient","optional":true},{"reason":"Required for Oracle backend support.","package":"cx_Oracle","optional":true},{"reason":"Required for PostgreSQL backend support (or `psycopg` for newer versions).","package":"psycopg2-binary","optional":true},{"reason":"Required for JDBC backend support.","package":"JPype1","optional":true}],"imports":[{"note":"The 'ENGINE' path must be changed to the pooling backend provided by dj_db_conn_pool.","wrong":"DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql' } }","symbol":"MySQL Connection Pool","correct":"DATABASES = { 'default': { 'ENGINE': 'dj_db_conn_pool.backends.mysql' } }"},{"note":"Ensure to replace the default Django PostgreSQL engine with the pooling variant.","wrong":"DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql' } }","symbol":"PostgreSQL Connection Pool","correct":"DATABASES = { 'default': { 'ENGINE': 'dj_db_conn_pool.backends.postgresql' } }"},{"note":"Similar to other backends, the Oracle engine path needs to be updated.","wrong":"DATABASES = { 'default': { 'ENGINE': 'django.db.backends.oracle' } }","symbol":"Oracle Connection Pool","correct":"DATABASES = { 'default': { 'ENGINE': 'dj_db_conn_pool.backends.oracle' } }"},{"note":"Specific backend for JDBC Oracle connections.","symbol":"JDBC Oracle Connection Pool","correct":"DATABASES = { 'default': { 'ENGINE': 'dj_db_conn_pool.backends.jdbc.oracle' } }"},{"note":"Used to change default pool arguments globally before any pool is created.","symbol":"dj_db_conn_pool.setup","correct":"import dj_db_conn_pool\ndj_db_conn_pool.setup(pool_size=100, max_overflow=50)"}],"quickstart":{"code":"import os\n\n# settings.py\n\nDATABASES = {\n    'default': {\n        'ENGINE': 'dj_db_conn_pool.backends.postgresql',\n        'NAME': os.environ.get('DB_NAME', 'mydatabase'),\n        'USER': os.environ.get('DB_USER', 'myuser'),\n        'PASSWORD': os.environ.get('DB_PASSWORD', 'mypassword'),\n        'HOST': os.environ.get('DB_HOST', 'localhost'),\n        'PORT': os.environ.get('DB_PORT', '5432'),\n        # Important: Set CONN_MAX_AGE to 0 or None when using an external pooler to avoid conflicts\n        'CONN_MAX_AGE': 0,\n        'POOL_OPTIONS': {\n            'POOL_SIZE': 10,\n            'MAX_OVERFLOW': 5,\n            'RECYCLE': 3600, # Recycle connections after 1 hour\n            'TIMEOUT': 30 # Connection checkout timeout\n        }\n    }\n}\n\n# Example of using a connection (standard Django ORM operations apply)\n# from django.db import connections\n# from myapp.models import MyModel\n#\n# try:\n#    obj = MyModel.objects.first()\n#    print(obj)\n# except Exception as e:\n#    print(f\"Database error: {e}\")","lang":"python","description":"To quickly integrate `django-db-connection-pool`, update your `DATABASES` setting in `settings.py` by changing the `ENGINE` to the appropriate `dj_db_conn_pool.backends` path. It is crucial to set `CONN_MAX_AGE` to `0` or `None` to prevent Django's built-in persistent connection logic from conflicting with the connection pool. You can further customize pooling behavior using the `POOL_OPTIONS` dictionary, which accepts parameters like `POOL_SIZE`, `MAX_OVERFLOW`, `RECYCLE`, and `TIMEOUT`."},"warnings":[{"fix":"For PostgreSQL on Django 5.1+, consider using Django's native pooling by setting `DATABASES['default']['OPTIONS']['pool'] = True` or a dictionary of `psycopg_pool.ConnectionPool` options. If using `django-db-connection-pool`, ensure `CONN_MAX_AGE` is 0 and test thoroughly for conflicts.","message":"Django 5.1+ includes native connection pooling for PostgreSQL using `psycopg`. Using `django-db-connection-pool` alongside or instead of the native solution for PostgreSQL on Django 5.1+ might lead to unexpected behavior, performance issues, or redundancy. Assess whether the native pooling meets your needs before opting for this third-party library for PostgreSQL with Django 5.1 and above.","severity":"breaking","affected_versions":"Django 5.1+"},{"fix":"Carefully calculate and configure `POOL_SIZE` and `MAX_OVERFLOW` in `POOL_OPTIONS` considering the number of worker processes your application uses to avoid exceeding database connection limits.","message":"In multiprocessing environments (e.g., uWSGI, Gunicorn with multiple workers), each process will instantiate its own independent connection pool. This means the total number of connections to your database can be `number_of_workers * (pool_size + max_overflow)`, which might exceed your database's connection limits if not properly configured.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always set `CONN_MAX_AGE` to `0` or `None` in your `DATABASES` settings when using `django-db-connection-pool`. Let the pooling library handle the full lifecycle and recycling of connections.","message":"Setting Django's `CONN_MAX_AGE` to a positive value will conflict with `django-db-connection-pool`'s connection management, as `CONN_MAX_AGE` implements Django's own form of persistent connections. This can lead to connections being closed or recycled prematurely by Django, or the pool failing to manage connections effectively.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always ensure that database transactions are explicitly committed or rolled back within your application logic. Use `with transaction.atomic():` blocks or equivalent patterns to ensure transaction integrity.","message":"Improper transaction management (e.g., not calling `commit()` or `rollback()` after a transaction) can lead to 'stale' connections being returned to the pool with an open transaction. While SQLAlchemy's pool aims to reset connections, applications should still ensure proper transaction hygiene.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install a JRE and set `export JAVA_HOME=/path/to/jre; export CLASSPATH=/path/to/jdbc_driver.jar` in your environment before running Django.","message":"For JDBC backend support, you must have a Java Runtime Environment (JRE) installed and correctly configure `JAVA_HOME` and `CLASSPATH` environment variables to include your JDBC driver JAR files. Without this, the JDBC backend will fail to connect.","severity":"gotcha","affected_versions":"All versions (when using JDBC backends)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Increase the `RECYCLE` value (e.g., `RECYCLE: 3600` for 1 hour, which should be less than the database's idle timeout) in `POOL_OPTIONS` to ensure connections are refreshed proactively. Also, ensure `TIMEOUT` is set appropriately to prevent long waits for unavailable connections.","cause":"The database connection was closed by the server due to inactivity (idle timeout) or a network issue before `django-db-connection-pool` could recycle it, and `RECYCLE` or `TIMEOUT` options are not adequately configured.","error":"OperationalError: (2006, 'MySQL server has gone away')"},{"fix":"Review and adjust `POOL_SIZE` and `MAX_OVERFLOW` in `POOL_OPTIONS` to better match your database server's `max_connections` and the number of application worker processes. Alternatively, consider an external pooler like PgBouncer for more centralized connection management, especially in highly concurrent environments.","cause":"The total number of active database connections (across all worker processes and their respective pools) has exceeded the database server's configured maximum connection limit.","error":"django.db.utils.OperationalError: FATAL: sorry, too many clients already"},{"fix":"Set `CONN_MAX_AGE = 0` (or `None`) in your `DATABASES` settings when using `django-db-connection-pool` or any connection pooling solution. The pool itself manages connection persistence.","cause":"This error occurs when Django's native connection pooling (introduced in Django 5.1 for PostgreSQL) is enabled with `CONN_MAX_AGE > 0`, or it's a general indicator of conflicting persistent connection settings when a pooling backend is used. Although not directly from `django-db-connection-pool`, it highlights the incompatibility.","error":"ImproperlyConfigured: Pooling doesn't support persistent connections"}]}