Raccoon Tools DB
A managed PostgreSQL connection pool (via psycopg 3) with opt-in FastAPI and OpenTelemetry integrations.
Installation
Base install:
uv add raccoontools-db
With OpenTelemetry instrumentation:
uv add raccoontools-db[otel]
With FastAPI OTEL instrumentation:
uv add raccoontools-db[fastapi]
All extras:
uv add raccoontools-db[all]
Functionalities
Connection Pool (raccoontools_db.pool)
Provides a module-level singleton connection pool with a simple create/get/close lifecycle.
PoolConfig
Configuration dataclass for the connection pool.
Fields:
conn_info(str): PostgreSQL connection string. Not included inrepr(config), since it usually holds the password.min_size(int): Minimum connections in pool (default: 2).max_size(int): Maximum connections in pool (default: 10).use_otel(bool): Enable OpenTelemetry tracing (default: False).otel_service_name(str): Service name for OTEL (required whenuse_otel=True).otel_exporter_endpoint(str): OTLP exporter endpoint (required whenuse_otel=True).otel_use_http(bool): Use HTTP protocol for OTLP (default: True).
create_pool(config: PoolConfig) -> None
Creates and opens the global connection pool. Raises RuntimeError if a pool already exists.
get_pool() -> ConnectionPool
Returns the active pool. Raises RuntimeError if the pool has not been created.
close_pool() -> None
Closes the pool and resets state. Safe to call if already closed or never created.
Example: Plain usage (no FastAPI, no OTEL)
from raccoontools_db.pool import PoolConfig, create_pool, get_pool, close_pool
config = PoolConfig(conn_info="postgresql://user:pass@localhost:5432/mydb")
create_pool(config)
pool = get_pool()
with pool.connection() as conn:
with conn.cursor() as cur:
cur.execute("SELECT 1")
print(cur.fetchone())
close_pool()
Example: With OpenTelemetry
from raccoontools_db.pool import PoolConfig, create_pool, get_pool, close_pool
config = PoolConfig(
conn_info="postgresql://user:pass@localhost:5432/mydb",
use_otel=True,
otel_service_name="my-service",
otel_exporter_endpoint="http://localhost:4318",
)
create_pool(config)
pool = get_pool()
# Use pool as normal — logging is handled via OTEL tracing
FastAPI Integration (raccoontools_db.fastapi)
create_lifespan(config: PoolConfig)
An async context manager that ties the pool lifecycle to FastAPI's startup/shutdown.
Example: With FastAPI
from fastapi import FastAPI
from raccoontools_db.fastapi import create_lifespan
from raccoontools_db.pool import PoolConfig, get_pool
config = PoolConfig(conn_info="postgresql://user:pass@localhost:5432/mydb")
app = FastAPI(lifespan=create_lifespan(config))
@app.get("/health")
def health():
pool = get_pool()
with pool.connection() as conn:
conn.execute("SELECT 1")
return {"status": "ok"}
Example: With FastAPI + OpenTelemetry
from fastapi import FastAPI
from raccoontools_db.fastapi import create_lifespan
from raccoontools_db.pool import PoolConfig, get_pool
config = PoolConfig(
conn_info="postgresql://user:pass@localhost:5432/mydb",
use_otel=True,
otel_service_name="my-service",
otel_exporter_endpoint="http://localhost:4318",
)
app = FastAPI(lifespan=create_lifespan(config))
Changelog
Metadata
Release files for raccoontools-db 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| raccoontools_db-1.1.0.tar.gz | 8.5 kB | Without provenance | Details for raccoontools_db-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| raccoontools_db-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for raccoontools_db-1.1.0-py3-none-any.whl |
Total release size: 15.3 kB
Release files / raccoontools_db-1.1.0.tar.gz
| Download URL | raccoontools_db-1.1.0.tar.gz |
|---|---|
| Size | 8.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aae4a2d5df0819855115b0c0f08e3ba6043a7da0c26a3364d688378a43b1a535
|
|
BLAKE2b-256 checksum How to use checksums |
2e4b4836c8e94055a4467b6081d3cc388181cd72021881c5337761239b5f19cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Release files / raccoontools_db-1.1.0-py3-none-any.whl
| Download URL | raccoontools_db-1.1.0-py3-none-any.whl |
|---|---|
| Size | 6.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b2b4a2ef81ea5350333750f0c830d6b589b989f251826bfa240da64776ca16be
|
|
BLAKE2b-256 checksum How to use checksums |
490bef34422c7ccee35792bb37017824cef02c09aa68986c7386b501c57f5293
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Security for raccoontools-db 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.