Registry / database / dbutils

dbutils

JSON →
library3.2.0pypypi✓ verified 26d ago

DBUtils is a suite of Python modules providing robust, persistent, and pooled connections to a database, designed for multi-threaded environments. It supports DB-API 2 compliant database interfaces and the classic PyGreSQL interface. The current version, 3.1.2, is actively maintained and supports Python versions 3.7 to 3.14.

pip install DBUtils
INSTALL
IMPORT
SIG · DBUTILS
D
dbutils
databasepythonv3.2.0
Install
1.6s avg
Import
10ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.008s · 18MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.006s · 19MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PooledDB
from dbutils.pooled_db import PooledDB
PersistentDB
from dbutils.persistent_db import PersistentDB
SimplePooledDB
from dbutils.simple_pooled_db import SimplePooledDB
Not recommended for production use; intended as a basic reference implementation.

This quickstart demonstrates how to set up and use `PooledDB` with an in-memory SQLite database. Replace `sqlite3.connect` with your specific DB-API 2 compliant database connector (e.g., `psycopg2.connect`) and provide appropriate connection arguments for your database.

import sqlite3 from dbutils.pooled_db import PooledDB # This example uses sqlite3 which is part of Python's standard library. # For other databases, replace sqlite3.connect with your actual DB-API 2 connect function, # e.g., import psycopg2; db_module = psycopg2 # Create a pool of connections # mincached: Minimum number of connections to keep in the pool # maxcached: Maximum number of connections to keep in the pool # maxconnections: Maximum number of connections to create in total # blocking: Whether to block if maxconnections is reached (True) or raise an error (False) # creator: The DB-API 2 module's connect function pool = PooledDB( creator=sqlite3.connect, database=":memory:", # Use an in-memory SQLite database for the example mincached=2, maxcached=5, maxconnections=10, blocking=True ) def get_data_from_db(pool_instance): conn = None cursor = None try: # Get a connection from the pool conn = pool_instance.connection() cursor = conn.cursor() cursor.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)") cursor.execute("INSERT INTO users (name) VALUES ('Alice')") conn.commit() cursor.execute("SELECT * FROM users") rows = cursor.fetchall() print(f"Fetched users: {rows}") return rows except Exception as e: print(f"An error occurred: {e}") if conn: conn.rollback() finally: # Return the connection to the pool if conn: conn.close() if __name__ == "__main__": print("Running quickstart example for DBUtils.PooledDB") get_data_from_db(pool) get_data_from_db(pool) # Get data again, should reuse pooled connections print("Example finished.")
Debug
Known issues
breakingVersion 2.0 introduced significant breaking changes. Users upgrading from versions 1.x should carefully review the changelog to understand necessary modifications to their code.
fix
Consult the official DBUtils changelog and documentation for migration guidance when upgrading from pre-2.0 versions.
affects: 2.0.0 and above
gotchaThe `dbutils.simple_pooled_db.SimplePooledDB` class is provided as a basic reference implementation and is explicitly NOT recommended for production use due to lacking sophisticated features like failover.
fix
For production environments, always use `dbutils.pooled_db.PooledDB` or `dbutils.persistent_db.PersistentDB` for robust connection management.
affects: All versions
gotchaDBUtils itself does not include a database driver. You must separately install a DB-API 2 compliant driver for your specific database (e.g., `psycopg2` for PostgreSQL, `mysql-connector-python` for MySQL, `cx_Oracle` for Oracle) and pass its `connect` function to `PooledDB` or `PersistentDB`.
fix
Ensure the appropriate database driver is installed via pip (e.g., `pip install psycopg2-binary`) and imported into your application.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dbutils'
This error often occurs when developers confuse the PyPI `DBUtils` library (for database connection pooling) with the built-in `dbutils` utilities found in Databricks environments, or if the `DBUtils` package itself is not installed or imported with the correct casing.
fix
Ensure the `DBUtils` package is installed via `pip install DBUtils`. Then, import specific components with correct casing, for example: `from DBUtils.PooledDB import PooledDB`.
AttributeError: __enter__
This error happens when attempting to use a connection object obtained from `DBUtils.PooledDB` directly with a Python `with` statement, which was not natively supported in older versions of the library or due to issues with attribute proxying.
fix
Upgrade `DBUtils` to version 2.0.2 or newer, which added `__enter__` and `__exit__` methods to connection objects. Alternatively, for older versions, use `contextlib.closing` or explicitly call `connection.close()` in a `finally` block.
DBUtils.PooledDB.TooManyConnections
This specific exception is raised by `PooledDB` when the maximum number of allowed connections (`maxconnections`) has been reached, and the `blocking` parameter in the `PooledDB` constructor is set to `False`, preventing the request from waiting for an available connection.
fix
Increase the `maxconnections` parameter in the `PooledDB` constructor, ensure that database connections are properly closed and returned to the pool after use, or set `blocking=True` to make connection requests wait until a connection becomes available.
OperationalError: (2003, "Can't connect to MySQL server on 'localhost' (10061)") (or similar DB-API 2 connection error)
This (or a similar `OperationalError`, `InterfaceError`, etc.) typically arises when the `creator` function or module passed to `PooledDB` or `PersistentDB` cannot establish a valid connection to the database, often due to incorrect host, port, credentials, or an unavailable database server.
fix
Verify that the database server is running and accessible, and that all connection parameters (host, port, user, password, database) passed to your `creator` function (e.g., `pymysql.connect`, `psycopg2.connect`) are correct. Ensure the `creator` function returns a valid DB-API 2 compliant connection object.
Upgrade
Version history
3.2.0latest on PyPI · released Aug 21, 2026
Audit
Dependencies
Any DB-API 2 compliant database driver (e.g., psycopg2, mysql-connector-python, cx_Oracle) or PyGreSQLrequiredDBUtils requires a separate database driver to connect to a specific database. It does not include one itself.
Agent activity
41 hits · last 30 days
node
40
Resources