soda docs v17.0.1
/

Requirements

ItemRequirement
JDK17 or newer
Spring Boot3.2.x ~ 4.1.x (one jar covers both)
Build toolMaven or Gradle
DatabaseNot bound by the framework — you implement the repository layer yourself
Tip

Don't want to scaffold a project by hand? Generate one at https://start.soda.hibuka.com — H2 in-memory database built in, unzip and mvn spring-boot:run, no MySQL or Redis needed. See Quickstart, which walks you through the sample code.

Tip

soda manages versions through the spring-boot-dependencies BOM. If your own project also imports Spring Boot's dependency management, versions align automatically — soda needs no separate Spring Boot version.

Add the core dependency

soda-core-base is the core package: command bus, query bus, event bus, CQRS aspects, domain events, and context propagation.

xml
<dependency>
  <groupId>com.hibuka.soda</groupId>
  <artifactId>soda-core-base</artifactId>
  <version>17.0.1</version>
</dependency>

Gradle:

groovy
implementation 'com.hibuka.soda:soda-core-base:17.0.1'
Important

The version in the coordinates above is filled in at build time. The latest version is whatever the Maven repository shows — check the repository page for com.hibuka.soda:soda-core-base, or see Versions & Compatibility.

Optional: Redis event bus

The default event bus is in-process — events are delivered inside one JVM only. To deliver events across services (service A writes its database and triggers logic in service B), add soda-event-redis:

xml
<dependency>
  <groupId>com.hibuka.soda</groupId>
  <artifactId>soda-event-redis</artifactId>
  <version>17.0.1</version>
</dependency>

It is built on Redis Streams, with consumer groups, idempotency keys, and a dead-letter stream.

Note

soda-event-redis is an optional dependency. If you don't need cross-service delivery, don't add it — the artifact is much smaller and pulls in no Redis dependency.

What auto-configuration does

Once the dependency is in place you write no @Configuration at all — Spring Boot auto-configuration registers these beans:

Auto-configuration classWhat it does
SpringBusAutoConfigurationAlways active: registers CommandBus, QueryBus, cqrsAsyncExecutor, BusFacade. The name is misleading — it has nothing to do with Spring events; it is the CQRS skeleton in every mode
SimpleEventBusAutoConfigurationActive when bus-type=simple or unset: registers SimpleEventBus (matchIfMissing = true)
RepositoryEventAutoConfigurationActive when the container has an EventBus: registers RepositoryEventAspect — publishing suspended domain events automatically on aggregate save
RedisEventBusAutoConfigurationActive when bus-type=redis (requires soda-event-redis): registers the Redis Streams event bus

BusFacade is always available — it is the entry point your business code uses to send commands and queries.

Switching the event bus type

In application.yaml:

yaml
soda:
  event:
    bus-type: simple      # simple | redis
ValueEffect
unsetSimpleEventBus — in-process, no external dependency
simpleSame as above, but explicit — intent is clearer. Recommended
redisRedis Streams; requires the soda-event-redis dependency + Redis config; delivers across services
spring⚠️ No such implementation in the current version. No EventBus bean is created at all and domain events silently never fire
Warning

The EventProperties field still defaults to "spring", but the soda-event-spring module was removed in 17.0.1. Do not write spring — no error is raised, but events never go out. Leaving it unconfigured is safe (falls back to Simple).

Full option list: Configuration Reference. Practical recipes: Configuration.

Verify the install

Create an empty project, start Spring Boot, and look for soda's auto-configuration in the log:

java
@SpringBootApplication
public class SodaApplication {
    public static void main(String[] args) {
        SpringApplication.run(SodaApplication.class, args);
    }
}

Next: Quickstart.