Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.eventdbx.com/llms.txt

Use this file to discover all available pages before exploring further.

Aggregates are the unit of consistency inside EventDBX. They own their events, snapshots, and Merkle trees. Good aggregate design keeps writes simple and isolates failure domains.

​
Naming and identifiers

  • Use stable, business-meaningful IDs (invoice-991, org_42). Avoid database auto-increment integers—they leak implementation details.
  • Embed shard hints if you plan to distribute aggregates across filesystems: order:us:10023.
  • Store identifiers in metadata (@tenant, @channel) so plugins can route events without parsing payloads.

​
Lifecycle

Create aggregates explicitly with an initial event: 
dbx aggregate create person p-991 person_registered --payload '{"first_name":"jane","last_name":"doe"}'
Append new facts as they occur: 
dbx aggregate apply person p-991 person_updated --payload '{"status":"active"}'
Check current state (with optional history): 
dbx aggregate get person p-991 --include-events
Delete operations are rare; prefer terminal events (invoice_voided) that mark state without removing history. If you must retire an aggregate, archive it (dbx aggregate archive <type> <id>) or remove only when it has no events (dbx aggregate remove requires version 0).

​
Metadata conventions

{
  "@actor": "svc-billing",
  "@tenant": "northwind",
  "@source": "invoice-service",
  "@replay": false
}
Reserve the @ prefix for extension metadata. Everything else belongs to your business domain. Consistent metadata enables search, audit, and replication filters. Use namespaced keys (@trace, @tenant) to keep user hints distinct from system metadata.

​
Anti-patterns to avoid

  • God aggregates: packing unrelated concerns (billing + identity + compliance) into one aggregate explodes payload size and causes contention.
  • Cross-aggregate transactions: EventDBX is intentionally single-write-path. Model relationships through events (e.g., order_paid referencing payment_id) and have read models enforce constraints asynchronously.
  • Mutable fields: never overwrite data in place. Emit a new event (invoice_amount_adjusted) so the audit trail stays truthful.
Thoughtful aggregate design pays dividends when you need to replay history, verify integrity, or explain how a piece of state changed over time.