Django 模型查询中的数据库连接池配置指南

写给每一个被too many connections报错折磨过的 Django 开发者。

一、先搞清楚：Django 默认是怎么管连接的？

Django 自带的django.db.backends在每次请求结束时，会根据CONN_MAX_AGE决定是否关闭数据库连接：

# settings.py 默认配置DATABASES={'default':{'ENGINE':'django.db.backends.postgresql','CONN_MAX_AGE':0,# 每次请求后都关闭连接}}

• CONN_MAX_AGE = 0：请求结束立刻断开，下个请求重新建连。安全但慢。
• CONN_MAX_AGE = None：永久复用同一个连接。快但有风险（连接断开后不会自动重连）。
• CONN_MAX_AGE = 60：60 秒内复用连接，超时后重建。这是官方推荐的折中方案。

但这只是 Django 层面的"连接复用"，不是连接池。当并发上来，每个 Worker 进程仍会各自持有连接，连接数 = Worker 数 × 并发请求数，数据库照样扛不住。

二、什么时候你真正需要连接池？

核心矛盾：应用层想复用连接，但 Django 默认的复用粒度太粗（按进程），不够细（按请求）。

三、四种主流方案，从简单到生产级

方案一：调大CONN_MAX_AGE（最简单，但不够）

DATABASES={'default':{'CONN_MAX_AGE':600,# 10 分钟内复用}}

优点：零依赖，一行代码搞定。

缺点：仍然是进程级复用，没法限制总连接数。适合轻量场景。

方案二：django-db-connection-pool（推荐入门）

这是一个专门为 Django 设计的连接池库，基于DBUtils.PersistentDB，支持 PostgreSQL / MySQL。

安装：

pipinstalldjango-db-connection-pool

配置：

DATABASES={'default':{'ENGINE':'django_db_connection_pool.backends.postgresql','NAME':'mydb','USER':'myuser','PASSWORD':'mypass','HOST':'localhost','POOL_OPTIONS':{'POOL_SIZE':10,# 池中最大连接数'MAX_OVERFLOW':5,# 超出池大小后最多额外创建的连接数'RECYCLE':3600,# 连接最大存活时间（秒）'TIMEOUT':30,# 获取连接的等待超时（秒）},}}

关键参数说明：

效果： 原本 10 个 Worker 各自建 10 个连接 = 100 个连接，现在 10 个 Worker 共用 10 个连接的池，峰值最多 15 个。

方案三：PgBouncer（PostgreSQL 生产环境标配）

django-db-connection-pool是应用层连接池，性能和稳定性不如独立的连接池中间件。PostgreSQL 官方推荐用 PgBouncer。

架构变成：

Django App → PgBouncer (连接池) → PostgreSQL

快速部署（Docker）：

# docker-compose.ymlservices:pgbouncer:image:edoburu/pgbouncerenvironment:-DATABASE_URL=postgres://user:pass@postgres:5432/mydb-POOL_MODE=transaction-MAX_CLIENT_CONN=1000-DEFAULT_POOL_SIZE=25ports:-"6432:6432"

Django 配置（连 PgBouncer，不连 PG 直接）：

DATABASES={'default':{'ENGINE':'django.db.backends.postgresql','HOST':'pgbouncer',# 注意：不是原来的 pg 主机'PORT':'6432',# PgBouncer 端口'NAME':'mydb',# ... 其他不变'CONN_MAX_AGE':0,# 必须设为 0！因为 PgBouncer 自己管池}}

⚠️ 关键坑：CONN_MAX_AGE必须设为 0。

原因：PgBouncer 的transaction模式下，如果 Django 持有连接不放，会导致连接无法回池。设为 0 让 Django 用完即还，PgBouncer 负责复用。

三种 Pool Mode 对比：

方案四：使用psycopg2自带的连接池（轻量替代）

如果你不想引入额外组件，可以用psycopg2内置的ThreadedConnectionPool：

# settings.pyimportpsycopg2frompsycopg2importpool# 创建全局连接池（Django 启动时初始化）connection_pool=psycopg2.pool.ThreadedConnectionPool(minconn=1,maxconn=10,host='localhost',database='mydb',user='myuser',password='mypass')DATABASES={'default':{'ENGINE':'django.db.backends.postgresql',# 不配置 HOST/PORT/USER/PASSWORD，用自定义的 getconn'CONN_MAX_AGE':None,}}# Monkey patch：让 Django 用我们的池fromdjango.db.backends.postgresql.baseimportDatabaseWrapperdefget_connection(self):conn=connection_pool.getconn()returnconn DatabaseWrapper.get_new_connection=get_connection# 归还连接defclose_connection(self,conn):connection_pool.putconn(conn)self.connection=NoneDatabaseWrapper.close=close_connection

优点：无第三方依赖。

缺点：需要 monkey patch，升级 Django 可能失效，不够优雅。

四、怎么选？一张表说清楚

五、生产环境的完整配置示例（推荐组合）

# settings.pyDATABASES={'default':{'ENGINE':'django.db.backends.postgresql','NAME':'mydb','USER':'myuser','PASSWORD':env('DB_PASSWORD'),'HOST':'pgbouncer',# 指向 PgBouncer'PORT':'6432','CONN_MAX_AGE':0,# ⚠️ 关键：必须为 0'OPTIONS':{'connect_timeout':10,'application_name':'myapp',# 方便 PG 侧监控},}}# Gunicorn 配置（配合连接池）# gunicorn.conf.pyworkers=4# Worker 数 = POOL_SIZE / 2 左右worker_class='gevent'# 或 sync，取决于你的视图是否有阻塞 IOtimeout=30keepalive=5

六、监控：你怎么知道连接池生效了？

-- PostgreSQL 查看当前连接数SELECTcount(*),stateFROMpg_stat_activityGROUPBYstate;-- 查看 PgBouncer 池状态（连接 PgBouncer 的管理库）SHOWPOOLS;SHOWCLIENTS;

关键指标：

• active connections应远小于max_connections
• waiting requests应接近 0
• 如果waiting requests持续 > 0，说明池太小，需要调大POOL_SIZE

总结

连接池不是银弹，但它是 Django 从"能跑"到"扛得住"的必经之路。