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("io.namastack:namastack-outbox-starter-jpa:1.6.x")
}

Maven

<dependency>
    <groupId>io.namastack</groupId>
    <artifactId>namastack-outbox-starter-jpa</artifactId>
    <version>1.6.x</version>
</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("io.namastack:namastack-outbox-starter-jdbc:1.6.x")
}

Maven

<dependency>
    <groupId>io.namastack</groupId>
    <artifactId>namastack-outbox-starter-jdbc</artifactId>
    <version>1.6.x</version>
</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 Table Prefix and Schema Name

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

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

Examples:

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

Schema Initialization Limitation

When using custom table prefix or schema name, 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("io.namastack:namastack-outbox-starter-mongodb:1.6.x")
}

Maven

<dependency>
    <groupId>io.namastack</groupId>
    <artifactId>namastack-outbox-starter-mongodb</artifactId>
    <version>1.6.x</version>
</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.