diff --git a/src/kura_driver.erl b/src/kura_driver.erl index 5464cca..12c4323 100644 --- a/src/kura_driver.erl +++ b/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(), diff --git a/src/kura_pool.erl b/src/kura_pool.erl index 46ad7b4..bdf64c1 100644 --- a/src/kura_pool.erl +++ b/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,7 +35,7 @@ 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", @@ -42,8 +43,8 @@ teardown checks it back in. 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). ``` """.