§reference

event_notifications

Optional: needed only with the local event handler. One delivery row per event and handler: fan-out turns each event into one row per handler that subscribes to it, so an event with two handlers becomes two rows, with the same event_id and different handler_name.

Needed when: you use the local event handler. Written by: EventFanoutJob creates rows; EventHandlingJob updates them. Created by: your migration (V0001__eventlog.sql in the examples, beside events). Where: eventlog.event_notifications. On PostgreSQL eventlog is a schema in each database; on MySQL and MariaDB it is a database of its own, one per server. The place is fixed - see Framework tables.

Like events, it is a plain row shape, not a model or an entity. The handling job updates its rows directly as delivery goes on. In code, a row is an EventNotification, read and written by EventNotificationRepository.

DDL

PostgreSQL

CREATE TABLE eventlog.event_notifications (
    id              UUID         PRIMARY KEY,
    event_id        UUID         NOT NULL,
    handler_name    VARCHAR(255) NOT NULL,
    namespace       VARCHAR(255) NOT NULL,
    action_id       UUID         NOT NULL,
    action_name     VARCHAR(255) NOT NULL,
    action_params   JSONB        NOT NULL,
    started_date    TIMESTAMP    NOT NULL,
    completion_date TIMESTAMP    NOT NULL,
    model_id        VARCHAR(255),
    model_type      VARCHAR(255),
    event_type      VARCHAR(255) NOT NULL,
    payload         JSONB,
    event_date      TIMESTAMP    NOT NULL,
    state           VARCHAR(24)  NOT NULL,
    attempts        INT          NOT NULL DEFAULT 0,
    next_retry_at   TIMESTAMP    NOT NULL,
    created_date    TIMESTAMP    NOT NULL,
    updated_date    TIMESTAMP    NOT NULL,
    UNIQUE (event_id, handler_name)
);

CREATE INDEX event_notifications_due
    ON eventlog.event_notifications (next_retry_at)
    WHERE state IN ('PENDING', 'FAILED');

MySQL

CREATE TABLE eventlog.event_notifications (
    id              CHAR(36)     CHARACTER SET ascii NOT NULL,
    event_id        CHAR(36)     CHARACTER SET ascii NOT NULL,
    handler_name    VARCHAR(255) NOT NULL,
    namespace       VARCHAR(255) NOT NULL,
    action_id       CHAR(36)     CHARACTER SET ascii NOT NULL,
    action_name     VARCHAR(255) NOT NULL,
    action_params   JSON         NOT NULL,
    started_date    DATETIME(6)  NOT NULL,
    completion_date DATETIME(6)  NOT NULL,
    model_id        VARCHAR(255),
    model_type      VARCHAR(255),
    event_type      VARCHAR(255) NOT NULL,
    payload         JSON,
    event_date      DATETIME(6)  NOT NULL,
    state           VARCHAR(24)  NOT NULL,
    attempts        INT          NOT NULL DEFAULT 0,
    next_retry_at   DATETIME(6)  NOT NULL,
    created_date    DATETIME(6)  NOT NULL,
    updated_date    DATETIME(6)  NOT NULL,
    PRIMARY KEY (id),
    UNIQUE (event_id, handler_name)
);

CREATE INDEX event_notifications_due ON eventlog.event_notifications (next_retry_at);

MariaDB

As MySQL, with MariaDB’s UUID type for id (UUID PRIMARY KEY), event_id and action_id.

DATETIME(6) rather than DATETIME matters here: next_retry_at is compared with times that are not whole seconds.

Columns

Twelve columns are copied from the event row when fan-out creates the delivery row, so a handler needs nothing else:

columnnullmeaning
event_idnothe events row this delivery is for
namespacenocopied: the service that emitted the event
action_idnocopied: shared by every row one action wrote
action_namenocopied: what ran
action_paramsnocopied: the action’s input, for anything the event does not carry
started_datenocopied
completion_datenocopied
model_idyescopied
model_typeyescopied
event_typenocopied. Never null here, unlike in events: action rows are never fanned out
payloadyescopied: the event as JSON
event_datenocopied: the event’s time

The rest belong to this table: which handler the row is for, and how its delivery is going.

columnnullmeaning
idnothis delivery row
handler_namenothe handler’s name(). Treat it as part of the schema - see below
statenoPENDING, FAILED, SUCCEEDED or EXPIRED
attemptsnohow many times the handler has run for it
next_retry_atnothe earliest time the handler may run again. Fan-out sets it to the event’s event_date, so an older event is handled first
created_datenowhen fan-out created the row
updated_datenowhen it last changed

The unique key

UNIQUE (event_id, handler_name) means each handler gets each event once. Fan-out writes the rows and marks their events delivered in one transaction per shard. If two fan-outs ever work on the same events at once, the second one’s insert breaks the unique key, its transaction rolls back, and no second delivery row is made.

The same idea is worth copying into your own handlers: to make work safe to repeat, put a unique key inside the transaction that does the work. Checking first in code - “is there a row? if not, insert one” - leaves a gap where another process can slip in. A unique key leaves none.

The due index

The handling job reads due rows - state IN ('PENDING', 'FAILED') AND next_retry_at <= now, oldest next_retry_at first - on each shard’s primary. On PostgreSQL the index is partial, so SUCCEEDED and EXPIRED rows stay out of it. MySQL and MariaDB have no partial indexes; the examples index next_retry_at alone there.

States

statemeaning
PENDINGwritten by fan-out; not tried yet
FAILEDthe handler failed, and another try is still inside the retention window
SUCCEEDEDfinal. The handler returned Ok
EXPIREDfinal. The retention window passed without success - or the row was already past it when it was first read, and the handler was never called

FAILED is not final; EXPIRED is. Each try that ran adds one to attempts, success included; an expiry before any try does not.

A handler that can never succeed - a transfer into a closed wallet, say - should not return an error. It should record a business outcome and return Ok; otherwise it is retried until the window closes. See Sagas.

Nothing deletes old rows. SUCCEEDED and EXPIRED rows stay until you remove them.

Handler names are part of the schema

handler_name stores the handler’s name(), so queued rows carry the name the handler had when they were written. Rename a handler and every row queued under the old name finds no handler: each try fails with No handler registered with name: <old name>, until the rows expire.

Keep the old name in aliases():

impl EventHandler for WalletMoneyDepositedEventHandler {
    type Event = WalletMoneyDepositedEvent;

    fn name(&self) -> String {
        "wallet-money-deposited-notification".to_owned()
    }

    fn aliases(&self) -> Vec<String> {
        vec!["wallet-deposit-alert".to_owned()] // what it used to be called
    }

    fn handle(&self, envelope: EventEnvelope<WalletMoneyDepositedEvent>) -> Result<(), Error> {
        // ...
        Ok(())
    }
}

New rows are written with name(), and queued rows written under an alias still reach the handler. Drop the alias once no PENDING or FAILED row under the old name is left.

See also