Django Sequences

Common errors

• IntegrityError: duplicate key value violates unique constraint

  cause `get_next_value` was called, but the model saving the value was not wrapped in an atomic transaction or the transaction failed to commit, leading to a duplicate value being attempted later.
  fix Ensure all calls to `get_next_value()` and the subsequent `model.save()` are within a `with transaction.atomic():` block.

• Application is slow when multiple users/processes try to generate sequence numbers simultaneously.

  cause Access to `get_next_value()` for a specific sequence is serialized at the database level to ensure gapless numbers. Long-running transactions or very high contention can lead to performance bottlenecks.
  fix Optimize the code within the `transaction.atomic()` block to be as fast as possible. If extreme concurrency is needed and occasional non-sequential IDs are acceptable, consider alternative ID generation strategies or sharding sequences across different names.

• Gaps appear in generated sequence numbers in my application's records.

  cause This typically happens if the `get_next_value()` call and the record creation/update are not within the same atomic transaction, or if a transaction committed a value, but later records were inserted using a different mechanism or without using the sequence correctly.
  fix Verify that `django.db.transaction.atomic()` strictly wraps both the `get_next_value()` call and the database `create()` or `save()` for the record that uses the generated number.

Warnings

• gotcha For django-sequences to guarantee gapless values, `get_next_value()` and the corresponding model save operation MUST be executed within the same database transaction. If the transaction is committed, the value is consumed; otherwise, if the transaction rolls back, the value is not consumed by the user's model but the sequence counter is still incremented internally.
  Fix: Always wrap your `get_next_value()` call and model creation/update in `django.db.transaction.atomic()`.
• gotcha If a transaction involving `get_next_value()` is rolled back (e.g., due to an error in your code after retrieving the value but before committing), the internal sequence counter for `django-sequences` itself is NOT rolled back for performance reasons. This means there will be a 'gap' in the sequence numbers generated by `django-sequences` if you inspect its internal table, even though your application's committed records remain gapless.
  Fix: This is expected behavior and a trade-off for performance. Design your application to handle occasional internal sequence gaps if auditing the `sequences` table directly.
• gotcha Database transactions that call `get_next_value()` for a given sequence are serialized. This means concurrent calls for the *same* sequence will block, potentially impacting performance. Keep transactions involving `get_next_value()` as short as possible.
  Fix: Minimize the amount of work performed within the `transaction.atomic()` block that calls `get_next_value()`. Consider using `nowait=True` on `get_next_value()` for non-blocking behavior, though this might raise exceptions on contention.
• breaking The `read uncommitted` database isolation level is NOT supported and will lead to gaps and incorrect behavior. The `repeatable read` level is supported but requires application-level handling of serialization failures and retries.
  Fix: Use the `read committed` isolation level for optimal compatibility and guarantees. If using `repeatable read`, implement retry logic for transactions that encounter serialization errors.

Install

• pip install django-sequences Install stable version

Imports

• get_next_value
  wrong:

  from django_sequences import get_next_value

  correct:

  from sequences import get_next_value

  The top-level package name is 'sequences', not 'django_sequences'.
• Sequence

  from sequences import Sequence

  Provides an object-oriented API for sequence generation.
• SequencesConfig

  INSTALLED_APPS = [..., 'sequences.apps.SequencesConfig', ...]

  Required to register the application in Django settings.

Quickstart

To generate a gapless sequence, ensure that `get_next_value()` and the subsequent database save operation occur within the same atomic transaction. The library provides `get_next_value()` for a functional approach and a `Sequence` class for an object-oriented API. Remember to add `sequences.apps.SequencesConfig` to your `INSTALLED_APPS` and run migrations.

import os
from django.db import transaction
from sequences import get_next_value

# Assume 'Invoice' is a Django model with an 'number' field
# from invoices.models import Invoice

# For demonstration, we'll mock a model and save operation
class MockInvoice:
    _instances = []
    def __init__(self, number):
        self.number = number
        print(f"Created MockInvoice with number: {self.number}")
        MockInvoice._instances.append(self)

def create_invoice_with_sequence(sequence_name='invoice_numbers'):
    try:
        with transaction.atomic():
            next_invoice_number = get_next_value(sequence_name)
            # Replace with your actual model creation:
            # Invoice.objects.create(number=next_invoice_number)
            MockInvoice(number=next_invoice_number)
            print(f"Successfully committed invoice with number: {next_invoice_number}")
    except Exception as e:
        print(f"Transaction failed: {e}")

# Example usage:
create_invoice_with_sequence('orders')
create_invoice_with_sequence('orders')
create_invoice_with_sequence('shipments', initial_value=1000)
create_invoice_with_sequence('shipments')