Getting Started with ddd_cqrs_es

​

🚀 Installation

[dependencies]
ddd_cqrs_es = "0.3.0-rc.7"

​

Feature Flags

​

Enabling Durable Database Adapters:

• SQLite Support: Enable the "sqlite" feature (uses the rusqlite driver under the hood).
• PostgreSQL Support: Enable the "postgres" feature (uses the postgres driver under the hood).
• MySQL Support: Enable the "mysql" feature (uses the mysql driver under the hood).
• Spin MySQL Helper: Enable "spin-mysql" for Spin SDK MySQL query execution.

​

Supported Backends:

• SQLite / Local File: Standard local embedded SQL.
• PostgreSQL: Stable high-performance relational database.
• MySQL: High-performance relational database with native stores plus a Spin runtime query helper ("spin-mysql").
• LibSQL / Turso: Supported for distributed edge SQL via the "wasi-libsql" query helper.
• Redis: Supported for async event store, checkpoints, and pub/sub notifications via "redis" / "wasi-redis" / "spin-redis".

​

Realtime and Notification Support:

• PostgreSQL / SQLite / MySQL: Use durable events and checkpoints to drive polling, SSE, WebSocket, or worker pipelines in your application.
• Redis: Provides experimental async persistence plus notification-only pub/sub wake messages. Durable replay remains the source of truth.
• MySQL: MySQL does not provide a built-in pub/sub stream in this library; pair it with Redis, an outbox worker, binlog CDC, NATS, Kafka, or WebSocket fan-out when low-latency push notifications are required.

​

API Notes:

• Aggregates are loaded by the repository using the external stream ID; the Aggregate trait does not require an id() method.
• EventType is a serde-transparent newtype. Convert it with as_str() or into_string() when a database, UI, or protocol needs a plain string.
• SqlSchemaConfig table-name builders validate eagerly and return Result.
• Process managers can be coordinated by ProcessManagerRunner or AsyncProcessManagerRunner.
• execute_idempotent(...) is portable but not crash-atomic across separate stores. Use execute_idempotent_atomic(...) with native SQL stores for production request idempotency.

​

⚡ Quick 10-Second Example

use ddd_cqrs_es::{InMemoryEventStore, Repository, Metadata};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize a thread-safe, local, in-memory event ledger
    let store = InMemoryEventStore::<BankAccount>::new();
    
    // 2. Bind the ledger to the repository coordinator
    let repo = Repository::new(store);
    let account_id = "account_abc123".to_owned();

    // 3. Execute a transactional command with audit tracking metadata!
    repo.execute(
        &account_id,
        BankAccountCommand::DepositMoney { amount: 100 },
        Metadata::new().with_actor_id("user_alice"),
    )?;

    // 4. Rebuild aggregate state instantly by replaying its historical facts
    let loaded = repo.load(&account_id)?;
    assert_eq!(loaded.state.balance(), 100);
    
    println!("Transaction committed! Balance is: ${}", loaded.state.balance());
    Ok(())
}

​

🗺️ How to Navigate This Documentation

​

Start with the CLI: ddd CLI

• What you’ll learn: Install the ddd command, scaffold a new app with ddd init, add domain events and commands with ddd add, enable Redis/gRPC/tracing capabilities, run Spin-focused apps, and use dry-run JSON for agent/MCP workflows.

​

Module 1: The Patterns (Theory)

• What you’ll learn: The architectural foundations. Read about Domain-Driven Design (aggregate boundaries, Ubiquitous Language), CQRS (separating write vs read pipelines), State Changes (command validation vs event application), Queries (read models), and Event Sourcing mechanics.

​

Module 2: Domain Modeling (Tutorial)

• What you’ll learn: Build a fully validated Bank Account domain step-by-step. Implement Commands, Events (implementing DomainEvent), Errors (handling invariants), and the core Aggregate Root struct.

​

Module 3: Domain Tests

• What you’ll learn: Write bulletproof business validations in microseconds. Learn why Event Sourcing is a unit-testing superpower and write elegant Given-When-Then tests using the Aggregate Test Fixture API.

​

Module 4: Configuring an Application

• What you’ll learn: Assemble your domain parts. Wire up the local InMemoryEventStore, write a custom Query Projection, and Assemble them together into a working execution loop.

​

Module 5: Building an Application (Production)

• What you’ll learn: Move to production. Start with Production Guarantees, define Error Handling and Transport Mapping, deploy durable SQLite, PostgreSQL, and MySQL stores, configure asynchronous Projections with Checkpoint tracking, review production Database Query Patterns, use experimental Redis persistence and realtime notifications, attach Metadata trace headers, write custom Event Upcasters for schema evolution, and Integrate with Web Frameworks (Axum).

​

Module 6: Fullstack SaaS (Spin + wasi-auth)

• What you’ll learn: Operate the production SaaS starter. wasi-auth fullstack covers Spin + outbox worker, auth/org product surfaces, and release topology. Use auth storage rollout and OAuth rollout for operators. For Leptos islands product chrome (soft-nav, sidebar persistence, skeleton rules), read Persistent chrome on Leptos islands. Scaffold with ddd init --preset fullstack (see ddd CLI).

​

Module 7: Leptos WASM SSR + Spin CQRS and Runtimes

• What you’ll learn: The counter-style implementation path (domain → Spin storage → projections → server APIs → UI → backends → execution), then Wasmtime vs Spin deployment trade-offs.