impl(spanner): promote from experimental and document multiplexed session support (#15366)

scotthart · web-flow · commit 12ddf77ba5a1 · 2025-08-11T16:37:59.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,14 @@ breaking changes in the upcoming 3.x release. This release is scheduled for
 
 ## v2.41.0 - TBD
 
+### [Spanner](/google/cloud/spanner/README.md)
+
+- [Multiplexed session](https://cloud.google.com/spanner/docs/sessions#multiplexed_sessions)
+support is now available. To enable Multiplexed sessions, add the
+`spanner::EnableMultiplexedSessionOption` to `Options` when calling
+`spanner::MakeConnection`. This enables Multiplexed sessions on all operations
+read-only, read-write, and partitioned.
+
 ## v2.40.0 - 2025-08
 
 ### New Libraries
diff --git a/google/cloud/spanner/integration_tests/client_integration_test.cc b/google/cloud/spanner/integration_tests/client_integration_test.cc
@@ -55,7 +55,7 @@ class ClientIntegrationTest : public spanner_testing::DatabaseIntegrationTest {
     auto session_mode =
         internal::GetEnv("GOOGLE_CLOUD_CPP_SPANNER_TESTING_SESSION_MODE");
     if (session_mode.has_value() && *session_mode == "multiplexed") {
-      options.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+      options.set<spanner::EnableMultiplexedSessionOption>({});
     }
     client_ = std::make_unique<Client>(
         MakeConnection(GetDatabase(), std::move(options)));
diff --git a/google/cloud/spanner/internal/connection_impl.cc b/google/cloud/spanner/internal/connection_impl.cc
@@ -529,7 +529,7 @@ Status ConnectionImpl::PrepareSession(SessionHolder& session,
                                       Session::Mode mode) {
   if (!session) {
     StatusOr<SessionHolder> session_or;
-    if (opts_.has<spanner_experimental::EnableMultiplexedSessionOption>()) {
+    if (opts_.has<spanner::EnableMultiplexedSessionOption>()) {
       session_or = session_pool_->Multiplexed(mode);
     } else {
       session_or = session_pool_->Allocate(mode);
diff --git a/google/cloud/spanner/internal/connection_impl_test.cc b/google/cloud/spanner/internal/connection_impl_test.cc
@@ -2169,8 +2169,7 @@ TEST(ConnectionImplTest, MultiplexedExecuteBatchDmlSuccess) {
       spanner::SqlStatement("UPDATE ..."),
   };
 
-  auto options =
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+  auto options = Options{}.set<spanner::EnableMultiplexedSessionOption>({});
   auto conn = MakeConnectionImpl(db, mock, options);
   internal::OptionsSpan span(MakeLimitedTimeOptions());
   auto txn = spanner::MakeReadWriteTransaction(
@@ -2945,8 +2944,7 @@ TEST(ConnectionImplTest, MutationCommitSuccess) {
             commit_timestamp, spanner::CommitStats{request.mutations_size()});
       });
 
-  auto options =
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+  auto options = Options{}.set<spanner::EnableMultiplexedSessionOption>({});
   auto conn = MakeConnectionImpl(db, mock, options);
   internal::OptionsSpan span(MakeLimitedTimeOptions());
   auto commit = conn->Commit({spanner::MakeReadWriteTransaction(), mutations,
@@ -3017,8 +3015,7 @@ TEST(ConnectionImplTest, MutationCommitRetryOnceSuccess) {
             commit_timestamp, spanner::CommitStats{original_mutations_size});
       });
 
-  auto options =
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+  auto options = Options{}.set<spanner::EnableMultiplexedSessionOption>({});
   auto conn = MakeConnectionImpl(db, mock, options);
   internal::OptionsSpan span(MakeLimitedTimeOptions());
   auto commit = conn->Commit({spanner::MakeReadWriteTransaction(), mutations,
@@ -3103,8 +3100,7 @@ TEST(ConnectionImplTest, MutationCommitRetryMoreThanOnceSuccess) {
             commit_timestamp, spanner::CommitStats{original_mutations_size});
       });
 
-  auto options =
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+  auto options = Options{}.set<spanner::EnableMultiplexedSessionOption>({});
   auto conn = MakeConnectionImpl(db, mock, options);
   internal::OptionsSpan span(MakeLimitedTimeOptions());
   auto commit = conn->Commit({spanner::MakeReadWriteTransaction(), mutations,
@@ -3188,8 +3184,7 @@ TEST(ConnectionImplTest, MultiplexedPrecommitUpdated) {
         });
   }
 
-  auto options =
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({});
+  auto options = Options{}.set<spanner::EnableMultiplexedSessionOption>({});
   auto conn = MakeConnectionImpl(db, mock, options);
   internal::OptionsSpan span(MakeLimitedTimeOptions());
   spanner::Transaction txn =
diff --git a/google/cloud/spanner/internal/session_pool.cc b/google/cloud/spanner/internal/session_pool.cc
@@ -94,7 +94,7 @@ SessionPool::SessionPool(spanner::Database db,
 
 void SessionPool::Initialize() {
   internal::OptionsSpan span(opts_);
-  if (opts_.has<spanner_experimental::EnableMultiplexedSessionOption>()) {
+  if (opts_.has<spanner::EnableMultiplexedSessionOption>()) {
     std::unique_lock<std::mutex> lk(mu_);
     CreateMultiplexedSession(lk);
     ScheduleMultiplexedBackgroundWork(multiplexed_session_background_interval_);
@@ -120,7 +120,7 @@ SessionPool::~SessionPool() {
   // they must not have successfully finished a call to `lock()` on the
   // `weak_ptr` to `this` they hold. Any in-progress or subsequent `lock()`
   // will now return `nullptr`, in which case no work is done.
-  if (opts_.has<spanner_experimental::EnableMultiplexedSessionOption>()) {
+  if (opts_.has<spanner::EnableMultiplexedSessionOption>()) {
     current_multiplexed_timer_.cancel();
   } else {
     current_timer_.cancel();
@@ -442,7 +442,7 @@ StatusOr<SessionHolder> SessionPool::Allocate(Session::Mode mode) {
 }
 
 StatusOr<SessionHolder> SessionPool::Multiplexed(Session::Mode mode) {
-  if (opts_.has<spanner_experimental::EnableMultiplexedSessionOption>()) {
+  if (opts_.has<spanner::EnableMultiplexedSessionOption>()) {
     std::unique_lock<std::mutex> lk(mu_);
     if (mode == Session::Mode::kDisassociated && multiplexed_session_.ok()) {
       // For disassociated sessions, only used in partitioned operations, we do
diff --git a/google/cloud/spanner/internal/session_pool_test.cc b/google/cloud/spanner/internal/session_pool_test.cc
@@ -164,7 +164,7 @@ TEST_F(SessionPoolTest, Multiplexed) {
   google::cloud::internal::AutomaticallyCreatedBackgroundThreads threads;
   auto pool = MakeTestSessionPool(
       db, {mock}, threads.cq(),
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+      Options{}.set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   ASSERT_STATUS_OK(session);
   EXPECT_EQ((*session)->session_name(), "multiplexed");
@@ -188,7 +188,7 @@ TEST_F(SessionPoolTest, MultiplexedAllocateRouteToLeader) {
       db, {mock}, threads.cq(),
       Options{}
           .set<spanner::RouteToLeaderOption>(true)
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   ASSERT_STATUS_OK(session);
   EXPECT_EQ((*session)->session_name(), "multiplexed");
@@ -241,7 +241,7 @@ TEST_F(SessionPoolTest, MultiplexedAllocateNoRouteToLeader) {
       db, {mock}, threads.cq(),
       Options{}
           .set<spanner::RouteToLeaderOption>(false)
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   ASSERT_STATUS_OK(session);
   EXPECT_EQ((*session)->session_name(), "multiplexed");
@@ -324,7 +324,7 @@ TEST_F(SessionPoolTest, MultiplexedCreateError) {
   google::cloud::internal::AutomaticallyCreatedBackgroundThreads threads;
   auto pool = MakeTestSessionPool(
       db, {mock}, threads.cq(),
-      Options{}.set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+      Options{}.set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   EXPECT_THAT(session,
               StatusIs(StatusCode::kInternal, HasSubstr("init failure")));
@@ -554,7 +554,7 @@ TEST_F(SessionPoolTest, MultiplexedLabels) {
       db, {mock}, threads.cq(),
       Options{}
           .set<spanner::SessionPoolLabelsOption>(std::move(labels))
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   ASSERT_STATUS_OK(session);
   EXPECT_EQ((*session)->session_name(), "multiplexed");
@@ -598,7 +598,7 @@ TEST_F(SessionPoolTest, MultiplexedCreatorRole) {
       db, {mock}, threads.cq(),
       Options{}
           .set<spanner::SessionCreatorRoleOption>(role)
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
   auto session = pool->Multiplexed();
   ASSERT_STATUS_OK(session);
   EXPECT_EQ((*session)->session_name(), "multiplexed");
@@ -773,7 +773,7 @@ TEST_F(SessionPoolTest, MultilpexedSessionReplacementSuccess) {
               background_interval)
           .set<MultiplexedSessionReplacementIntervalOption>(
               replacement_interval)
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
 
   auto s1 = pool->Multiplexed();
   ASSERT_STATUS_OK(s1);
@@ -815,7 +815,7 @@ TEST_F(SessionPoolTest, MultilpexedSessionReplacementRpcPermanentFailure) {
               background_interval)
           .set<MultiplexedSessionReplacementIntervalOption>(
               replacement_interval)
-          .set<spanner_experimental::EnableMultiplexedSessionOption>({}));
+          .set<spanner::EnableMultiplexedSessionOption>({}));
 
   auto s1 = pool->Multiplexed();
   ASSERT_STATUS_OK(s1);
diff --git a/google/cloud/spanner/options.h b/google/cloud/spanner/options.h
@@ -57,25 +57,29 @@
 
 namespace google {
 namespace cloud {
-namespace spanner_experimental {
+namespace spanner {
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
 
 /**
- * Option for `google::cloud::Options` to use MultiplexedSessions in lieu of
+ * Option for `google::cloud::Options` to use Multiplexed sessions in lieu of
  * pooled sessions.
  *
+ * When Multiplexed sessions are enabled, ALL operations: read-only,
+ * partitioned, and read-write will use Multiplexed sessions. Selectively
+ * enabling Multiplexed sessions for some subset of operations is not supported.
+ *
+ * @note None of the GOOGLE_CLOUD_SPANNER_MULTIPLEXED_SESSIONS* environment
+ * variables are supported.
+ *
+ * @see https://cloud.google.com/spanner/docs/sessions#multiplexed_sessions for
+ * more information.
+ *
  * @ingroup google-cloud-spanner-options
  */
 struct EnableMultiplexedSessionOption {
   using Type = absl::monostate;
 };
 
-GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
-}  // namespace spanner_experimental
-
-namespace spanner {
-GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
-
 /**
  * Option for `google::cloud::Options` to set a `spanner::RetryPolicy`.
  *
@@ -130,10 +134,10 @@ struct RouteToLeaderOption {
  * Option for `google::cloud::Options` to set the database role used for
  * session creation.
  *
- * When used in combination with Multiplexed Sessions, the database role applies
- * to all operations performed using that spanner::Connection. To perform
- * operations with a different database role, using Multiplexed Sessions, a
- * separate spanner::Connection is required.
+ * @note When used in combination with Multiplexed sessions, the database role
+ * applies to all operations performed using that spanner::Connection. To
+ * perform operations with a different database role, using Multiplexed
+ * sessions, a separate spanner::Connection is required.
  *
  * @ingroup google-cloud-spanner-options
  */
@@ -252,8 +256,7 @@ using SessionPoolOptionList = OptionList<
     RouteToLeaderOption, SessionCreatorRoleOption, SessionPoolMinSessionsOption,
     SessionPoolMaxSessionsPerChannelOption, SessionPoolMaxIdleSessionsOption,
     SessionPoolActionOnExhaustionOption, SessionPoolKeepAliveIntervalOption,
-    SessionPoolLabelsOption,
-    spanner_experimental::EnableMultiplexedSessionOption>;
+    SessionPoolLabelsOption, EnableMultiplexedSessionOption>;
 
 /**
  * Option for `google::cloud::Options` to set the optimizer version used in an

Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,7 @@ class ClientIntegrationTest : public spanner_testing::DatabaseIntegrationTest {`
`55`	`55`	`auto session_mode =`
`56`	`56`	`internal::GetEnv("GOOGLE_CLOUD_CPP_SPANNER_TESTING_SESSION_MODE");`
`57`	`57`	`if (session_mode.has_value() && *session_mode == "multiplexed") {`
`58`		`- options.set<spanner_experimental::EnableMultiplexedSessionOption>({});`
	`58`	`+ options.set<spanner::EnableMultiplexedSessionOption>({});`
`59`	`59`	`}`
`60`	`60`	`client_ = std::make_unique<Client>(`
`61`	`61`	`MakeConnection(GetDatabase(), std::move(options)));`