Adapters - Iii — ContextQMD

Each iii module that needs persistence or distribution uses an adapter — a pluggable backend that implements a fixed interface. Swap adapters in iii-config.yaml without touching application code.

Pattern

yaml

modules:
  - class: modules::queue::QueueModule
    config:
      adapter:
        class: modules::queue::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

Every adapter entry has two fields:

class — the full adapter path
config — adapter-specific config (omit if not needed)

Adapter Reference

Queue

Adapter	Class	External dependency
Built-in	`modules::queue::BuiltinQueueAdapter`	None
Redis	`modules::queue::RedisAdapter`	Redis
RabbitMQ	`modules::queue::RabbitMQAdapter`	RabbitMQ

`modules::queue::BuiltinQueueAdapter`

Default. In-process only with retries and DLQ — does not share messages across engine instances.

yaml

adapter:
  class: modules::queue::BuiltinQueueAdapter

`modules::queue::RedisAdapter`

yaml

adapter:
  class: modules::queue::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}

`modules::queue::RabbitMQAdapter`

yaml

adapter:
  class: modules::queue::RabbitMQAdapter
  config:
    amqp_url: ${RABBITMQ_URL:amqp://localhost:5672}
    max_attempts: 3
    prefetch_count: 10
    queue_mode: standard   # standard | fifo

<Info> For retry behavior, dead-letter queues, and full config reference, see the [Queue module](/modules/module-queue). </Info>

State

Adapter	Class	External dependency
KV Store	`modules::state::adapters::KvStore`	None
Redis	`modules::state::adapters::RedisAdapter`	Redis
Bridge	`modules::state::adapters::Bridge`	Remote iii Engine

`modules::state::adapters::KvStore`

Default. Supports in-memory or file-based persistence.

yaml

adapter:
  class: modules::state::adapters::KvStore
  config:
    store_method: file_based   # in_memory | file_based
    file_path: ./data/state
    save_interval_ms: 5000

`modules::state::adapters::RedisAdapter`

yaml

adapter:
  class: modules::state::adapters::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}

`modules::state::adapters::Bridge`

Forwards state operations to a remote iii Engine.

yaml

adapter:
  class: modules::state::adapters::Bridge

Stream

Adapter	Class	External dependency
KV Store	`modules::stream::adapters::KvStore`	None
Redis	`modules::stream::adapters::RedisAdapter`	Redis

`modules::stream::adapters::KvStore`

Default. In-process only.

yaml

adapter:
  class: modules::stream::adapters::KvStore
  config:
    store_method: file_based   # in_memory | file_based
    file_path: ./data/stream_store
    save_interval_ms: 5000

`modules::stream::adapters::RedisAdapter`

yaml

adapter:
  class: modules::stream::adapters::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}

Cron

Adapter	Class	External dependency
KV Cron	`modules::cron::KvCronAdapter`	None
Redis Cron	`modules::cron::RedisCronAdapter`	Redis

`modules::cron::KvCronAdapter`

Default. Process-local locks — jobs may run on every instance in multi-instance deployments.

yaml

adapter:
  class: modules::cron::KvCronAdapter

`modules::cron::RedisCronAdapter`

Distributed locking via Redis — ensures each job runs only once across all instances.

yaml

adapter:
  class: modules::cron::RedisCronAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}

PubSub

Adapter	Class	External dependency
Local	`modules::pubsub::LocalAdapter`	None
Redis	`modules::pubsub::RedisAdapter`	Redis

`modules::pubsub::LocalAdapter`

Default. In-process broadcast — subscribers must be in the same engine process.

yaml

adapter:
  class: modules::pubsub::LocalAdapter

`modules::pubsub::RedisAdapter`

yaml

adapter:
  class: modules::pubsub::RedisAdapter
  config:
    redis_url: ${REDIS_URL:redis://localhost:6379}

Choosing an Adapter

	Single instance	Multi-instance
Queue	BuiltinQueueAdapter	RedisAdapter or RabbitMQAdapter
State	KvStore (file_based)	RedisAdapter
Stream	KvStore	RedisAdapter
Cron	KvCronAdapter	RedisCronAdapter
PubSub	LocalAdapter	RedisAdapter

<Info title="Environment variables"> Use `${VAR:default}` syntax in `iii-config.yaml` to switch adapters per environment without changing the file:

yaml

redis_url: ${REDIS_URL:redis://localhost:6379}

</Info>