Skip to content

Architecture · By Rivtor · Updated

Size Uvicorn workers against memory and database connections

Choose Uvicorn worker count from measured per-process memory, CPU workload and total database connections. Each process loads application state and may own a pool. Increasing workers blindly can exhaust memory or PostgreSQL capacity instead of improving request handling.

See the Rivtor deployment workflow →

Count resources per process

Each worker has its own Python interpreter and application state. Large models, caches and imported libraries can be duplicated across processes. A deployment that fits one worker may exceed the memory limit after several workers start.

The application’s database engine commonly exists per process too. An illustrative four-worker app with up to five connections per worker can request twenty connections before any background worker or migration runs. This is budget arithmetic, not a recommended production configuration.

Distinguish async requests from CPU work

Async I/O can let a worker handle concurrent waits, but blocking code inside an async path can still stop that event loop from progressing. CPU-intensive work may need a separate process or background job, depending on the workload. Adding web workers is not a universal replacement for correcting a blocked request path.

Workload observationInvestigation
CPU saturatedCPU task, process count and background execution
Memory rises per workerImported state, caches and allocation
Requests wait for DBPool and transaction capacity
Long external callsBounded concurrency and upstream timeouts

Measure before increasing the count

Start with a deliberate small configuration in a representative test environment. Record idle memory, peak memory during expected concurrency, request latency and errors. Leave headroom for startup, releases and native allocations.

Use the pinned Uvicorn/process-manager documentation for the actual supported command. Reload mode and production multi-worker mode are different workflows. Avoid deprecated worker-class instructions copied from an old tutorial without checking the installed server versions.

Verify host and database fit

On Rivtor, review service commands and current plan resources. Count all application and background processes against the relevant limits. A process that starts successfully can still fail when several requests allocate buffers or execute queries at once.

Change one variable, repeat the same bounded workload and compare latency, memory and errors together. Keep the configuration that meets the workload within the capacity budget. Document the environment and observations rather than claiming that a CPU-count formula guarantees the best worker count everywhere.

References