Config Parity with PyStator

This page defines the shared contract across pycharter and pystator for overlapping configuration surfaces.

Unified contract

For overlapping keys and sections, both services follow:

1. explicit CLI/runtime override (when command accepts one)
2. environment variable
3. .cfg value with the same env-style key name
4. package default/fallback

Environment values always win over .cfg.

Overlap matrix

Category	PyCharter key(s)	PyStator key(s)	Notes
API URL	PYCHARTER_API_URL	PYSTATOR_API_URL	Used by UI proxy defaults.
Database URL	PYCHARTER_DATABASE_URL	PYSTATOR_DATABASE_URL	Base SQLAlchemy URL for API/db/worker unless worker override is set.
Auth disable	PYCHARTER_AUTH_DISABLED	PYSTATOR_AUTH_DISABLED	Truthy disables auth.
Auth local users	PYCHARTER_AUTH_USERS	PYSTATOR_AUTH_USERS	JSON list payload semantics match.
Auth JWT secret	PYCHARTER_AUTH_JWT_SECRET	PYSTATOR_AUTH_JWT_SECRET	Signing secret for built-in auth mode.
External auth URL	PYCHARTER_AUTH_SERVICE_URL	PYSTATOR_AUTH_SERVICE_URL	Optional external auth integration.
UI theme	PYCHARTER_UI_THEME	PYSTATOR_UI_THEME	Same palette contract.
UI app name	PYCHARTER_UI_APP_NAME	PYSTATOR_UI_APP_NAME	Branding/display title.
Worker DB override	PYCHARTER_WORKER_DB_URL	PYSTATOR_WORKER_DB_URL	Worker can target a dedicated DB URL.
Worker poll interval	PYCHARTER_WORKER_POLL_INTERVAL_MS	PYSTATOR_WORKER_POLL_INTERVAL_MS	Milliseconds.
Worker concurrency	PYCHARTER_WORKER_CONCURRENCY	PYSTATOR_WORKER_CONCURRENCY	Integer >= 1.
Worker drain timeout	PYCHARTER_WORKER_DRAIN_TIMEOUT_S	PYSTATOR_WORKER_DRAIN_TIMEOUT_S	Seconds.
Worker max attempts	PYCHARTER_WORKER_MAX_ATTEMPTS	PYSTATOR_WORKER_MAX_ATTEMPTS	Retry ceiling.
Worker lease / heartbeat	PYCHARTER_WORKER_LEASE_SECONDS, PYCHARTER_WORKER_HEARTBEAT_SECONDS	PYSTATOR_WORKER_LEASE_SECONDS, PYSTATOR_WORKER_HEARTBEAT_SECONDS	Claim lease + heartbeat interval.
Worker retry base/max	PYCHARTER_WORKER_RETRY_BACKOFF_BASE_MS, PYCHARTER_WORKER_RETRY_BACKOFF_MAX_MS	PYSTATOR_WORKER_RETRY_BACKOFF_BASE_MS, PYSTATOR_WORKER_RETRY_BACKOFF_MAX_MS	Backoff shaping.
Worker metrics / health	PYCHARTER_WORKER_METRICS_ENABLED, PYCHARTER_WORKER_HEALTH_SERVER_*	PYSTATOR_WORKER_METRICS_ENABLED, PYSTATOR_WORKER_HEALTH_SERVER_*	Opt-in operability.
Worker NOTIFY	PYCHARTER_WORKER_NOTIFY_LISTENER_ENABLED, PYCHARTER_WORKER_NOTIFY_CHANNEL_PREFIX	PYSTATOR_WORKER_NOTIFY_LISTENER_ENABLED, PYSTATOR_WORKER_NOTIFY_CHANNEL_PREFIX	Postgres LISTEN wake-up.
Worker retention	PYCHARTER_WORKER_RETENTION_*	PYSTATOR_WORKER_RETENTION_*	Opt-in queue row sweeps.
DLQ enabled	PYCHARTER_WORKER_DLQ_ENABLED	PYSTATOR_WORKER_DLQ_ENABLED	Toggle DLQ writes.
DLQ DB URL	PYCHARTER_WORKER_DLQ_DATABASE_URL	PYSTATOR_WORKER_DLQ_DATABASE_URL	Optional dedicated DLQ DB URL.
DLQ table	PYCHARTER_WORKER_DLQ_TABLE_NAME	PYSTATOR_WORKER_DLQ_TABLE_NAME	Default dead_letter_queue.

DLQ fallback semantics

When DLQ is enabled and *_WORKER_DLQ_DATABASE_URL is unset, both packages now resolve DLQ storage against the worker DB URL, which itself falls back to the app database URL.