docs: the behaviour examples name the backend kura selects

src/kura_driver.erl

@@ -4,7 +4,7 @@ Pluggable database driver behaviour.
 
 A `kura_driver` implementation is the seam between kura's portable
 query layer and a specific database client library. Each impl wraps
-one client (`pgo`, `esqlite`, `mysql_otp`, ...) behind a uniform
+one client (`minato`, `pgo`, `esqlite`, `mysql_otp`, ...) behind a uniform
 query/transaction surface.
 
 The pool layer (`kura_pool`) hands out a connection. The driver layer
@@ -30,8 +30,9 @@ the transaction context.
 
 ## Today
 
-The canonical impl is `kura_driver_pgo`. It uses pgo's process-dict
-based transaction context (`pgo_transaction_connection`) so existing
+The canonical impl is `kura_driver_minato`, and `kura_driver_pgo` is
+still shipped. Both keep the in-flight transaction in the process
+dictionary so that queries written inside a transaction function
 code that does `kura_db:transaction(Repo, fun() -> kura_repo:insert(...) end)`
 continues to work transparently.
 """.
@@ -45,14 +46,17 @@ continues to work transparently.
 -type params() :: [term()].
 
 -doc """
-Driver-specific options. The pgo driver honors `decode_opts`. Other
-drivers may ignore unknown keys or define their own.
+Driver-specific options. The PostgreSQL drivers honor `decode_opts`,
+and the minato driver also passes `timeout`, which is a deadline after
+which the statement is cancelled on the server. Other drivers may
+ignore unknown keys or define their own.
 """.
 -type opts() :: map().
 
 -doc """
 Driver-specific result shape. Today this is whatever the underlying
-client returns (`#{rows := [...], num_rows := N, ...}` for pgo). A
+client returns (`#{rows := [...], num_rows := N, ...}` for both
+PostgreSQL drivers). A
 future kura layer may normalize this; the driver behaviour does not
 prescribe a shape.
 """.
@@ -84,11 +88,13 @@ its lifetime.
 -doc """
 Wrap `Fun` in a database transaction over a pool. Queries inside
 `Fun` route to the transaction's connection by whatever convention
-the driver uses (pgo: process dict).
+the driver uses (both PostgreSQL drivers: the process dictionary).
 
 `Opts` carries driver-specific options. The pgo driver honors
 `pool_options => [{timeout, infinity | non_neg_integer()}]` for
-long-running streams. Other drivers may ignore unknown keys.
+long-running streams; the minato driver takes no options here, because
+a statement's deadline is set per query rather than per transaction.
+Other drivers may ignore unknown keys.
 """.
 -callback transaction(PoolMod, Pool, Fun, Opts) -> term() when
     PoolMod :: module(),

src/kura_pool.erl

@@ -10,7 +10,7 @@ Different drivers want different pool shapes:
 
 - Network-protocol drivers like Postgres benefit from caller-side I/O on
   the socket, so the pool just hands out a connection record and stays
-  out of the way (`kura_pool_pgo`, the canonical PG impl).
+  out of the way (`kura_pool_minato`, the canonical PG impl).
 - gen_server-style drivers like MySQL or HTTP clients want a worker
   process the caller calls into; a gen_server-call-style pool fits.
 
@@ -20,8 +20,9 @@ matches their backend.
 ## Token vs connection
 
 `checkout/2` returns both a `conn()` and a `token()`. The `conn()` is
-what callers actually use to run work (e.g. a `pgo_pool:conn()` record
-that `pgo_handler:extended_query/4` accepts). The `token()` is the
+what callers actually use to run work: `kura_pool_minato` hands back a
+process that owns the connection and answers queries, and the pgo impl
+hands back pgo's own conn record. The `token()` is the
 opaque value the caller hands back to `checkin/2`. Implementations are
 free to make them the same value if they like.
 
@@ -34,16 +35,16 @@ teardown checks it back in.
 ## Example
 
 ```erlang
-{ok, _Pid} = kura_pool_pgo:start_pool(my_pool, #{
+{ok, _Pid} = kura_pool_minato:start_pool(my_pool, #{
     host => "localhost",
     database => "my_app",
     user => "postgres",
     password => "secret",
     pool_size => 10
 }),
 
-kura_pool:with_conn(kura_pool_pgo, my_pool, fun(Conn) ->
-    pgo_handler:extended_query(Conn, ~"SELECT 1", [])
+kura_pool:with_conn(kura_pool_minato, my_pool, fun(Conn) ->
+    kura_driver_minato:query_on(Conn, ~"SELECT 1", [], #{})
 end).
 ```
 """.