Skip to main content

Raccoon Tools DB

A managed PostgreSQL connection pool (via psycopg 3) with opt-in FastAPI and OpenTelemetry integrations.

vet OSS Components

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 in repr(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 when use_otel=True).
  • otel_exporter_endpoint (str): OTLP exporter endpoint (required when use_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)

Source distribution for raccoontools-db 1.1.0
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)

Table of built distributions (wheels) for raccoontools-db 1.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page