Skip to main content
Version: 1.5.x

Database Support

Supported Databases​

Namastack Outbox supports any JPA/JDBC-compatible relational database. The JDBC module includes automatic schema creation for the following databases:

  • ✅ H2 (development)
  • ✅ MySQL / MariaDB
  • ✅ PostgreSQL
  • ✅ SQL Server
  • ✅ Oracle

MongoDB​

MongoDB is supported via the dedicated namastack-outbox-starter-mongodb module. Collections and indexes are created automatically via Spring Data MongoDB on application startup. For manual index management and index definitions, see MongoDB Schema. For module setup and configuration, see Persistence Modules → MongoDB.

Schema Management​

JDBC Module — Automatic Initialization​

The JDBC module creates the outbox schema automatically on application startup. This is enabled by default and requires no additional configuration.

To disable automatic schema creation (recommended for production deployments that use migration tools):

namastack:
  outbox:
    jdbc:
      schema-initialization:
        enabled: false

When disabled, you are responsible for creating the schema using your preferred migration tooling before the application starts.

JPA Module — No Automatic Schema Creation​

The JPA module does not support automatic schema creation. Schema management is delegated to Hibernate or your migration tool.

Option 1: Hibernate DDL Auto (Development Only)

spring:
  jpa:
    hibernate:
      ddl-auto: create      # or create-drop for test environments

This is convenient for local development but should never be used in production — it may drop and recreate tables on restart.

Option 2: Flyway or Liquibase (Production)

Create the outbox tables as part of your migration scripts. Database-specific SQL schema files are available in the repository: 👉 Schema Files on GitHub

Then configure Hibernate to validate the schema on startup rather than modify it:

spring:
  jpa:
    hibernate:
      ddl-auto: validate

If the schema does not match the expected structure, Spring Boot will fail to start — which is the desired behavior for production deployments.

Migration Strategies​

Flyway​

Add the Flyway migration file to src/main/resources/db/migration/:

-- V1__create_outbox_tables.sql
-- Copy the content from the appropriate schema file for your database

Liquibase​

Add the outbox table definition to your Liquibase changelog. Use the SQL schema files linked above as the source for the sql changeset type, or translate to Liquibase XML/YAML format.

Troubleshooting​

Table 'outbox_record' doesn't exist The schema has not been initialized. Either enable automatic initialization (JDBC module) or apply the migration scripts before starting the application.

Schema-validation: missing table (JPA module) Hibernate's ddl-auto: validate found a mismatch. Ensure your migration scripts match the schema files for the current library version. Check for pending migrations.

Could not obtain lock on outbox partition (PostgreSQL) This is a normal advisory lock contention message logged at DEBUG level when multiple instances compete for the same partition. It is not an error — the second instance will retry on the next poll cycle.

Oracle: ORA-00955: name is already used by an existing object Automatic schema initialization tried to create tables that already exist. Disable automatic initialization and manage the schema manually.