

Managing thousands of concurrent client connections has long been a core challenge for MySQL database administrators. As active connections grow, the database server must provision and manage more operating system threads, assign thread stacks, and coordinate process scheduling. Under intense concurrency, this model triggers heightened context switching, memory consumption, and lock contention.
Historically, Oracle restricted the native Thread Pool plugin to MySQL Enterprise Edition. Community Edition users who required native thread management had to use third-party distributions such as Percona Server for MySQL or MariaDB, or deploy external connection proxies like ProxySQL.
With the release of MySQL 26.7.0, Oracle introduced the native Thread Pool plugin into MySQL Community Edition. Community deployments can now leverage server-side thread management natively without an Enterprise license.
This addition is particularly relevant for high-traffic Online Transaction Processing (OLTP) environments where applications run high volumes of short-lived transactions. However, moving to a thread-pooled model fundamentally shifts how queries are scheduled and executed.
In this post, we examine the internal mechanics of the MySQL Thread Pool plugin, walk through its setup and monitoring in MySQL 26.7 Community Edition, and analyze benchmark results comparing it against the traditional connection model using Sysbench.
1. Understanding the One-Thread-Per-Connection Model
By default, MySQL uses a one-thread-per-connection architecture.
Whenever a client establishes a connection, MySQL assigns a dedicated server thread to that connection. The thread handles statements submitted by that client and remains associated with the connection until it disconnects.
For example, consider a MySQL server receiving 1,000 simultaneous client connections.
- 100 client connections require approximately 100 connection-handling threads.
- 500 client connections require approximately 500 connection-handling threads.
- 1,000 client connections require approximately 1,000 connection-handling threads.
Each connection thread consumes resources, including thread-stack memory and other thread-related structures. The operating system must also schedule runnable threads.
This architecture works well when the number of concurrent connections is relatively small. However, under heavy concurrency, it can introduce several challenges:
- Memory Footprint: Every connection thread reserves memory for its thread stack (thread_stack) along with connection-specific buffers (such as read_buffer_size, sort_buffer_size, and temporary memory allocations).
- Operating System Context Switching: When thousands of threads compete for CPU execution time, the OS kernel expends significant CPU cycles swapping registers and thread states.
- CPU Scheduling Delays: A higher run-queue length in the OS scheduler leads to CPU thrashing and variable query execution times.
- Internal Engine Contention: Too many simultaneous transactions executing inside the storage engine increase contention around InnoDB row locks, mutexes, and read-view structures.
The important distinction is that the number of connected clients does not necessarily represent the number of queries that need to execute simultaneously.
For example, a server might have 2,000 connected clients, but only 50 of them may be actively executing SQL statements at a particular moment. The remaining connections may be idle or waiting for application requests.
The one-thread-per-connection model maintains a separate connection thread even when that connection is not actively executing a query.
This is where thread pooling becomes useful.
2. What Is MySQL Thread Pool?
MySQL Thread Pool is a server-side plugin that changes how MySQL schedules and executes statements from client connections.
Instead of maintaining a separate execution thread for every client connection, the Thread Pool plugin organizes connections into a configurable number of thread groups.
Each thread group manages a set of client connections. Worker threads within these groups execute statements submitted by those connections.
The architecture separates two important concepts:
- Client connections: The number of applications and clients connected to MySQL.
- Execution threads: The operating system threads available to process SQL statements.
For example, consider a MySQL server with 1,000 connected clients and 8 thread groups.
1,000 Connected Clients
│
▼
Thread Pool Plugin
(e.g., 8 Thread Groups)
│
▼
Worker Threads (~Small, Scaled Pool)
Executing Queries Against InnoDBThe main objective is to control execution concurrency and reduce unnecessary thread-management overhead.
Important: Thread pooling does not impose a limit on the number of client connections. It changes how statements from those connections are scheduled and executed. The maximum number of connections is still governed by MySQL connection limits and available system resources.
3. How MySQL Thread Pool Works Internally
To understand the benefits of thread pooling, let's walk through what happens when a client connects and submits a SQL statement.
Step 1: Client connections are assigned to thread groups
When a client establishes a connection, the Thread Pool plugin assigns that connection to a thread group.
Connections are assigned to groups in a round-robin fashion.
The number of thread groups is controlled by:
thread_pool_sizeEach group manages its own set of connections and scheduling activities.
Step 2: Listener threads monitor incoming requests
Each thread group has a listener mechanism responsible for detecting incoming requests from its assigned connections.
When a client sends a SQL query:
- The listener detects the incoming packet and marks the connection as ready for execution.
- If a worker thread is free and no backlog exists, the statement can be executed immediately.
- If all workers are occupied, the statement moves into a priority queue.
By default, listener tasks can be executed dynamically by worker threads. If thread_pool_dedicated_listeners is enabled, a dedicated thread is assigned strictly to network listening.
Step 3: Statements enter priority queues
One of the important features of MySQL Thread Pool is its priority-based scheduling mechanism.
Each thread group maintains two statement queues.
- High Priority Queue
- Low Priority Queue
High-priority queue
- This queue contains statements associated with transactions that have already started.
- Prioritizing these statements helps existing transactions make progress and complete. This can also help release locks held by those transactions.
Low-priority queue
This queue contains the initial statements of transactions that have not yet started, including new transactions.
By separating these workloads, MySQL can prioritize the continuation of existing transactions rather than allowing new transactions to continuously compete for execution resources.
Statements waiting in the low-priority queue are not necessarily left there indefinitely.
To prevent new queries from starving indefinitely in the low-priority queue under sustained load, the system uses a promotion timer:
thread_pool_prio_kickup_timerStep 4: Worker threads execute statements
- Worker threads retrieve statements from the queues and execute them.
- The Thread Pool generally prioritizes statements from the high-priority queue, subject to its scheduling and fairness mechanisms.
- Once a worker finishes executing a statement, it can return to the scheduling mechanism and process another statement.
- The same worker can therefore serve different client connections over time.
- This reuse of execution threads reduces the need to create and manage a separate operating system thread for every connected client.
Step 5: Stall detection and additional worker creation
If a query blocks on an external disk read, an uncommitted row lock, or a long-running join, the assigned worker thread stalls. If every worker thread in a group becomes blocked, other non-blocking queries assigned to that group could get stuck waiting in the queue.
To avoid this situation, MySQL monitors worker activity.
The relevant configuration parameter is:
thread_pool_stall_limit- This parameter determines how long an executing statement can run before the thread pool considers it stalled.
- When a statement is considered stalled, the thread pool can allow another worker to start executing statements in that group.
- Additional workers can be created when necessary.
Important: Stall detection does not mean that MySQL cancels or terminates the original statement. The original statement can continue executing. Stall detection allows the thread group to make progress by scheduling additional work.
4. MySQL Thread Pool Architecture
The following simplified diagram illustrates how client connections are managed through thread groups and worker threads.
5. Installing and Enabling Thread Pool in MySQL 26.7 Community Edition
In MySQL 26.7 Community Edition, the Thread Pool is distributed as a plugin library. It can be loaded during server initialization.
Step 1: Verify the Plugin Library Location
Identify the server's plugin directory:
SHOW VARIABLES LIKE 'plugin_dir';On Linux systems, verify that the thread_pool.so shared library exists inside that target path:
ls -l /usr/lib/mysql/plugin/thread_pool.soStep 2: Configure my.cnf
To ensure the plugin loads at startup, add the plugin-load-add directive under the [mysqld] section in your configuration file (/etc/mysql/my.cnf or /etc/my.cnf):
mysqld]
plugin-load-add=thread_pool.soRestart the MySQL daemon:
systemctl restart mysqlStep 3: Confirm Plugin State
Verify that the Thread Pool has loaded and reports an ACTIVE status:
SELECT PLUGIN_NAME, PLUGIN_STATUS
FROM INFORMATION_SCHEMA.PLUGINS
WHERE PLUGIN_NAME = 'thread_pool';+-------------+---------------+
| PLUGIN_NAME | PLUGIN_STATUS |
+-------------+---------------+
| thread_pool | ACTIVE |
+-------------+---------------+
1 row in set (0.001 sec)The ACTIVE status confirms that the plugin has been successfully loaded and is active.
Step 4: Review Thread Pool Variables
Inspect the runtime variables initialized by the plugin:
SHOW GLOBAL VARIABLES LIKE 'thread%';Example output from our environment:
+----------------------------------------+--------------------+
| Variable_name | Value |
+----------------------------------------+--------------------+
| thread_cache_size | 100 |
| thread_handling | loaded-dynamically |
| thread_pool_algorithm | 1 |
| thread_pool_connection_report_interval | 120 |
| thread_pool_dedicated_listeners | OFF |
| thread_pool_high_priority_connection | 0 |
| thread_pool_longrun_trx_limit | 2000 |
| thread_pool_max_active_query_threads | 0 |
| thread_pool_max_transactions_limit | 128 |
| thread_pool_max_unused_threads | 32 |
| thread_pool_prio_kickup_timer | 1000 |
| thread_pool_query_threads_per_group | 2 |
| thread_pool_size | 4 |
| thread_pool_stall_limit | 6 |
| thread_pool_transaction_delay | 0 |
| thread_stack | 1048576 |
+----------------------------------------+--------------------+
16 rows in set (0.002 sec)Key Parameters to Understand
- thread_pool_size: Sets the number of thread groups. Typically configured between 1 and 2x the number of available CPU cores. This variable is static and must be set in the configuration file before server startup.
- thread_pool_stall_limit: Determines the threshold before an executing query is classified as stalled. The unit is roughly 10 milliseconds (e.g., a setting of 6 equals ~60ms).
- thread_pool_prio_kickup_timer: The time (in milliseconds) a statement can sit in the low-priority queue before being moved to the high-priority queue.
- thread_pool_max_transactions_limit: Sets a ceiling on the concurrent transactions handled by the Thread Pool.
6. Monitoring MySQL Thread Pool
After enabling thread pooling, administrators should monitor whether the plugin is managing execution threads as expected.
MySQL 26.7 exposes dedicated Performance Schema tables for monitoring Thread Pool activity.
The important tables are:
These tables help DBAs understand connection distribution, worker activity, queue depths, and stalled statements.
Inspecting Thread Group Activity
To see how connections and worker threads are distributed across thread groups, run:
SELECT
TP_GROUP_ID AS grp,
CONNECTION_COUNT AS conns,
THREAD_COUNT AS total_workers,
ACTIVE_THREAD_COUNT AS active_workers,
STALLED_THREAD_COUNT AS stalled_workers,
QUEUED_QUERIES AS high_prio_queue,
QUEUED_TRANSACTIONS AS low_prio_queue
FROM performance_schema.tp_thread_group_state
ORDER BY TP_GROUP_ID;The important columns are:
- CONNECTION_COUNT: Number of client connections assigned to the group.
- THREAD_COUNT: Total number of threads started in the group.
- ACTIVE_THREAD_COUNT: Number of threads actively executing statements.
- STALLED_THREAD_COUNT: Number of statements currently considered stalled.
- QUEUED_QUERIES: Number of statements waiting in the high-priority queue.
- QUEUED_TRANSACTIONS: Number of initial transaction statements waiting in the low-priority queue.
Live observation under write contention (128 concurrent threads)
During our 128-thread oltp_read_write benchmark, we captured the following snapshot from tp_thread_group_state:
+-----+-------+---------------+----------------+-----------------+-----------------+----------------+
| grp | conns | total_workers | active_workers | stalled_workers | high_prio_queue | low_prio_queue |
+-----+-------+---------------+----------------+-----------------+-----------------+----------------+
| 0 | 17 | 33 | 16 | 4 | 0 | 0 |
| 1 | 16 | 30 | 15 | 5 | 0 | 0 |
| 2 | 16 | 32 | 16 | 5 | 0 | 0 |
| 3 | 16 | 30 | 15 | 6 | 0 | 0 |
| 4 | 16 | 34 | 16 | 1 | 0 | 0 |
| 5 | 16 | 34 | 15 | 6 | 0 | 0 |
| 6 | 16 | 35 | 16 | 3 | 0 | 0 |
| 7 | 16 | 36 | 14 | 2 | 0 | 0 |
+-----+-------+---------------+----------------+-----------------+-----------------+----------------+This live query shows:
- Connections are balanced across the 8 configured groups (16–17 connections per group).
- Under write contention, statements periodically hit the stall timer, prompting the Thread Pool to provision additional workers to keep processing other pending traffic.
- The queues remained at 0, confirming worker capacity was sufficient to process statements without queuing delays at this concurrency level.
7. Benchmarking Thread Pool vs. One-Thread-Per-Connection
To measure the operational trade-offs, we ran comparative tests between:
- Test 1: Default one-thread-per-connection model.
- Test 2: Thread Pool model enabled (thread_pool_size = 8).e
Environment & Test Configuration
- Workload: Sysbench oltp_read_write
- Dataset: 10 tables, 250,000 rows per table
- Duration: 45 seconds per concurrency level
- Concurrency Steps: 8, 32, 128, 256, 512, 1024, and 2048 threads
Execution Script
The following bash script executed the runs, capturing OS thread counts via ps, memory footprints via Resident Set Size (RSS), and kernel context switches via vmstat:
MODE="tp_size_8" # baseline, tp_size_4, tp_size_8
OUTDIR="/var/tmp/benchmark_results/
"mkdir-p"OUTDIR"
for THREADS in 8 32 128 256 512 1024 2048; do
echo ">>> Running ${MODE} at ${THREADS} threads..."
(
sleep 15
echo "--- OS Threads ---" \
> "${OUTDIR}/sys_${THREADS}th.log"
ps -eLf | grep '[m]ysqld' | wc -l \
>> "${OUTDIR}/sys_${THREADS}th.log"
echo "--- Memory (RSS KB) ---" \
>> "${OUTDIR}/sys_${THREADS}th.log"
ps -o pid,rss,vsz,comm -C mysqld \
>> "${OUTDIR}/sys_${THREADS}th.log"
echo "--- vmstat (5 samples) ---" \
>> "${OUTDIR}/sys_${THREADS}th.log"
vmstat 1 5 \
>> "${OUTDIR}/sys_${THREADS}th.log"
) &
sysbench oltp_read_write \
--db-driver=mysql \
--mysql-host=127.0.0.1 \
--mysql-port=3306 \
--mysql-user=mydbops \
--mysql-password=’****’ \
--mysql-db=sbtest \
--tables=10 \
--table-size=250000 \
--threads="${THREADS}" \
--time=45 \
--percentile=99 \
run | tee "${OUTDIR}/bench_${THREADS}th.log"
sleep 5
doneThe script samples OS threads and memory 15 seconds after each test begins. The vmstat output provides system-level information, including context-switch activity.
For a controlled comparison, the same MySQL configuration, dataset, hardware, buffer-pool settings, and benchmark preparation should be used in both tests. Run multiple repetitions and compare the median results.
Also ensure that the background monitoring process has completed before starting the next benchmark iteration.
8. Benchmark Results
With Thread Pool enabled
Threads | TPS | QPS | Avg(ms) | P99(ms) | Max(ms) | OS_Threads | RSS(MB) | CtxSw/s
---------|------------|------------|----------|----------|-----------|------------|------------|---------
8 | 684.74 | 13694.78 | 11.68 | 41.10 | 112.19 | 290 | 1611 | 517
32 | 1104.31 | 22086.28 | 28.96 | 102.97 | 183.23 | 311 | 1636 | 517
128 | 1268.93 | 25378.56 | 100.64 | 253.35 | 507.69 | 311 | 1737 | 517
256 | 1220.61 | 24412.13 | 208.87 | 559.50 | 1230.58 | 352 | 1964 | 518
512 | 1222.44 | 24448.90 | 415.62 | 773.68 | 1432.85 | 352 | 2731 | 518
1024 | 1176.52 | 23530.35 | 855.88 | 1280.93 | 2319.00 | 427 | 4310 | 518
2048 | 638.17 | 12763.50 | 3083.76 | 7754.26 | 11609.84 | 479 | 6595 | 518 Without Thread Pool
Threads | TPS | QPS | Avg(ms) | P99(ms) | Max(ms) | OS_Threads | RSS(MB) | CtxSw/s
---------|------------|------------|----------|----------|-----------|------------|------------|---------
8 | 1199.61 | 23992.25 | 6.67 | 20.00 | 109.56 | 137 | 12466 | 422
32 | 1441.39 | 28827.90 | 22.19 | 112.67 | 148.32 | 137 | 12470 | 422
128 | 1669.46 | 33389.18 | 76.54 | 200.47 | 401.57 | 165 | 12477 | 422
256 | 1704.19 | 34083.87 | 149.76 | 404.61 | 759.33 | 293 | 12488 | 422
512 | 1642.74 | 32854.79 | 309.97 | 846.57 | 1501.67 | 549 | 12500 | 422
1024 | 1543.60 | 30872.40 | 654.67 | 1836.24 | 3567.97 | 1061 | 12530 | 422
2048 | 893.87 | 17877.43 | 2216.56 | 11317.84 | 21680.88 | 2085 | 12521 | 422 9. Analyzing the Benchmark Results
The benchmark data highlights key operational differences between the two architectures:
1. Operating System Thread Reduction
At 2,048 client connections:
- Without Thread Pool: 2,085 operating system threads
- With Thread Pool: 479 operating system threads
The Thread Pool achieved a ~77% reduction in OS thread count. Instead of spawning a dedicated thread for every incoming connection, the engine routed traffic through controlled worker pools. This reduction limits OS scheduler saturation under high connection volumes.
2. Memory Consumption (Resident Set Size)
At 2,048 concurrency:
- Without Thread Pool: 12,521 MB RSS
- With Thread Pool: 6,595 MB RSS
This is an approximate 47% reduction in resident memory usage.
Caveat: Total RSS encompasses InnoDB buffer pool structures, session buffers, dictionary caches, and execution stacks. While lower thread allocations account for direct stack savings, differing cache footprints and memory management patterns during execution also influence this metric.
3. Transaction Throughput (TPS) Realities
A common misconception is that enabling a thread pool automatically improves transaction throughput. In this benchmark, the default one-thread-per-connection model yielded higher TPS at all tested concurrency points:
- At 128 threads: Baseline reached 1,669.46 TPS vs. 1,268.93 TPS with Thread Pool.
- At 1,024 threads: Baseline reached 1,543.60 TPS vs. 1,176.52 TPS with Thread Pool.
- At 2,048 threads: Baseline reached 893.87 TPS vs. 638.17 TPS with Thread Pool.
Why did this occur?
Sysbench clients generate a continuous, uniform stream of queries without client think time. In this specific scenario, every connection actively demands execution time. By limiting execution via thread groups, queries must queue through listener and worker scheduling logic, adding scheduling latency compared to direct thread execution.
The Thread Pool's strength lies in handling connection-heavy environments with intermittent query activity (e.g., thousands of idle application connections), protecting database stability rather than maximizing raw synthetic throughput.
Advantages and Disadvantages
Advantages
- Lower OS Thread Overhead: Reusing worker threads across client sessions limits thread explosion and reduces context-switching load on the kernel.
- Predictable Memory Footprint: By capping the total number of concurrently executing threads, memory utilization remains controlled when connection numbers peak.
- Execution Concurrency Control: Regulates statement contention against CPU cores and internal InnoDB structures.
- Transaction-Aware Scheduling: Prioritizes in-flight transactions in high-priority queues to release locks and minimize transaction duration.
- Stall Mitigation: Detects blocking queries and spins up new workers to keep the thread group responsive.
Disadvantages
- Internal Scheduling Latency: Query statements pass through listener detection, priority evaluation, and queue coordination, which introduces overhead under low-to-moderate loads.
- Tuning Sensitivity: Suboptimal configurations of thread_pool_size or thread_pool_stall_limit can lead to premature thread spawning or excessive queue waits.
- Complex Analytical Workloads: Queries with variable, long execution times can trigger stall timers, driving worker thread counts up and offsetting pooling advantages.
Conclusion
The inclusion of the Thread Pool plugin in MySQL 26.7 Community Edition provides open-source administrators with a built-in tool for managing high client concurrency without third-party builds or external licenses.
However, the benchmark results show that Thread Pool is a concurrency and stability management tool, not an automatic performance booster. If your workload consists of a controlled connection count where all sessions are continuously running queries, the default one-thread-per-connection model may deliver higher raw throughput.
Conversely, if your database architecture handles thousands of persistent microservice connections, runs short-lived OLTP transactions, and faces memory or thread exhaustion, the Thread Pool can help stabilize performance.
Before deploying the Thread Pool to production, benchmark your specific query workload using tools like Sysbench to find the optimal balance among thread count, memory footprint, and query latency.
Call to Action (CTA)
Need Help Optimizing MySQL Concurrency and Architecture?
Scaling MySQL under high connection concurrency requires balancing thread parameters, memory limits, and storage engine dynamics. Whether you are planning an upgrade to newer MySQL releases, tuning production workloads, or troubleshooting contention bottlenecks, our database experts are here to help.
Explore our MySQL Consulting Services or learn more about Database Performance Tuning with Mydbops.

.avif)
.avif)

.avif)
