摘要：是一個允許在多線程應用和數據庫之間安全及高效連接的模塊套件。實現了穩定，線程仿射，持久化的數據庫連接。線程結束時該連接會自動關閉。但仍可以請求非線程共享的專用數據庫連接。

DBUtils是一個允許在多線程python應用和數據庫之間安全及高效連接的python模塊套件。

DBUtils套件包含兩個模塊子集，一個適用于兼容DB-API 2接口的模塊，一個適用于PyGreSQL的模塊。

Universal DB-API 2 variant

該子集下的模塊依賴關系如圖：

Classic PyGreSQL variant

該子集下的模塊依賴關系如圖：

DBUtils.SimplePooledDB是池化數據庫連接中非常基礎的一種實現。相較于PooledDB，它并不那么復雜，且缺少failover機制。SimplePooledDB應視為一種概念演示，不要直接在生產環境使用。

DBUtils.SteadyDB基于兼容DB-API 2接口的數據庫模塊創建的普通連接，實現了"加強"連接。具體指當數據庫連接關閉、丟失或使用頻率超出限制時，將自動重新獲取連接。

典型的應用場景如下：在某個維持了某些數據庫連接的程序運行時重啟了數據庫，或在某個防火墻隔離的網絡中訪問遠程數據庫時重啟了防火墻。

DBUtils.PersistentDB實現了穩定，線程仿射(thread-affine)，持久化的數據庫連接。下圖顯式了使用PersistentDB進行連接時涉及的連接層：

某個線程第一次開啟一個數據庫連接時，該連接將用于此特定線程。即使在線程中關閉連接，連接也會保持打開狀態，以便同一個線程的下一次連接請求直接使用。線程結束時該連接會自動關閉。

簡而言之：PersistentDB會回收數據庫連接從而在整體上增加多線程應用的數據庫訪問性能，它確保線程之間永遠不會共享連接。

因此即使底層的DB-API模塊不是connection級別的線程安全，PersistentDB也可以完美實現線程安全，避免在其他線程更改數據庫會話或執行跨多個SQL指令的事務時出現問題。

要使用PersistentDB模塊，首先傳遞以下參數創建PersistentDB實例：

creator：兼容DB-API 2的數據庫模塊或返回DB-API 2連接的任意函數

maxusage：單個連接的最大重用次數(0或None表示無重用次數限制)，達到該限制后自動關閉并重新打開連接

setsession：設置連接會話的sql指令列表，比如["set wait_timeout = 100", ...]

failures：異常類或異常類元組。在默認的(OperationalError, InternalError)不能處理連接failover機制時使用

ping：如果ping()方法可用，該值表示何時使用ping()方法檢查連接(0 = None = never, 1 = default = whenever it is requested, 2 = when a cursor is created, 4 = when a query is executed, 7 = always, and all other bit combinations of these values)

closeable：如果設置為True，將允許手動close()連接，默認為False，忽略關閉連接的操作，只在線程終止時自動關閉

threadlocal：表示thread-local數據的類。設置值為threading.local可能獲取連接的速度更快，但不一定適用于所有情況(例如，mod_wsgi會清空requests之間的threading.local數據)

傳遞給creator參數值創建connection對象的參數，如host, database等

import pymysql
from DBUtils.PersistentDB import PersistentDB

persist = PersistentDB(creator=pymysql, user="root", passwd="123456", db="test")
# conn的使用和常規DB-API 2接口類似
conn = persist.connection()

NOTE:需要在連接上調用begin()方法明確開啟事務。這可以確保a.只在事務完成時才重新打開連接b.連接被同一個線程重用時回滾。

DBUtils.PooledDB實現了穩定、線程安全的緩存連接池。下圖顯式了使用PooledDB進行連接時涉及的連接層：

使用正整數的maxshared參數和connection級別的線程安全的creator參數創建連接池時，連接池中的連接默認是線程間共享的。但仍可以請求非線程共享的專用數據庫連接。

除了共享連接池外，還可以創建至少mincached個，至多maxcached個連接的空閑連接池，在共享連接池未滿(不太理解)或線程請求專用數據庫連接時使用。當某個線程關閉不再共享的連接時，該連接將回收到空閑連接池以便再次使用。

如果底層的DB-API 2模塊非線程安全，將使用線程鎖確保PooledDB連接是線程安全的。但對于線程專用的連接，要小心更改數據庫會話或執行跨多個SQL指令的事務帶來的不良影響。

要使用PoolDB模塊，首先傳遞以下參數創建PoolDB實例：

creator：同PersistentDB

mincached：連接池中空閑連接的初始數量(0表示不創建初始空閑連接)

maxcached：連接池中允許的最大空閑連接數(0或None表示無限制)

maxshared：允許的最大共享連接數(0或None表示所有連接都是專用的)，When this maximum number is reached, connections are shared if they have been requested as shareable

maxconnections：允許的最大連接數(0或None表示無限制)

blocking：查過最大值是否阻塞。True表示將阻塞直到釋放新的連接，默認False表示拋出異常

maxusage：同PersistentDB

setsession：同PersistentDB

reset：返回連接池時應該怎樣重置連接(False或None將只回滾明確調用了begin()開啟的事務，默認值為True，出于安全考慮總是會回滾)

failures：同PersistentDB

ping：同PersistentDB

傳遞給creator參數值創建connection對象的參數，如host, database等

import pymysql
from DBUtils.PooledDB import PooledDB

pool = PooledDB(creator=pymysql, 5, user="root", passwd="123456", db="test")
# conn的使用和常規DB-API 2接口類似
conn = pool.connection()

對于線程共享的連接池，可以用以下方式獲取線程專用連接：

conn = pool.connection(shareable=False)
# 或者
conn = pool.dedicated_connection()

對于不再使用的連接，調用close()方法回收到連接池。

在多線程環境中，不要寫以下代碼，這會導致連接過早釋放并被其他線程重用，如果連接非線程安全可能導致程序出現嚴重錯誤：

pool.connection().cursor().execute(...)

NOTE:需要在連接上調用begin()方法明確開啟事務。這可以確保a.只在事務完成時才重新打開連接b.連接在返回連接池之前執行回滾c.連接不會被其他線程共享

PooledDB和PersistentDB都通過回收數據庫連接，且即使數據庫連接中斷也能保持穩定性的方式從而達到提升數據庫訪問性能的目的。在現實場景中應該如何選擇呢？對于保持常量線程數且頻繁使用數據庫的應用，使用PersistentDB；對于頻繁開啟、結束線程的應用，使用PooledDB。

如果程序中使用了ORM框架，如SQLObject或SQLAlchemy，不需要使用DBUtils，因為這些框架自身維護了連接池。

數據庫線程安全級別：

比如pymysql就是可以共享模塊但不能共享連接，查看方式pymysql.threadsafety