Persistence Modules

Namastack Outbox provides three persistence modules to choose from based on your needs.

JPA Module

The JPA module uses Hibernate/JPA for database operations. Best for projects already using Spring Data JPA.

Gradle

dependencies {
    implementation(platform("io.namastack:namastack-outbox-bom:1.9.x"))
    implementation("io.namastack:namastack-outbox-starter-jpa")
}

Maven

<dependencyManagement>
  <dependencies>
      <dependency>
          <groupId>io.namastack</groupId>
          <artifactId>namastack-outbox-bom</artifactId>
          <version>1.9.x</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>io.namastack</groupId>
  <artifactId>namastack-outbox-starter-jpa</artifactId>
</dependency>

Schema Management

The JPA module does not support automatic schema creation. You must manage schemas using:

• Flyway/Liquibase (recommended for production) - Use the SQL schema files
• Hibernate DDL Auto (ddl-auto: create) for development

---

JDBC Module

The JDBC module uses Spring's JdbcClient for database operations. Best for projects that don't use JPA or want lower overhead.

Gradle

dependencies {
    implementation(platform("io.namastack:namastack-outbox-bom:1.9.x"))
    implementation("io.namastack:namastack-outbox-starter-jdbc")
}

Maven

<dependencyManagement>
  <dependencies>
      <dependency>
          <groupId>io.namastack</groupId>
          <artifactId>namastack-outbox-bom</artifactId>
          <version>1.9.x</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>io.namastack</groupId>
  <artifactId>namastack-outbox-starter-jdbc</artifactId>
</dependency>

Benefits:

• No Hibernate/JPA dependency required
• Built-in automatic schema initialization
• Support for custom table prefixes and schema names
• Lower memory footprint

Automatic Schema Creation (JDBC Only)

The JDBC module automatically creates outbox tables on startup by default:

namastack:
  outbox:
    jdbc:
      schema-initialization:
        enabled: true  # Auto-create tables on startup (default: true)

Database Detection

The JDBC module automatically detects your database type and uses the appropriate schema. Supported databases: PostgreSQL, MySQL, MariaDB, H2, SQL Server, Oracle.

Custom Schema Name and Table Prefix

The JDBC module supports custom table naming for multi-tenant deployments or naming conventions:

namastack:
  outbox:
    jdbc:
      schema-name: "outbox_schema"     # Results in: outbox_schema.myapp_outbox_record
      table-prefix: "myapp_"           # Results in: myapp_outbox_record, myapp_outbox_instance, etc.

Examples:

Configuration	Resulting Table Name
Default	outbox_record
schema-name: "myschema"	myschema.outbox_record
table-prefix: "app1_"	app1_outbox_record
Both	myschema.app1_outbox_record

Fully Custom Table Names

When a prefix is not enough — for example when organization-wide standards mandate all-uppercase, case-sensitive identifiers — you can override the base table names directly:

namastack:
  outbox:
    jdbc:
      table-prefix: "ACME_"
      table-names:
        record: "OUTBOX_RECORD"        # Results in: ACME_OUTBOX_RECORD
        instance: "OUTBOX_INSTANCE"    # Results in: ACME_OUTBOX_INSTANCE
        partition: "OUTBOX_PARTITION"  # Results in: ACME_OUTBOX_PARTITION

schema-name and table-prefix are still applied on top of the configured base names.

For complete control over naming (beyond prefix/schema/base-name composition), register your own JdbcTableNameResolver bean. The auto-configuration only provides the default implementation when no such bean exists (@ConditionalOnMissingBean):

Kotlin

@Bean
fun jdbcTableNameResolver(): JdbcTableNameResolver =
    object : JdbcTableNameResolver {
        override val outboxRecord = "ACME_OUTBOX_RECORD"
        override val outboxInstance = "ACME_OUTBOX_INSTANCE"
        override val outboxPartitionAssignment = "ACME_OUTBOX_PARTITION"
    }

Java

@Bean
public JdbcTableNameResolver jdbcTableNameResolver() {
    return new JdbcTableNameResolver() {
        @Override
        public String getOutboxRecord() {
            return "ACME_OUTBOX_RECORD";
        }

        @Override
        public String getOutboxInstance() {
            return "ACME_OUTBOX_INSTANCE";
        }

        @Override
        public String getOutboxPartitionAssignment() {
            return "ACME_OUTBOX_PARTITION";
        }
    };
}

Schema Initialization Limitation

When using a custom schema name, table prefix or custom table names, you must disable schema initialization (which is enabled by default). Schema initialization cannot be used with custom naming:

namastack:
  outbox:
    jdbc:
      table-prefix: "myapp_"
      schema-name: "custom_schema"
      schema-initialization:
        enabled: false  # Must be false when using custom naming

Manual Schema Creation:

Use the SQL schema files as templates and adjust table names: 👉 Schema Files on GitHub

---

MongoDB Module

The MongoDB module uses Spring Data MongoDB for document-based persistence. Best for projects already using MongoDB.

Gradle

dependencies {
    implementation(platform("io.namastack:namastack-outbox-bom:1.9.x"))
    implementation("io.namastack:namastack-outbox-starter-mongodb")
}

Maven

<dependencyManagement>
  <dependencies>
      <dependency>
          <groupId>io.namastack</groupId>
          <artifactId>namastack-outbox-bom</artifactId>
          <version>1.9.x</version>
          <type>pom</type>
          <scope>import</scope>
      </dependency>
  </dependencies>
</dependencyManagement>

<dependency>
  <groupId>io.namastack</groupId>
  <artifactId>namastack-outbox-starter-mongodb</artifactId>
</dependency>

Benefits:

• No SQL or relational database required
• Automatic collection and index creation via Spring Data MongoDB
• Support for custom collection prefixes
• Single-document atomicity for most operations

Custom Collection Prefix

The MongoDB module supports custom collection naming for multi-tenant deployments or naming conventions:

namastack:
  outbox:
    mongodb:
      collection-prefix: "myapp_"         # Results in: myapp_outbox_records, myapp_outbox_instances, etc.

Examples:

Configuration	Resulting Collection Name
Default	outbox_records
collection-prefix: "app_"	app_outbox_records
collection-prefix: "tenant1_"	tenant1_outbox_records

Index Creation

Ensure spring.data.mongodb.auto-index-creation is set to true (or manage indexes manually) so that the required indexes for outbox collections are created automatically. For production environments, consider using the manual setup script instead.