Database clients

arknet provides native, header-only MySQL and Redis clients for independent single-node database services. Both support Boost.Asio and Standalone Asio, own their IO resources, and provide bounded connection pools. Neither requires Boost.MySQL, Boost.Redis or a database client driver.

Build and run

OpenSSL is required for MySQL authentication even when a connection explicitly disables TLS. Enable ARKNET_ENABLE_SSL to use MySQL or secure Redis. Plain Redis does not need OpenSSL.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DARKNET_ENABLE_SSL=ON -DARKNET_BUILD_EXAMPLES=ON
cmake --build build --target arknet_mysql_client arknet_mysql_pool \
  arknet_redis_client arknet_redis_pool --config Release

Boost is selected by default. Standalone Asio uses ARKNET_USE_BOOST_ASIO=OFF and, if necessary, ARKNET_ASIO_INCLUDE_DIR. The examples and benchmarks are independent C++ executables; running them does not require Python or Ruby.

The examples require an explicit service endpoint. Supply passwords through their documented environment variables. TLS examples keep certificate-chain and DNS/IP identity verification enabled; private CAs require the appropriate trust file.

Connections and pool leases

An independent MySQL connection or Redis client owns one IO context and thread. A database pool shares library-owned IO resources among its connections; its connection limit is not a thread count. MySQL pools expose io_threads; Redis pools use one IO context and thread.

async_acquire returns an exclusive lease. Keep the same lease for the complete MySQL transaction or Redis WATCH/MULTI/EXEC sequence. Submit operations through the lease, then call release() or let it leave scope. Use discard() when reuse must be forbidden.

Returning a lease starts asynchronous processing. The pool waits for submitted callbacks and pending replies before resetting the session. Another borrower cannot use that connection during return processing.

MySQL prepared statements belong to one connection generation and session. Reset, reconnect or return invalidates them; a handle cannot be used by another borrower. Bare-connection transaction helpers do not prevent another producer from submitting an intervening command, so use a lease or enforce ownership for the entire transaction.

Cancellation and uncertain outcomes

Cancellation cannot retract a command that has already been sent. Neither client automatically reconnects or replays failed commands.

A failed MySQL commit may already have committed. A failed Redis pipeline may contain replies received before failure and may have executed later sent commands. Decide retries from application semantics and durable operation identifiers.

Redis server errors are typed error or bulk_error replies; bool(result) checks the client status, so inspect individual replies too. RESP3 pushes use a separate handler and never consume ordinary response slots. MySQL preserves available server error code, SQLSTATE and message; a complete normal ERR response differs from a broken protocol boundary.

Limits and callback ownership

Both clients reserve bounded work before posting it to their IO lane. Configure command count and byte limits, result/parser limits, pool connection/waiter limits and deadlines for the intended workload. These limits do not cap caller-owned storage or total process RSS.

Timeouts must be positive and representable by the monotonic clock. A zero Redis command-timeout override or either pool’s acquisition-timeout override selects its configured default. MySQL query_options.timeout must be positive. Negative or overflowing overrides are rejected. Queue wait is included in operation deadlines.

Results own their values. MySQL buffers rows within its configured result limits; it does not provide row streaming. Redis pipelines buffer their owned replies within the pipeline limit. Check field/value types before accessing them.

Callbacks for accepted operations run on the associated library IO lane and must not block or throw. An empty or moved-from lease has no executor and rejects inline with request ID 0. Once close_and_wait() closes permanent admission, requests on live clients, pools and retained leases also invoke their rejection handlers synchronously on the caller. These later rejection handlers may propagate exceptions and are outside the earlier accepted-operation set. Capture application state with sufficient ownership through completion.

close() asynchronously requests closure; its return is not a callback-drain barrier. Redis clients and both pools close terminally. A standalone MySQL connection can explicitly reconnect after closing its session. See process shutdown for owned runtimes and global owners.

Supported scope and TODOs

HTTP/2, HTTP/3, named pipes, Unix domain sockets and RPC remain separate items on the roadmap. RESP3 push delivery does not constitute a Pub/Sub subscription API.

Validation and measurement

Independent-server checks include MySQL Community Server 8.4.11 and Redis 7.4.2. Client and pool suites cover successful operations, authentication/TLS rejection, malformed or partial responses, queue saturation, cancellation, session reset, lease isolation and shutdown. Protocol-codec and IO-runtime tests provide separate coverage.

Deadline tests include nonpositive durations, integer extremes and clock-addition boundaries. Correctness and sanitizer checks are separate from local Release measurements; test counts are not throughput or capacity figures.

MySQL retains its runtime while asynchronous posting returns, including when a completion destroys the connection. Separate invalid-connect and rejected-command destruction cases cover these immediate completion paths. MySQL connection/pool suites pass TSan with both Asio dependencies and ASan+UBSan with Boost.Asio; the testing record identifies their scope and counts.

The MySQL and Redis performance pages describe their compilable benchmarks, workload dimensions and reports. Record the machine/server configuration, payload, queue/pipeline depth, connections, repeated rounds, operations/s, RT percentiles and CPU percentage. Capacity requires deployment acceptance.

arknet owns protocol IO, authentication, reply correlation, pools and shutdown. ark database plugins own framework configuration and module integration; applications own transaction boundaries, business results and retry decisions. Client release does not establish ark plugin compatibility without application regression tests.