Adapters

Adapters#

The adapter layer connects MuduDB client code to different backend capabilities, including SQLite, PostgreSQL, MySQL, and the MuduDB kernel itself. It lets the same procedure code run interactively against a standalone database during development and be deployed against mudud in production.

Supported backends#

Backend

Use case

Connection hint

MuduDB kernel

Production / full Mudu Procedure runtime.

mudud://host:port/...

SQLite

Local development and tests.

sqlite://path/to/db.sqlite

PostgreSQL

Compatibility testing against Postgres.

postgres://user:pass@host/db

MySQL

Compatibility testing against MySQL.

mysql://user:pass@host/db

The exact URL format depends on the adapter implementation in use. Check the current mudu_adapter crate for the supported connection strings in this release.

Connection configuration#

Adapters are typically configured through the MUDU_CONNECTION environment variable or a connection string passed to mudu_open. Common parameters include:

  • http_addr — HTTP management endpoint used to discover topology when connecting to mudud.

  • async_session_loop — enable or disable the background async manager thread.

  • app — default application name for interactive SQL shells.

Example connection string:

mudud://127.0.0.1:9527/ycsb?http_addr=127.0.0.1:8300

Async session loop#

When async_session_loop=true, the adapter forwards session management and I/O commands to a dedicated background manager thread running an async runtime. The manager keeps long-lived AsyncClient connections and serializes work through a channel-based command queue.

Behavioral differences#

  • Synchronous path (async_session_loop=false): each mudu_open creates a SyncClient and calls are performed blocking on the caller thread.

  • Asynchronous path (async_session_loop=true): adapter methods enqueue commands (Open/Close/Get/Put/Range/Query/Command/Batch) to the manager and wait for a response over a small sync channel, reducing blocking on the calling thread and improving concurrency.

When to use async loop#

Prefer async_session_loop=true when:

  • connecting to the IOUring or Tokio backend,

  • running many concurrent sessions from a single client,

  • blocking the caller thread is expensive.

Use false for simple scripts, tests, or when debugging step-by-step.

Known differences#

  • The MuduDB kernel supports Mudu Procedures and .mpk packages; SQLite/PostgreSQL/MySQL adapters do not.

  • Parameterized batch may be implemented differently across backends; the kernel currently returns NotImplemented when parameters are supplied.

  • Partition routing and topology discovery are kernel-specific features.

See Partitioning for routing details and Mudu Procedure for the procedure programming model.