Feedback: Node Shutdown

[jameslupolthrd]

Page: https://cockroachlabs.com/docs/v24.2/node-shutdown.html

What is the reason for your feedback?

[ ] Missing the information I need

[ ] Too complicated

[ ] Out of date

[ ] Something is broken

[ X] Other

Some parts of the drain documentation are confusing:

Clients are disconnected, and subsequent connection requests are sent to other nodes.

This makes it sound like a node can redirect client (SQL or DistSQL?) connections to other nodes, which I'd be surprised to hear is true. I suspect this means the load balancer will redirect new connections to a different node, but it's ambiguous due to the use of the passive voice.

2. SQL wait phase: New SQL client connections are no longer permitted, and any remaining SQL client connections are allowed to close or time out. This phase completes either when all SQL client connections are closed or the [maximum duration set by server.shutdown.connections.timeout](https://www.cockroachlabs.com/docs/stable/node-shutdown#server-shutdown-connections-timeout) is reached.

3. SQL drain phase: All active transactions and statements for which the node is a [gateway](https://www.cockroachlabs.com/docs/v24.2/architecture/life-of-a-distributed-transaction#gateway) are allowed to complete, and CockroachDB closes the SQL client connections immediately afterward. After this phase completes, CockroachDB closes all remaining SQL client connections to the node. This phase completes either when all transactions have been processed or the [maximum duration set by server.shutdown.transactions.timeout](https://www.cockroachlabs.com/docs/stable/node-shutdown#server-shutdown-transactions-timeout) is reached.

So in phase 2, we shut down client connections, and in phase 3 we wait for all active transactions and statements for which the node is a gateway to finish -- but an active transaction or statement requires a SQL client connection, which we removed in phase 2. This must either be ambiguous or inaccurate.

Additional details

Jira issue: DOC-11123