From 663202ec7673e7345287cef661540a381ad44764 Mon Sep 17 00:00:00 2001
From: Lev Kokotov <lev.kokotov@gmail.com>
Date: Sat, 11 Jan 2025 12:06:39 -0800
Subject: [PATCH] session mode docs

---
 docs/docs/features/session-mode.md     | 30 ++++++++++++++++++++++++++
 docs/docs/features/transaction-mode.md |  2 +-
 pgdog/src/frontend/client.rs           |  5 ++---
 3 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 docs/docs/features/session-mode.md

diff --git a/docs/docs/features/session-mode.md b/docs/docs/features/session-mode.md
new file mode 100644
index 0000000..04d7fdc
--- /dev/null
+++ b/docs/docs/features/session-mode.md
@@ -0,0 +1,30 @@
+# Session mode
+
+In session mode, pgDog allocates one PostgreSQL server connection per client. This ensures that all PostgreSQL features work as expected, including persistent session variables, settings, and
+process-based features like `LISTEN`/`NOTIFY`. Some batch-based tasks, like ingesting large amounts of data, perform better in session mode.
+
+## Enable session mode
+
+Session mode can be enabled globally or on a per-user basis:
+
+=== "pgdog.toml"
+    ```toml
+    [general]
+    pooler_mode = "session"
+    ```
+=== "users.toml"
+    ```toml
+    [[users]]
+    name = "pgdog"
+    database = "pgdog"
+    pooler_mode = "session"
+    ```
+
+## Performance
+
+Unlike [transaction mode](transaction-mode.md), session mode doesn't allow for client/server connection multiplexing, so the maximum number of allowed client connections
+is controlled by the `default_pool_size` (and `pool_size`) settings. For example, if your database pool size is 15,
+only 15 clients will be able to connect and use the database at any given moment.
+
+!!! note
+    In session mode, when the connection pool reaches full capacity, a client has to disconnect before another one can connect to pgDog.
diff --git a/docs/docs/features/transaction-mode.md b/docs/docs/features/transaction-mode.md
index ba38d1f..2915163 100644
--- a/docs/docs/features/transaction-mode.md
+++ b/docs/docs/features/transaction-mode.md
@@ -6,7 +6,7 @@ more than a few thousand concurrently open connections.
 
 <center>
   <img src="/images/transaction-mode.png" width="65%" alt="Load balancer" />
-  <p><i>In transaction mode, multiple clients reuse one Postgres connection.</i></p>
+  <p><i>In transaction mode, multiple clients can reuse one Postgres connection.</i></p>
 </center>
 
 
diff --git a/pgdog/src/frontend/client.rs b/pgdog/src/frontend/client.rs
index da600f7..e379cb1 100644
--- a/pgdog/src/frontend/client.rs
+++ b/pgdog/src/frontend/client.rs
@@ -9,7 +9,6 @@ use tracing::{debug, error, info, trace};
 use super::{Buffer, Comms, Error, Router, Stats};
 use crate::auth::scram::Server;
 use crate::backend::pool::Connection;
-use crate::config::PoolerMode;
 use crate::net::messages::{
     Authentication, BackendKeyData, ErrorResponse, Protocol, ReadyForQuery,
 };
@@ -55,7 +54,7 @@ impl Client {
             Ok(params) => params,
             Err(err) => {
                 if err.no_server() {
-                    error!("Connection pool is down");
+                    error!("connection pool is down");
                     stream.fatal(ErrorResponse::connection()).await?;
                     return Ok(());
                 } else {
@@ -161,7 +160,7 @@ impl Client {
                         match backend.connect(&self.id, router.route()).await {
                             Ok(()) => (),
                             Err(err) => if err.no_server() {
-                                error!("Connection pool is down");
+                                error!("connection pool is down");
                                 self.stream.error(ErrorResponse::connection()).await?;
                                 comms.stats(stats.error());
                                 continue;