Summary

What is the problem or use case, what are we trying to achieve?
The existing client session API has significant usability issues. Passing a session object to every related database operation is easy to overlook and is inconsistent with what users expect, especially in languages like Python that make extensive use of context managers. Both external and internal users often forget to include their session object in database operations, leading to unexpected behavior.

PyMongo implemented a new context-manager based API in PYTHON-4542.

Loosening the specification to allow similarly idiomatic session management for each driver's language will let users utilize client sessions in familiar ways that improve correctness.

Motivation

Who is the affected end user?

All users that utilize client sessions, especially in combination with the startTransaction API.

Who are the stakeholders?

How does this affect the end user?

Are they blocked? Are they annoyed? Are they confused?

Users of drivers that implement idiomatic session management will misuse sessions less often and have simpler, more correct code.   

How likely is it that this problem or use case will occur?

Main path? Edge case?

Most users of explicit sessions (and withTransaction) would benefit from better APIs.

If the problem does occur, what are the consequences and how severe are they?

Minor annoyance at a log message? Performance concern? Outage/unavailability? Failover can't complete?

We often see users forget to pass their explicit session to an operation, especially when using withTransaction. This leads to behavior inconsistent with what they expect, and is difficult to debug when looking at large blocks of operations.

Is this issue urgent?

Does this ticket have a required timeline? What is it?

No. This gives drivers the option to implement idiomatic APIs if they choose to do so. 

Is this ticket required by a downstream team?

Needed by e.g. Atlas, Shell, Compass?

No.

Is this ticket only for tests?

Does this ticket have any functional impact, or is it just test improvements?

Functional improvements.

Acceptance Criteria

What specific requirements must be met to consider the design phase complete?

N/A.