Skip to main content
View as Markdown

Avoid Sequence Locks in Document Numbers

Not Yet in Stable Release

This feature is not yet part of a stable iDempiere release and may change.

Goal: Technical

Developer: Carlos Ruiz (BX Service)

Feature Ticket: IDEMPIERE-7120

Avoiding Sequence Locks Under Concurrent Document Creation​

The Problem: Sequence Lock Contention​

When many documents are created concurrently - for example during load testing or high-volume integrations - iDempiere's numeric document sequences become a bottleneck. Each document number allocation locks the AD_Sequence row, and under heavy concurrency, threads queue up waiting for the lock. After the configured timeout (MSEQUENCE_GETNEXT_TIMEOUT SysConfig, default 30 seconds) is exceeded, causing GenerateDocumentNoTimeOut errors and failed document creation.

Solution 1: Allow Gaps for Numeric Document Sequences​

For numeric document sequences where lock contention is a concern but UUIDs are not desired, a new Allow Gaps setting is available.

  • When a numeric document sequence allows gaps, the next number allocation uses a standalone/committed transaction instead of the caller's transaction. This means the allocated number is preserved even if the caller rolls back, avoiding the need to hold the lock for the entire document creation process.

Solution 2: UUID Document Sequences​

This feature introduces a UUID-based sequence type for document numbers. When a sequence is configured as UUID, it generates a UUIDv7 value - a time-ordered, sortable UUID - without needing to lock the sequence row at all. This eliminates the contention point entirely.

Existing numeric sequences continue to work as before. UUID sequences are opt-in per document type.

UUID sequences have also better performance as they don't require the UPDATE to the AD_Sequence table.

Setting Up a low-contention Document Sequence​

  1. Open the Sequence window and select the sequence used by your document type, or create a new one.
  2. Enable the UUID option by setting the IsUUIDSeq flag to Yes.
  3. Alternatively Enable the Allow Gaps by setting the IsAllowSequenceGaps flag to Yes.
  4. Configure prefix and suffix as needed - same as numeric sequences, the UUID value is placed between the prefix and suffix.

AvoidLocksInDocumentSequences

Document Number Field Expansion​

To accommodate the longer UUID values, all DocumentNo columns and related process parameters in the core iDempiere tables have been widened from 30 to 255 characters. This includes fields such as:

  • I_GLJournal.BatchDocumentNo
  • I_GLJournal.JournalDocumentNo
  • C_PaySelection.Name
  • C_Payment.CheckNo
  • C_Order.POReference
  • C_Invoice.POReference
  • C_BPartner.POReference

Backward Compatibility​

This feature is fully backward compatible:

  • Existing numeric sequences continue to work unchanged.
  • UUID sequences are opt-in; no existing behavior is altered unless IsUUIDSeq is explicitly enabled.
  • Document number field expansion (30 → 255 characters) is transparent to existing data.