django-postgres-multirange

PostgreSQL multirange fields for Django, built on the same primitives as django.contrib.postgres range fields.

A multirange is an ordered set of non-overlapping ranges — the native way to store things like available hours, blocked-out dates, or VLAN id spans in a single column.

Django declined to add these types to contrib.postgres. This package fills that gap.

Requirements

• Python 3.10+
• Django 5.2+
• psycopg 3
• PostgreSQL 14+ (developed against PostgreSQL 17)

Install

pip install django-postgres-multirange
# or, with the binary psycopg build:
pip install "django-postgres-multirange[binary]"

Add django.contrib.postgres to INSTALLED_APPS. Adding django_postgres_multirange is optional; the fields work without it.

Fields

Each range field Django already ships has a matching multirange:

Python values are psycopg.types.multirange.Multirange objects — a mutable sequence of Range. Lists of ranges or (lower, upper) pairs are accepted on assignment, the same way RangeField accepts a pair.

from django.contrib.postgres.indexes import GistIndex
from django.db import models
from django_postgres_multirange import IntegerMultiRangeField, Multirange
from psycopg.types.range import Range


class Schedule(models.Model):
    hours = IntegerMultiRangeField()

    class Meta:
        indexes = [GistIndex(fields=["hours"])]


Schedule.objects.create(hours=[(9, 12), (13, 17)])
row = Schedule.objects.get()
# PostgreSQL normalizes on write.
assert row.hours == Multirange([Range(9, 12), Range(13, 17)])

Continuous fields (DecimalMultiRangeField, DateTimeMultiRangeField) accept Django's default_bounds ("[)" by default) for pair input.

Empty ({} / Multirange()) is distinct from NULL.

Lookups

The lookups match RangeField, plus two that only make sense on a multirange:

Schedule.objects.filter(hours__contains=10)
Schedule.objects.filter(hours__overlap=(12, 14))
Schedule.objects.filter(hours__contains=[(9, 10), (14, 15)])
Schedule.objects.filter(hours__range_merge__contains=16)
Schedule.objects.filter(hours__len=2)

GiST indexes and ExclusionConstraint work the same way they do for range fields (&&, @>, <@, …).

Development

make up     # Postgres 17 on localhost:54317
make test

See CONTRIBUTING.md for the full workflow.

Roadmap

Not in this release:

• tsmultirange (Django has no tsrange counterpart)
• union / intersection / difference / unnest database functions
• range_agg / range_intersect_agg
• user-defined range types
• a non-JSON admin widget

License

BSD-3-Clause

Questions or issues: omar.bohsali@gmail.com