I-edit

Connection pooling in mssql-django

This article explains how connection pooling works in mssql-django and how to configure it for your Django application.

How connection pooling works

By default, mssql-django uses driver-level connection pooling. The default pyodbc path uses pyodbc pooling, and the mssql-python path uses mssql-python pooling. When Django closes a connection, the active driver returns it to a pool instead of closing the underlying database connection. Subsequent connection requests reuse pooled connections, which reduces the overhead of establishing new database connections. For driver selection details, see Select the database driver for mssql-django.

Configure connection pooling

Connection pooling is controlled by the DATABASE_CONNECTION_POOLING setting, which is placed at the module level in settings.py (outside the DATABASES dictionary):

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

# Set to False to disable driver-level connection pooling
DATABASE_CONNECTION_POOLING = False
Value Behavior
True (default) Connection pooling is enabled. Closed connections are returned to the pool.
False Driver-level connection pooling is disabled. The pyodbc path sets Database.pooling=False, and the mssql-python path calls PoolingManager.disable().

When to disable connection pooling

Consider disabling connection pooling in these scenarios:

  • Token-based authentication: When using access tokens that expire, pooled connections might hold stale tokens.
  • Debugging connection issues: Disabling pooling simplifies troubleshooting by ensuring each request creates a fresh connection.
  • Short-lived processes: For scripts or management commands that make a few queries and exit, pooling adds no benefit.

Connection retry settings

Regardless of the pooling setting, you can configure retry behavior for failed connection attempts. For the full list of retry and timeout options, see Configuration reference.

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
            "connection_retries": 3,
            "connection_retry_backoff_time": 10,
            "connection_timeout": 30,
        },
    },
}

Django's CONN_MAX_AGE

Django also provides a CONN_MAX_AGE setting that controls how long Django keeps a database connection open before closing it. This setting works alongside driver-level connection pooling:

DATABASES = {
    "default": {
        "ENGINE": "mssql",
        "NAME": "<your-database>",
        "USER": "<your-username>",
        "PASSWORD": "<your-password>",
        "HOST": "<your-server>",
        "PORT": "1433",
        "CONN_MAX_AGE": 600,  # Keep connections open for 10 minutes
        "OPTIONS": {
            "driver": "ODBC Driver 18 for SQL Server",
        },
    },
}

For more information about CONN_MAX_AGE, see the Django database settings documentation.

Practical starting points:

  • CONN_MAX_AGE=0: safest for debugging and short-lived jobs.
  • CONN_MAX_AGE=600: good default for many web apps.
  • CONN_MAX_AGE=3600: reasonable for steady high-throughput services after load testing.

Note

When you use ASGI servers (such as Daphne or Uvicorn) or threaded deployments, persistent connections can leak across async contexts. If you use CONN_MAX_AGE with an ASGI server, set CONN_HEALTH_CHECKS = True in supported Django versions and test under realistic concurrency. For more information, see the Django documentation on connection management.

CONN_HEALTH_CHECKS validates pooled connections before reuse. If Django detects a stale connection, it transparently opens a fresh one. This adds a small per-request check cost and is usually worth enabling for long-lived processes.

Related content

  • Last updated on