Short answer: use

PREFECT_SERVER_DATABASE_*

for both the API and the background services. There is no

PREFECT_API_DATABASE_*

setting in Prefect 3.x for server-side database configuration. Details: - Any container/process that runs the Prefect Server (the API service and each background service instance) should receive the same

PREFECT_SERVER_DATABASE_*

settings so they all point to the same Postgres database. - Common options you can set: -

PREFECT_SERVER_DATABASE_CONNECTION_URL

(recommended single URL) - Or the component fields if you prefer: -

PREFECT_SERVER_DATABASE_DRIVER

(e.g.,

postgresql+asyncpg

) -

PREFECT_SERVER_DATABASE_HOST

-

PREFECT_SERVER_DATABASE_PORT

-

PREFECT_SERVER_DATABASE_USER

-

PREFECT_SERVER_DATABASE_PASSWORD

-

PREFECT_SERVER_DATABASE_NAME

- Optional SQLAlchemy tuning/TLS (e.g.,

PREFECT_SERVER_DATABASE_SQLALCHEMY_ECHO

,

PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CA_FILE

, etc.) Example env snippet:

PREFECT_SERVER_DATABASE_CONNECTION_URL=<postgresql+asyncpg://prefect:prefect@my-postgres:5432/prefect>
# or:
PREFECT_SERVER_DATABASE_DRIVER=postgresql+asyncpg
PREFECT_SERVER_DATABASE_HOST=my-postgres
PREFECT_SERVER_DATABASE_PORT=5432
PREFECT_SERVER_DATABASE_USER=prefect
PREFECT_SERVER_DATABASE_PASSWORD=prefect
PREFECT_SERVER_DATABASE_NAME=prefect

Docs for reference: - Self-hosted guide: Scalable self-hosted Prefect - Settings reference: Settings reference (search for “ServerDatabaseSettings” and

PREFECT_SERVER_DATABASE_*

) If you share how you’re deploying (Docker Compose, Kubernetes/Helm), I can tailor an example manifest with the right env vars wired into both the API and services.

Short version - Background services are Prefect Server’s periodic/async control-plane workers (not flow runners). They handle things like scheduling, triggers, late-run marking, cancellations cleanup, repossessing stuck runs, concurrency limits, pause expirations, and event logging/persisting. - Yes, you can (and should) run multiple replicas for high availability and throughput. They are stateless and coordinate via the database to avoid duplicate work, so horizontal scaling is safe. What they do (high level) - Scheduler: materializes flow runs from deployment schedules. - Triggers engine: evaluates trigger conditions and starts runs. - Late runs: marks overdue runs. - Cancellation cleanup: finalizes cancellations that didn’t complete cleanly. - Repossessor: recovers/marks stuck runs so resources/concurrency slots are freed. - Concurrency limits: enforces configured concurrency policies. - Pause expirations: expires paused runs at configured times. - Event logger/persister: collects and persists events for the UI and auditing. - Task run recorder: ensures final task/flow state and related records are durably written. HA and scaling guidance - Run 2+ replicas of the background services process; they coordinate through the DB and are designed to be idempotent, so multiple replicas won’t double-execute work. - Use the same database settings for all replicas (and the API) so they share state. - Use managed Postgres or a highly available Postgres setup; services depend on it. - You can scale replicas up to improve scheduling/trigger evaluation throughput and reduce tail latencies. - Ensure clocks are roughly in sync across nodes (helps with “late” detection). Config pointers - Use the same

PREFECT_SERVER_DATABASE_*

env vars on all background-service replicas and API replicas. - Also set

PREFECT_API_URL

(and

PREFECT_API_AUTH_STRING

if auth is enabled) so services can reach the API. Docs - Scalable self-hosted guide: Scalable self-hosted Prefect - Settings reference (search for “ServerServices” and “ServerDatabaseSettings”): Settings reference If you share whether you’re on Kubernetes or Docker Compose, I can sketch a concrete deployment with multiple replicas and the right env vars.