Operations and capacity planning

The defaults fit typical single-node deployments. Keep the pool settings unchanged unless DATABASE_BUSY occurs repeatedly or you add Web or Worker processes.

Default connection capacity

Item	Default
Web processes	`1`
Primary-database ceiling per Web process	`20` (pool `10` + temporary `10`)
Worker processes	`1`
Primary-database ceiling per Worker process	`10` (pool `5` + temporary `5`)
Workbook ceiling per process	`10`
Built-in PostgreSQL `max_connections`	`100`

With Workbook enabled, the conservative application peak is 51 connections:

Web 20 + Worker 10 + Workbook 20 + LISTEN/NOTIFY 1 = 51

The PostgreSQL ceiling of 100 leaves sufficient headroom. POOL_SIZE is the number of retained connections, not the connection ceiling; add MAX_OVERFLOW to get that ceiling.

When DATABASE_BUSY occurs

DATABASE_BUSY means AskTable temporarily could not acquire a database connection or PostgreSQL reached its connection limit. The page retries automatically and offers a manual Retry action if the database remains busy. If the error keeps returning:

Check logs to determine whether Web requests or background refreshes are affected.
For refresh contention, first reduce AT_WORKER_MAX_JOBS.
Do not enlarge pools when PostgreSQL already reports exhausted connections.
Increase only the affected Web or Worker pool, and only after confirming PostgreSQL has headroom and the local pool is timing out.

When adding processes

Each additional Web process adds one Web primary-database pool, up to one Workbook pool, and one LISTEN/NOTIFY connection. Each additional Worker adds one Worker primary-database pool and up to one Workbook pool. Tune in this order: shorten transactions, reduce background concurrency, adjust the affected role pool, and raise the PostgreSQL limit last. Keep at least 10 connections available for migrations and troubleshooting.

Complete configuration reference

All settings are static environment variables. Restart the affected process after changing them.

Setting	Default	Description
`AT_SERVER_WORKERS`	`1`	Web processes; CLI `--workers` takes precedence
`AT_WEB_DB_POOL_SIZE`	`10`	Primary-database connections retained by each Web process
`AT_WEB_DB_MAX_OVERFLOW`	`10`	Temporary connections allowed when the Web pool is full
`AT_WORKER_NUM_PROCS`	`1`	Worker processes
`AT_WORKER_MAX_JOBS`	`10`	Maximum concurrent jobs in each Worker
`AT_WORKER_DB_POOL_SIZE`	`5`	Primary-database connections retained by each Worker process
`AT_WORKER_DB_MAX_OVERFLOW`	`5`	Temporary connections allowed when the Worker pool is full
`AT_DB_POOL_TIMEOUT`	`30`	Maximum seconds to wait for a primary-database connection
`AT_DB_POOL_RECYCLE`	`300`	Primary-database connection recycle interval in seconds
`WORKBOOK_PG_DSN`	Separate database in local PostgreSQL	Enables Workbook when non-empty; set it explicitly empty to disable
`AT_WORKBOOK_POOL_MIN`	`1`	Minimum Workbook connections retained by each process
`AT_WORKBOOK_POOL_MAX`	`10`	Maximum Workbook connections used by each process

Web and Worker pool capacity is configured separately; both roles share the wait and recycle settings. All pool values must be non-negative, and Workbook must satisfy 0 <= MIN <= MAX.

Calculate the exact connection ceiling

B is AT_WORKBOOK_POOL_MAX when Workbook is enabled and 0 otherwise.

Application connection ceiling =
  AT_SERVER_WORKERS
    × (AT_WEB_DB_POOL_SIZE + AT_WEB_DB_MAX_OVERFLOW + B + 1)
  + AT_WORKER_NUM_PROCS
    × (AT_WORKER_DB_POOL_SIZE + AT_WORKER_DB_MAX_OVERFLOW + B)

The application ceiling plus at least 10 operations connections must remain below PostgreSQL’s connections available to regular users. That number is max_connections minus reserved_connections and superuser_reserved_connections.

Inspect connection usage

Inspect PostgreSQL limits:

SHOW max_connections;
SHOW reserved_connections;
SHOW superuser_reserved_connections;

Inspect connection sources and long transactions:

SELECT application_name, state, count(*) AS connections,
       max(now() - xact_start) AS longest_transaction
FROM pg_stat_activity
WHERE datname IN ('asktable', 'asktable_workbook')
GROUP BY application_name, state
ORDER BY connections DESC;

Inspect container logs:

docker compose logs --since=30m asktable | grep -E 'DATABASE_BUSY|creating postgresql pool|refresh_table_task'
docker compose logs --since=30m asktable-pg

For external PostgreSQL, use the provider’s effective connection limit. AskTable does not change it automatically.

​Default connection capacity

​When DATABASE_BUSY occurs

​When adding processes

Default connection capacity

When DATABASE_BUSY occurs

When adding processes