Connection Pooling
Sombra uses connection pooling to efficiently manage database connections and prevent unbounded connections to upstream databases. This approach maintains a pool of connections for each database endpoint and stores these pools in an LRU (Least Recently Used) cache.
Pooling is the biggest lever for how fast Sombra processes DSRs against a database. For recommended starting values, how to verify pooling is on, and how pooling interacts with rate limits, see Database Integration Throughput.
To enable connection pooling, you must set the environment variable ODBC_POOL_CACHE_SIZE based on the number of upstream database servers being scanned, plus some buffer to prevent cache misses.
The following environment variables allow you to configure the connection pooling behavior:
| Environment Variable | Description | Default | Required |
|---|---|---|---|
ODBC_POOL_CACHE_SIZE | Maximum size of LRU cache to store the connection pool per database | None | Yes |
ODBC_POOL_CACHE_TTL_MS | How long (in milliseconds) each connection pool lives in the LRU cache before it is closed and recreated on next use | 3600000 (1 hour) | No |
ODBC_QUERY_TIMEOUT_IN_SECONDS | Maximum time to wait for each ODBC query to execute before returning to the application | 60 seconds | No |
ODBC_CONNECTION_TIMEOUT_IN_SECONDS | Number of seconds to wait for a request on the connection to complete before returning to the application | 0 | No |
ODBC_LOGIN_TIMEOUT_IN_SECONDS | Number of seconds to wait for a login request to complete before returning to the application | 10 | No |
ODBC_CONNECTION_POOL_SIZE | Maximum number of open connections the pool will create | 100 | No |
ODBC_CONNECTION_INITIAL_POOL_SIZE | Initial number of connections created in the pool | 10 | No |
ODBC_CONNECTION_POOL_SIZE_INCREMENT | Number of additional connections to create when all of the pool's connections are in use | 10 | No |
REUSE_ODBC_CONNECTIONS | Whether or not to reuse an existing connection instead of creating a new one | true | No |
ODBC_CONNECTION_POOL_SIZE_SHRINK | Whether or not the number of connections should shrink to initialSize as they free up | true | No |
UV_THREADPOOL_SIZE | Number of Node.js (libuv) threadpool threads per Sombra process. Each in-flight ODBC call holds one thread until the database answers. | 16 (Sombra image) | No |
ODBC_MAX_CONCURRENT_OPERATIONS | Maximum native ODBC calls (connect, prepare, execute, close) running at once per Sombra process. Calls above the cap wait for a free slot. | UV_THREADPOOL_SIZE minus a quarter of the pool, keeping at least 2 threads free (12 of 16) | No |
Sombra keeps part of the libuv threadpool free so slow or hung database calls cannot block DNS lookups and other outbound HTTP calls. Each Sombra process runs at most ODBC_MAX_CONCURRENT_OPERATIONS native ODBC calls at once; calls above the cap wait for a free slot. By default, the cap is UV_THREADPOOL_SIZE minus one quarter of the pool, with at least 2 threads reserved (12 of 16). To increase database concurrency, raise UV_THREADPOOL_SIZE; for example, 128 threads gives a default cap of 96. Set ODBC_MAX_CONCURRENT_OPERATIONS directly only when you need a specific cap, and keep it below UV_THREADPOOL_SIZE. Sombra logs Limiting native ODBC calls to N of M libuv threadpool threads at startup.
For high-volume DSR processing, the configuration below is a good starting point. Redeploy Sombra after changing these values, check that your database's connection limits leave room for the larger pools, and confirm pooling is on with the checks in Database Integration Throughput.
UV_THREADPOOL_SIZE=128
ODBC_POOL_CACHE_SIZE=20
ODBC_CONNECTION_INITIAL_POOL_SIZE=20
ODBC_CONNECTION_POOL_SIZE=100
ODBC_CONNECTION_POOL_SIZE_INCREMENT=20
ODBC_CONNECTION_POOL_SIZE_SHRINK=false
ODBC_POOL_CACHE_TTL_MS=86400000