This chapter will cover several considerations in regards to tuning the database for events.

SQL Databases

If you have generated the tables automatically using your JPA implementation (e.g. Hibernate), you probably do not have all the right indexes set on your tables. Different usages of the event store require different indexes to be set for optimal performance. This list suggests the indexes that should be added for the different types of queries used by the default EventStorageEngine implementation:

• Normal operational use (storing and loading events):

  Table DomainEventEntry, columns aggregateIdentifier and sequenceNumber (unique index)

  Table DomainEventEntry, eventIdentifier (unique index)

• Snapshotting:

  Table SnapshotEventEntry, aggregateIdentifier column.

  Table SnapshotEventEntry, eventIdentifier (unique index)

• Sagas

  Table AssociationValueEntry, columns sagaType, associationKey and associationValue,

  Table AssociationValueEntry, columns sagaId and sagaType,

The default column lengths generated by e.g. Hibernate may work, but won't be optimal. A UUID, for example, will always have the same length. Instead of a variable length column of 255 characters, you could use a fixed length column of 36 characters for the aggregate identifier.

The timestamp column in the DomainEventEntry table only stores ISO 8601 timestamps. If all times are stored in the UTC timezone, they need a column length of 24 characters. If you use another timezone, this may be up to 28. Using variable length columns is generally not necessary, since time stamps always have the same length.

Warning

It is highly recommended to store all timestamps in UTC format. In countries with daylight saving time, storing timestamps in local time may result in sorting errors for events generated around and during the timezone switch. This does not occur when UTC is used. Some servers are configured to always use UTC. Alternatively, you should configure the event store to convert timestamps to UTC before storing them.

The type column in the DomainEventEntry stores the type identifiers of aggregates. Generally, these are the 'simple name' of the aggregate. Even the infamous AbstractDependencyInjectionSpringContextTests in Spring only counts 45 characters. Here, again, a shorter (but variable) length field should suffice.

Auto-increments and sequences

When using a relational database as an event store, Axon relies on an auto-increment value to allow tracking processors to read all events roughly in the order they were inserted. We say "roughly", because "insert-order" and "commit-order" are different things.

While auto-increment values are (generally) generated at insert-time, these values only become visible at commit-time. This means another process may observe these sequence numbers arriving in a different order. While Axon has mechanisms to ensure eventually all events are handled, even when they become visible in a different order, there are limitations and performance aspects to consider.

When a tracking processor reads events, it uses the "global sequence" to track its progress. When events become available in a different order than they were inserted, Axon will encounter a "gap". Axon will remember these "gaps" to verify that data has become available since the last read. These gaps may be the result of events becoming visible in a different order, but also because a transaction was rolled back. It is highly recommended to ensure that no gaps exist because of over eagerly increasing the sequence number. The mechanism for checking gaps is convenient, but comes with a performance impact.

When using a JpaEventStorageEngine, Axon relies on the JPA implementation to create the table structure. While this will work, it is unlikely to provide the configuration that has the best performance for the database engine in use. That is because Axon uses default settings for the @GeneratedValue annotation.

To override these settings, create a file called /META-INF/orm.xml on the classpath, which looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings version="1.0" xmlns="http://java.sun.com/xml/ns/persistence/orm">
    <mapped-superclass access="FIELD" metadata-complete="false" class="org.axonframework.eventhandling.AbstractSequencedDomainEventEntry">
        <attributes>
            <id name="globalIndex">
                <generated-value strategy="SEQUENCE" generator="myGenerator"/>
                <sequence-generator name="myGenerator" sequence-name="mySequence"/>
            </id>
        </attributes>
    </mapped-superclass>
</entity-mappings>

It is important to specify metadata-complete="false". This indicates this file should be used to override existing annotations, instead of replacing them. For the best results, ensure that the DomainEventEntry table uses its own sequence. This can be ensured by specifying a different sequence generator for that entity only.