Workers vs. requests in Azure SQL Database

We now explicitly define ‘requests’ and ‘workers’ in the Azure SQL Database documentation, and we’ve cleaned up multiple places where we used to equate the two terms. In this post, I share the history of the two terms when it comes to Azure SQL Database, why the two were ever equated, and why things like this are tricky to change.

What we changed

The documentation for Azure SQL Database previously contained some statements which equate workers and requests. Notice that this heading equates workers and requests, but the paragraph talks only about worker limits:

Sessions and workers (requests)

The maximum numbers of sessions and workers are determined by the service tier and compute size. New requests are rejected when session or worker limits are reached, and clients receive an error message.

The documentation also has tables which explain resource limits by service tier and compute size. Those tables used to look like this:

What are workers and requests, anyway?

We made changes to clarify that there is no limit on requests. Instead, there is a worker limit. We also added information to help folks troubleshoot situations where they approach or hit worker limits.

1. We now define sessions, requests, and workers:

• A session represents a process connected to the database engine.
• A request is the logical representation of a query or batch. A request is issued by a client connected to a session. Over time, multiple requests may be issued on the same session.
• A worker thread, also known as a worker or thread, is a logical representation of an operating system thread. A request may have many workers when executed with a parallel query execution plan, or a single worker when executed with a serial (single threaded) execution plan. Workers are also required to support activities outside of requests: for example, a worker is required to process a login request as a session connects.

2. We’ve also cleaned up the tables: where tables used to read ‘workers (requests)’, they now simply read ‘workers’.

3. Finally, we added more troubleshooting steps for when the worker limit has been reached under Error 10928: Resource ID : 1. The request limit for the database is %d and has been reached.

Notice that this error message still uses the word ‘requests’ – keep reading to learn why.

Why were workers and requests ever equated for Azure SQL Database?

We added a note below that error message which explains:

The initial offering of Azure SQL Database supported only single threaded queries. At that time, the number of requests was always equivalent to the number of workers. Error message 10928 in Azure SQL Database contains the wording “The request limit for the database is N and has been reached” for backwards compatibility purposes. The limit reached is actually the number of workers.

Why was this tricky to change?

When Azure SQL Database gained the ability to run parallel queries, requests and workers were no longer interchangeable at all: a single request may have a large amount of workers, depending on the query plan and level of parallelism.

But things like that error message are risky to change. One of the big requirements of providing a hosted database service is providing as much stability as possible while still innovating. Customers can, and do, sometimes code dependencies on the text of error messages (not just the number). Changing something even as simple as an error message can cause regressions.

The documentation attempted to strike a balance here: headings and tables were adjusted to say “workers” with the older term “(requests)” following in parentheses, while explanatory paragraphs talked only about the request limit.

Why we updated the docs further

Feedback came in over the last few months that the documentation wasn’t striking the balance as intended: this was confusing. Based on that feedback, we made the changes above to clearly define the terms involved, explain and support folks hitting worker limits, and simplify the resource limits tables.

Thanks very much to Dimitri Furman for his help in working out these changes.