Skip to main content

Tools for refining Django's IntegrityError, and working with deferred database constraints.

Project description

Django Integrity

Django Integrity contains tools for controlling deferred constraints and handling IntegrityErrors in Django projects which use PostgreSQL.

Deferrable constraints

Some PostgreSQL constraints can be defined as DEFERRABLE. A constraint that is not deferred will be checked immediately after every command. A deferred constraint check will be postponed until the end of the transaction. A deferrable constraint will default to either DEFERRED or IMMEDIATE.

The utilities in django_integrity.constraints can ensure a deferred constraint is checked immediately, or defer an immediate constraint.

These alter the state of constraints until the end of the current transaction:

  • set_all_immediate(using=...)
  • set_immedate(names=(...), using=...)
  • set_deferred(names=(...), using=...)

To enforce a constraint immediately within some limited part of a transaction, use the immediate(names=(...), using=...) context manager.

Why do we need this?

This is most likely to be useful when you want to catch a foreign-key violation (i.e.: you have inserted a row which references different row which doesn't exist).

Django's foreign key constraints are deferred by default, so they would normally raise an error only at the end of a transaction. Using try to catch an IntegrityError from a foreign-key violation wouldn't work, and you'd need to wrap the COMMIT instead, which is trickier.

By making the constraint IMMEDIATE, the constraint would be checked on INSERT, and it would be much easier to catch.

More generally, if you have a custom deferrable constraint, it may be useful to change the default behaviour with these tools.

Refining IntegrityError

The refine_integrity_error context manager in django_integrity.conversion will convert an IntegrityError into a more specific exception based on a mapping of rules to your custom exceptions, and will raise the IntegrityError if it doesn't match.

Why do we need this?

When a database constraint is violated, we usually expect to see an IntegrityError.

Sometimes we need more information about the error: was it a unique constraint violation, or a check-constraint, or a not-null constraint? Perhaps we ran out of 32-bit integers for our ID column? Failing to be specific on these points could lead to bugs where we catch an exception without realising it was not the one we expected.

Example

from django_integrity import conversion
from users.models import User


class UserAlreadyExists(Exception): ...
class EmailCannotBeNull(Exception): ...
class EmailMustBeLowerCase(Exception): ...


def create_user(email: str) -> User:
    """
    Creates a user with the provided email address.

    Raises:
        UserAlreadyExists: If the email was not unique.
        EmailCannotBeNull: If the email was None.
        EmailMustBeLowerCase: If the email had a non-lowercase character.
    """
    rules = [
        (conversion.Unique(model=User, fields=("email",)), UserAlreadyExists),
        (conversion.NotNull(model=User, field="email"), EmailCannotBeNull),
        (conversion.Named(name="constraint_islowercase"), EmailMustBeLowerCase),
    ]
    with conversion.refine_integrity_error(rules):
        User.objects.create(email=email)

Supported dependencies

This package is tested against:

  • Python 3.10, 3.11, or 3.12.
  • Django 4.1, 4.2, or 5.0.
  • PostgreSQL 12 to 16.
  • psycopg2 and psycopg3.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_integrity-0.2.0.tar.gz (10.9 kB view details)

Uploaded Source

Built Distribution

django_integrity-0.2.0-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

Details for the file django_integrity-0.2.0.tar.gz.

File metadata

  • Download URL: django_integrity-0.2.0.tar.gz
  • Upload date:
  • Size: 10.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.0.0 CPython/3.12.3

File hashes

Hashes for django_integrity-0.2.0.tar.gz
Algorithm Hash digest
SHA256 6b7cd3779f7c06d3fbdfeb90f94bbf8b40d17a1c15b30362febab36506dc1cab
MD5 9b0e73070998af9b118926999c309129
BLAKE2b-256 154251158206450c032f5b6fbd00fe5d798b683062815c7de69df5261438b3c8

See more details on using hashes here.

File details

Details for the file django_integrity-0.2.0-py3-none-any.whl.

File metadata

File hashes

Hashes for django_integrity-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 95f5b3d41d81046c3075282dd6338d38a03c9f009b9fa17d6d49be371cf4d949
MD5 8ea83d14bfdabfdd1f2469d581f15eb5
BLAKE2b-256 f5575e16edf77b493ed8fdba9e03bb62fb2dea078695248dbf6f7600979f463c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page