Connection pooling

This page is an outline. What is here is accurate, but it is not yet the whole story — each section ends with a note on what is still to be written. For anything it does not answer, DEPLOYMENT.md and USING-MCP.md in the repository are the complete references.

Set DAO_POOL=YES in the config to give each tool call its own factory instead of serialising every call behind one connection. It is on by default for a config created in the console, because the deployed shape is several agents calling at once.

A pooled factory keeps its connection and its already-parsed statements — which is why this pools factories rather than connections.

Sizing

Each key lives in the config and can be overridden where the code runs by an environment variable of the same name, without regenerating.

Key	Meaning
`DAO_POOL_MAX_SIZE`	Ceiling. Also your effective concurrency limit.
`DAO_POOL_MIN_IDLE`	How many stay connected when idle.
`DAO_POOL_MAX_WAIT_MS`	How long a call waits for a free factory before “Server busy”.
`DAO_POOL_IDLE_TIMEOUT_MS`	How long an idle factory survives before eviction.
`DAO_POOL_ON_RETURN`	`COMMIT` or `ROLLBACK` when a call returns a factory.

Size the maximum against the server’s SESSIONS and OPEN_CURSORS, not against how many CPUs you have. Each factory in the pool holds one Oracle session and the cursors of every DAO it has used. If you run several generated servers against one database, it is the total across them that has to fit.

One factory kept warm is the console default. With a pool that starts empty the first call of the day pays connection setup and statement parsing — and that call is the one most likely to be someone trying the server out. More than one costs a held session for no benefit until traffic arrives.

What it changes

Pooling moves when work is committed: the transaction ends when a caller finishes, not when the connection is released. That is the one behavioural difference to think about before switching it on over existing PL/SQL — see Commit handling in called procedures.

Watching it

A pooled server logs a POOL-STATS line every 15 seconds, which the Runtime page reads. The same numbers are Prometheus gauges under mcpdbwizard_mcp_pool_* if you have metrics on.

Server busy: all database connections are in use means the pool is at its ceiling — load, not a fault. Raise DAO_POOL_MAX_SIZE if the database can carry it, or let clients retry.

To write. Worked sizing for a given SESSIONS; what to watch to know the ceiling is right; interaction with Oracle’s own shared-server and DRCP pooling.