DjanQuiltDB - Django Database Sharding

DjanQuiltDB is an extension to the Django web framework that provides helper functions to split a database based on top level hierarchy. It is specifically designed to support horizontal sharding not just within a single database cluster, but also across multiple database clusters, thus allowing you to scale database capacity both vertically and horizontally as your dataset grows.

This library attempts to combine the best of as many worlds as possible. Tenant-specific data is kept in tenant-specific PostgreSQL schemas, while data that is tenant-agnostic or shared can be kept in public schemas, so as to deduplicate. There are helpers to split data off from one shard to another, to migrate a shard across nodes, to synchronize changes across nodes, etc.

As the name suggests, this approach provides an interface to data, that may in reality be scattered across various schemas in various database clusters, and presents it as a coherent and easily accessible patchwork of tables, resulting in a database resembling a quilt.

Full documentation is at https://djanquiltdb.readthedocs.io/.

Installation

pip install djanquiltdb

Add it to INSTALLED_APPS:

INSTALLED_APPS = (
    ...
    'djanquiltdb',
    ...
)

Point every connection at the bundled backend, and routing at the router:

DATABASES = {
    'default': dj_database_url.parse(DATABASE_URL, engine='djanquiltdb.postgresql_backend'),
}

DATABASE_ROUTERS = ['djanquiltdb.router.DynamicDbRouter']

Then declare a shard model of your own and name it in the QUILT_DB setting:

# myapp/models.py
from djanquiltdb.models import BaseShard


class Shard(BaseShard):
    class Meta:
        app_label = 'myapp'

# settings.py
QUILT_DB = {
    'SHARD_CLASS': 'myapp.models.Shard',
}

Models are placed with the decorators in djanquiltdb.decorators; an undecorated model stays on the default node’s public schema. manage.py migrate is shard-aware, and applies each migration wherever its models live.

To declare Postgres views and functions the same way, install the extra:

pip install djanquiltdb[postgres-objects]

To track model history with django-pghistory the same way, install the extra:

pip install djanquiltdb[pghistory]

See the installation docs for the template schema that every node needs, and the settings reference for the full set of settings, including the mapping model, the session backend and the middleware.

Requirements

• Python 3.14

• Django 6.0 or 6.1

• PostgreSQL 17 or 18

Development

This package is developed in the DjanQuiltDB repository beside its in-tree plugins, each shipped as a distribution of its own.

pre-commit install

pre-commit run --all-files

docker compose run --rm test tox -m core

cp packages/djanquiltdb/tests/secrets.json.example packages/djanquiltdb/tests/secrets.json

docker compose run --no-deps --rm test tox -e core-build

docker compose run --no-deps --rm test tox -e docs

Attribution

This is an independently maintained fork of the patchman-django-sharding library originally created and maintained by Patchman B.V. (2017-2023) and Cloud Linux Software, Inc. (2023-2025).