Update timeout documentation + deprecate/update APIs

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## 3.4.0-dev.2
 
 - Support for binary `pgoutput` replication by [wolframm](https://github.com/Wolframm-Activities-OU).
-- Deprecated `TupleDataColumn.data`, user `.value` instead (for binary protocol messages).
+- Deprecated `TupleDataColumn.data`, use `.value` instead (for binary protocol messages).
 - **Allowing custom type codecs**:
   - `Codec` interface is used for encoding/decoding value by type OIDs or Dart values.
   - `Codec.encode` and `Codec.decode` gets a reference to `CodecContext` which provides
@@ -15,6 +15,14 @@
 - **Behaviour / soft-breaking changes**:
   - Removed `@internal`-annotated methods from the public API of `ServerException` and `Severity`.
   - `ServerException` may be transformed into `_PgTimeoutException` which is both `PgException` and `TimeoutException` (but no longer `ServerException`).
+  - The `timeout` parameters and the `SessionSettings.queryTimeout` has only a somewhat
+    acceptable behaviour: it triggers a timeout only in the local `Future` object, but
+    keeps the statement running on the server. Updated documentation, deprecated the
+    parameter where it doesn't make long-term sense.
+
+    **Do not rely on the combination of timeouts and query statement queueing!**
+    We are planning to adopt a `statement_timeout`-based implementation, which will be a
+    breaking change for queuing-related timeouts.
 
 ## 3.3.0
 

lib/postgres.dart

@@ -144,7 +144,12 @@ abstract class Session {
   ///
   /// When the returned future completes, the statement must eventually be freed
   /// using [Statement.dispose] to avoid resource leaks.
-  Future<Statement> prepare(Object /* String | Sql */ query);
+  Future<Statement> prepare(
+    Object /* String | Sql */ query, {
+    /// NOTE: setting the timeout here affects only the local [Future] object and
+    ///       it does not cancel the pending statement. This may change in the future.
+    Duration? timeout,
+  });
 
   /// Executes the [query] with the given [parameters].
   ///
@@ -172,6 +177,9 @@ abstract class Session {
         parameters,
     bool ignoreRows = false,
     QueryMode? queryMode,
+
+    /// NOTE: setting the timeout here affects only the local [Future] object and
+    ///       it does not cancel the pending statement. This may change in the future.
     Duration? timeout,
   });
 }
@@ -248,6 +256,10 @@ abstract class Statement {
   Future<Result> run(
     Object? /* List<Object?|TypedValue> | Map<String, Object?|TypedValue> */
         parameters, {
+    /// NOTE: setting the timeout here affects only the local [Future] object and
+    ///       it does not cancel the pending statement. This may change in the future.
+    @Deprecated('Use the `prepare` methods\'s `timeout` parameter instead. '
+        'Setting this parameter may throw an error in the future, and it may be removed in a future version.')
     Duration? timeout,
   });
 

lib/src/pool/pool_impl.dart

@@ -71,14 +71,17 @@ class PoolImplementation<L> implements Pool<L> {
   }
 
   @override
-  Future<Statement> prepare(Object query) async {
+  Future<Statement> prepare(
+    Object query, {
+    Duration? timeout,
+  }) async {
     final statementCompleter = Completer<Statement>();
 
     unawaited(withConnection((connection) async {
       _PoolStatement? poolStatement;
 
       try {
-        final statement = await connection.prepare(query);
+        final statement = await connection.prepare(query, timeout: timeout);
         poolStatement = _PoolStatement(statement);
       } on Object catch (e, s) {
         // Could not prepare the statement, inform the caller and stop occupying
@@ -297,8 +300,11 @@ class _PoolConnection implements Connection {
   }
 
   @override
-  Future<Statement> prepare(Object query) {
-    return _connection.prepare(query);
+  Future<Statement> prepare(
+    Object query, {
+    Duration? timeout,
+  }) {
+    return _connection.prepare(query, timeout: timeout);
   }
 
   @override

lib/src/v3/connection.dart

@@ -170,7 +170,12 @@ abstract class _PgSessionBase implements Session {
   }
 
   @override
-  Future<Statement> prepare(Object query) async => await _prepare(query);
+  Future<Statement> prepare(
+    Object query, {
+    Duration? timeout,
+  }) async {
+    return await _prepare(query, timeout: timeout);
+  }
 
   Future<_PreparedStatement> _prepare(
     Object query, {