Add configurable checkout timeout for transactions

[mgruen]

Summary

• pog.transaction called pgo:checkout/1 with no timeout, defaulting to pgo_pool's hardcoded 5000ms
• Add checkout_timeout field to Config (default: 5000ms, backwards compatible)
• Add checkout_timeout/2 setter so users can increase it
• Pass the timeout through to pgo:checkout/2 in the transaction path

Problem

Serverless databases (Neon, Supabase) can have cold starts of 5-30s. Cross-region connections add latency per round-trip. pog.query works fine (it passes timeout via pool_options), but pog.transaction fails with QueryTimeout because the checkout path had no configurable timeout.

Usage

let config = pog.url_config(name, url)
  |> pog.checkout_timeout(30_000)  // 30s for serverless DB cold starts

Fixes #82

[Copilot]

Pull request overview

Adds a configurable connection checkout timeout for pog.transaction, addressing failures on slower/cold-starting Postgres backends by passing an explicit timeout into pgo:checkout/2.

Changes:

• Added checkout_timeout to pog.Config (default 5000ms) plus a checkout_timeout/2 setter.
• Extended pog.Connection’s pooled variant to carry checkout_timeout, and used it when acquiring a dedicated connection for transaction.
• Updated Erlang FFI to support checkout/2 and to match the updated pooled-connection tuple shape.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/pog.gleam	Adds config + API surface for checkout timeout and threads it through the transaction checkout path.
src/pog_ffi.erl	Implements checkout/2 via pgo:checkout/2 and adapts query tuple matching for the updated Connection representation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

named_connection/1 now hardcodes checkout_timeout: 5000, so apps that start a pool with a larger Config.checkout_timeout but later create a Connection via named_connection (as shown in the README) will still have transactions failing at 5s. Consider adding a public API to override the checkout timeout on an existing Connection (or a named_connection/2 variant) so supervised pools can use the configured timeout.

Suggested change

	Pool(name:, checkout_timeout: 5000)
	}
	named_connection_with_timeout(name, 5000)
	}
	/// Create a reference to a pool using the pool's name and an explicit
	/// checkout timeout, in milliseconds.
	///
	/// This is useful when the pool was started elsewhere with a non-default
	/// `Config.checkout_timeout`, so transactions using this connection can use
	/// the same timeout when acquiring a dedicated connection from the pool.
	///
	/// If no pool has been started using this name then queries using this
	/// connection will fail.
	///
	pub fn named_connection_with_timeout(
	name: Name(Message),
	checkout_timeout: Int,
	) -> Connection {
	Pool(name:, checkout_timeout:)
	}

[Copilot]

The default checkout timeout value 5000 is duplicated (e.g. named_connection and default_config). To avoid drift if this default changes, consider introducing a single module-level constant (e.g. default_checkout_timeout) and referencing it in both places.

[Copilot]

There are transaction tests, but none that exercise the new checkout-timeout path (i.e. that checkout_timeout is actually passed through to pgo:checkout/2 and affects transaction behavior). Adding a test that forces checkout contention (e.g. pool_size=1 and holding a connection) would help prevent regressions.