Add configurable checkout timeout for transactions

pog.transaction uses pgo:checkout to acquire a dedicated connection, but
previously called it with no timeout option, defaulting to pgo_pool's
hardcoded 5000ms. This is too short for serverless databases (Neon,
Supabase) with cold starts or cross-region connections with high latency.

Changes:
- Add checkout_timeout field to Config (default: 5000ms for backwards compat)
- Add checkout_timeout/2 setter function
- Store checkout_timeout in Pool connection variant
- Pass timeout to pgo:checkout/2 in transaction path
- Update pog_ffi checkout/2 to accept and forward timeout

Fixes #82

Author: Michael G

src/pog.gleam

@@ -25,7 +25,7 @@ import gleam/uri.{Uri}
 const default_port: Int = 5432
 
 pub opaque type Connection {
-  Pool(Name(Message))
+  Pool(name: Name(Message), checkout_timeout: Int)
   SingleConnection(SingleConnection)
 }
 
@@ -39,7 +39,7 @@ pub type Message
 /// connection will fail.
 ///
 pub fn named_connection(name: Name(Message)) -> Connection {
-  Pool(name)
+  Pool(name:, checkout_timeout: 5000)
 }
 
 /// The configuration for a pool of connections.
@@ -75,6 +75,11 @@ pub type Config {
     /// (default: 1000): The database is pinged every idle_interval when the
     /// connection is idle.
     idle_interval: Int,
+    /// (default: 5000): Timeout in milliseconds for checking out a connection
+    /// from the pool. Used by `transaction` when acquiring a dedicated
+    /// connection. If the checkout takes longer than this, the transaction
+    /// fails with `QueryTimeout`.
+    checkout_timeout: Int,
     /// trace (default: False): pgo is instrumented with [OpenCensus][1] and
     /// when this option is true a span will be created (if sampled).
     ///
@@ -189,6 +194,14 @@ pub fn idle_interval(config: Config, idle_interval: Int) -> Config {
   Config(..config, idle_interval:)
 }
 
+/// Timeout in milliseconds for checking out a connection from the pool.
+/// Used by `transaction` when acquiring a dedicated connection.
+///
+/// default: 5000
+pub fn checkout_timeout(config: Config, checkout_timeout: Int) -> Config {
+  Config(..config, checkout_timeout:)
+}
+
 /// Trace pgo is instrumented with [OpenTelemetry][1] and
 /// when this option is true a span will be created (if sampled).
 ///
@@ -235,6 +248,7 @@ pub fn default_config(pool_name pool_name: Name(Message)) -> Config {
     queue_target: 50,
     queue_interval: 1000,
     idle_interval: 1000,
+    checkout_timeout: 5000,
     trace: False,
     ip_version: Ipv4,
     rows_as_map: False,
@@ -335,7 +349,11 @@ fn extract_ssl_mode(query: option.Option(String)) -> Result(Ssl, Nil) {
 ///
 pub fn start(config: Config) -> actor.StartResult(Connection) {
   case start_tree(config) {
-    Ok(pid) -> Ok(actor.Started(pid, Pool(config.pool_name)))
+    Ok(pid) ->
+      Ok(actor.Started(
+        pid,
+        Pool(name: config.pool_name, checkout_timeout: config.checkout_timeout),
+      ))
     Error(reason) -> Error(actor.InitExited(process.Abnormal(reason)))
   }
 }
@@ -431,10 +449,11 @@ pub fn transaction(
     SingleConnection(conn) -> {
       transaction_layer(conn, callback)
     }
-    Pool(name) -> {
+    Pool(name:, checkout_timeout:) -> {
       // Check out a single connection from the pool
       use #(ref, conn) <- result.try(
-        checkout(name) |> result.map_error(TransactionQueryError),
+        checkout(name, checkout_timeout)
+        |> result.map_error(TransactionQueryError),
       )
 
       // Make a best attempt to check back in the connection, even if this
@@ -481,6 +500,7 @@ fn transaction_layer(
 @external(erlang, "pog_ffi", "checkout")
 fn checkout(
   pool: Name(Message),
+  timeout: Int,
 ) -> Result(#(Reference, SingleConnection), QueryError)
 
 @external(erlang, "pgo", "checkin")

src/pog_ffi.erl

@@ -1,6 +1,6 @@
 -module(pog_ffi).
 
--export([query/4, query_extended/2, start/1, coerce/1, null/0, checkout/1]).
+-export([query/4, query_extended/2, start/1, coerce/1, null/0, checkout/2]).
 
 -include_lib("pog/include/pog_Config.hrl").
 -include_lib("pg_types/include/pg_types.hrl").
@@ -86,7 +86,7 @@ query(Pool, Sql, Arguments, Timeout) ->
     Res = case Pool of
         {single_connection, Conn} ->
             pgo_handler:extended_query(Conn, Sql, Arguments, #{});
-        {pool, Name} ->
+        {pool, Name, _CheckoutTimeout} ->
             Options = #{
                 pool => Name,
                 pool_options => [{timeout, Timeout}]
@@ -110,8 +110,8 @@ query_extended(Conn, Sql) ->
             {error, convert_error(Error)}
     end.
 
-checkout(Name) when is_atom(Name) ->
-    case pgo:checkout(Name) of
+checkout(Name, Timeout) when is_atom(Name) ->
+    case pgo:checkout(Name, [{timeout, Timeout}]) of
         {ok, Ref, Conn} -> {ok, {Ref, Conn}};
         {error, Error} -> {error, convert_error(Error)}
     end.