From 6668020eccf0e17885883a742da075b23b966162 Mon Sep 17 00:00:00 2001
From: Ellet <echo.ellet@gmail.com>
Date: Wed, 24 Jun 2026 17:22:38 +0300
Subject: [PATCH 1/2] docs: add doc comments for Session interface

---
 lib/postgres.dart | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/lib/postgres.dart b/lib/postgres.dart
index fb4e429..d76086a 100644
--- a/lib/postgres.dart
+++ b/lib/postgres.dart
@@ -125,6 +125,18 @@ class Sql {
   factory Sql.named(String sql, {String substitution}) = SqlImpl.named;
 }
 
+/// A capability for preparing and executing SQL statements.
+///
+/// This is **not** necessarily a 1:1 mapping to a PostgreSQL physical database
+/// connection or session.
+///
+/// An implementation may represent:
+///
+/// - a dedicated database connection.
+/// - a session executed on a connection borrowed from a pool.
+/// - or another abstraction capable of executing queries.
+///
+/// A session may also operate in a transactional context ([TxSession]).
 abstract class Session {
   /// Whether this connection is currently open.
   ///

From 25df66de832448b37735ef068a59850bdc16841f Mon Sep 17 00:00:00 2001
From: Ellet <echo.ellet@gmail.com>
Date: Wed, 24 Jun 2026 17:23:23 +0300
Subject: [PATCH 2/2] docs: document Pool.run(), Pool.execute() and other
 convenience methods

---
 lib/src/pool/pool_api.dart | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/lib/src/pool/pool_api.dart b/lib/src/pool/pool_api.dart
index b4af7ba..a3d8e9e 100644
--- a/lib/src/pool/pool_api.dart
+++ b/lib/src/pool/pool_api.dart
@@ -57,6 +57,10 @@ class PoolSettings extends ConnectionSettings {
 ///   specified data range.
 /// - a primary/replica status, whic may be specified for cases where stale or
 ///   read-only data is acceptable
+///
+/// This interface implements [Session] and [SessionExecutor] as a convenience
+/// API that internally acquires a pooled connection via [withConnection] for
+/// each operation.
 abstract class Pool<L> implements Session, SessionExecutor {
   factory Pool.withSelector(
     EndpointSelector<L> selector, {
@@ -125,8 +129,9 @@ abstract class Pool<L> implements Session, SessionExecutor {
   // TODO: decide whether PgSession.execute and prepare methods should also take locality parameter
 }
 
-typedef EndpointSelector<L> =
-    FutureOr<EndpointSelection> Function(EndpointSelectorContext<L> context);
+typedef EndpointSelector<L> = FutureOr<EndpointSelection> Function(
+  EndpointSelectorContext<L> context,
+);
 
 final class EndpointSelectorContext<L> {
   final L? locality;