Surgo / django-sharding

A sharding library for Django

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Django Sharding

Django Sharding is a library and part-framework for sharding Django applications.

It helps you to scale your applications by sharding your data across multiple databases in a consistent way.

Circle CI PyPI version PyPi downloads Coverage Status

What is Sharding?

Sharding is a way of horizontally partitioning your data by storing different rows of the same table in multiple tables across multiple databases. This helps to increase the number of connections to a given resource as well as improves read performance of your application.

Read The Documentation

For information about how to setup sharding in your application, read the documentation.

Developer Experience

I wrote this library after working on this problem for Wave and not being able to find a library that suited our needs. What we were looking for was something that was powerful, extensible and customizable. This library was created for just that purpose and includes at least one implimentation of each part of the pipeline with room to replace any individual components.


The package was influenced by my experiences at Wave as well as the help and code of my co-workers.


Check out the installation section of the docs for basic package setup.

Basis Setup & Usage

Sharding by User

Select a model to shard by and open up the file. Here we'll use the user model:

from django.contrib.auth.models import AbstractUser

from django_sharding_library.models import ShardedByMixin

class User(AbstractUser, ShardedByMixin):

Add that custom User to your settings file using the string class path:

AUTH_USER_MODEL = '<app_with_user_model>.User'

Create Your First Sharded Model

Define your new model, eg:

from django.db import models

from django_sharding_library.decorators import model_config
from django_sharding_library.fields import TableShardedIDField
from django_sharding_library.models import TableStrategyModel

class ShardedCarIDs(TableStrategyModel):

class Car(models.Model):
    id = TableShardedIDField(primary_key=True, source_table=ShardeCarIDs)
    ignition_type = models.CharField(max_length=120)
    company = models.ForeignKey('companies.Company')

    def get_shard(self):

Running migrations

Run them as normal, for example:

./ makemigrations <app_name>

# To let django run the migrations in all the right places.
./ migrate <app>

# To specify the database to run it on
./ migrate <app> --database=<database_alias>

Acccessing sharded data

# TODO: Update this with methods.
shard = User.shard


A sharding library for Django

License:BSD 3-Clause "New" or "Revised" License


Language:Python 99.8%Language:Shell 0.2%