Django Tenants

Django tenants using PostgreSQL Schemas
Alternatives To Django Tenants
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Prisma31,7684422 hours ago4,993September 24, 20222,915apache-2.0TypeScript
Next-generation ORM for Node.js & TypeScript | PostgreSQL, MySQL, MariaDB, SQL Server, SQLite, MongoDB and CockroachDB
Graphql Engine29,82712 hours ago17June 22, 20222,119apache-2.0TypeScript
Blazing fast, instant realtime GraphQL APIs on your DB with fine grained access control, also trigger webhooks on database events.
Postgraphile11,95576992 days ago156May 25, 202267mitTypeScript
Execute one command (or mount one Node.js middleware) and get an instant high-performance GraphQL API for your PostgreSQL database!
Dbal9,07347,9463,9334 hours ago99April 05, 2022199mitPHP
Doctrine Database Abstraction Layer
Records6,956150282 months ago11February 21, 201964iscPython
SQL for Humans™
Sqlboiler5,8119717 hours ago95August 28, 202285bsd-3-clauseGo
Generate a Go ORM tailored to your database schema.
Goose3,92065995 days ago46August 29, 202256otherGo
A database migration tool. Supports SQL migrations and Go functions.
Dbmate3,43213 days ago27March 25, 202216mitGo
:rocket: A lightweight, framework-agnostic database migration tool.
Xo3,3542910 days ago2April 16, 202142mitGo
Command line tool to generate idiomatic Go code for SQL databases supporting PostgreSQL, MySQL, SQLite, Oracle, and Microsoft SQL Server
Scenic3,18211411a month ago18February 13, 202223mitRuby
Versioned database views for Rails
Alternatives To Django Tenants
Select To Compare

Alternative Project Comparisons


Build status

This application enables django powered websites to have multiple tenants via PostgreSQL schemas. A vital feature for every Software-as-a-Service (SaaS) website.

Read the full documentation here:

Django provides currently no simple way to support multiple tenants using the same project instance, even when only the data is different. Because we dont want you running many copies of your project, youll be able to have:

  • Multiple customers running on the same instance
  • Shared and Tenant-Specific data
  • Tenant View-Routing

What are schemas

A schema can be seen as a directory in an operating system, each directory (schema) with its own set of files (tables and objects). This allows the same table name and objects to be used in different schemas without conflict. For an accurate description on schemas, see PostgreSQLs official documentation on schemas.

Why schemas

There are typically three solutions for solving the multitenancy problem.

  1. Isolated Approach: Separate Databases. Each tenant has its own database.
  2. Semi Isolated Approach: Shared Database, Separate Schemas. One database for all tenants, but one schema per tenant.
  3. Shared Approach: Shared Database, Shared Schema. All tenants share the same database and schema. There is a main tenant-table, where all other tables have a foreign key pointing to.

This application implements the second approach, which in our opinion, represents the ideal compromise between simplicity and performance.

  • Simplicity: barely make any changes to your current code to support multitenancy. Plus, you only manage one database.
  • Performance: make use of shared connections, buffers and memory.

Each solution has its up and down sides. For a more in-depth discussion, see Microsofts excellent article on Multi-Tenant Data Architecture.

How it works

Tenants are identified via their host name (i.e This information is stored on a table on the public schema. Whenever a request is made, the host name is used to match a tenant in the database. If theres a match, the search path is updated to use this tenants schema. So from now on all queries will take place at the tenants schema. For example, suppose you have a tenant customer at Any request incoming at will automatically use customers schema and make the tenant available at the request. If no tenant is found, a 404 error is raised. This also means you should have a tenant for your main domain, typically using the public schema. For more information please read the setup section.

What can this app do?

As many tenants as you want

Each tenant has its data on a specific schema. Use a single project instance to serve as many as you want.

Tenant-specific and shared apps

Tenant-specific apps do not share their data between tenants, but you can also have shared apps where the information is always available and shared between all.

Tenant View-Routing

You can have different views for and, even though Django only uses the string after the host name to identify which view to serve.


Everyone loves magic! Youll be able to have all this barely having to change your code!

Setup & Documentation

This is just a short setup guide. It is strongly recommended that you read the complete version at

Your DATABASE_ENGINE setting needs to be changed to

    'default': {
        'ENGINE': 'django_tenants.postgresql_backend',
        # ..

Add the middleware django_tenants.middleware.main.TenantMainMiddleware to the top of MIDDLEWARE, so that each request can be set to use the correct schema.


Add django_tenants.routers.TenantSyncRouter to your DATABASE_ROUTERS setting, so that the correct apps can be synced depending on what's being synced (shared or tenant).


Add django_tenants to your INSTALLED_APPS.

Create your tenant model

from django.db import models
from django_tenants.models import TenantMixin, DomainMixin

class Client(TenantMixin):
    name = models.CharField(max_length=100)
    paid_until = models.DateField()
    on_trial = models.BooleanField()
    created_on = models.DateField(auto_now_add=True)

class Domain(DomainMixin):

Define on which model is your tenant model. Assuming you created Client inside an app named customers, your TENANT_MODEL should look like this:

TENANT_MODEL = "customers.Client" # app.Model
TENANT_DOMAIN_MODEL = "customers.Domain" # app.Model

Now run migrate_schemas. This will sync your apps to the public schema.

python migrate_schemas --shared

Create your tenants just like a normal django model. Calling save will automatically create and sync the schema.

from customers.models import Client, Domain

# create your public tenant
tenant = Client(schema_name='tenant1',
                name='My First Tenant',

# Add one or more domains for the tenant
domain = Domain()
domain.domain = ''
domain.tenant = tenant
domain.is_primary = True

Any request made to will now automatically set your PostgreSQLs search_path to tenant1 and public, making shared apps available too. This means that any call to the methods filter, get, save, delete or any other function involving a database connection will now be done at the tenants schema, so you shouldnt need to change anything at your views.

Youre all set, but we have left key details outside of this short tutorial, such as creating the public tenant and configuring shared and tenant specific apps. Complete instructions can be found at

Running the example project

django-tenants comes with an example project please see



I would like to thank two of the original authors of this project.

  1. Bernardo Pires under the name django-tenant-schemas.
  2. Vlada Macek under the name of django-schemata.


  • Django 2 if you want to use Django 1.11 or lower please use version 1 of django-tenants
  • PostgreSQL


If you want to run tests, you can either run (which requires access to a PostgreSQL instance, location of which you can customize using the DATABASE_HOST env variable) or use docker-compose like this:

## Start Docker service
# start docker   # with Upstart
# systemctl start docker  # with systemd

## Install docker-compose (you might want to do this in Python virtualenv)
# pip install docker-compose

## In main directory of this repo do:
docker-compose run --rm django-tenants-test  # runs django-tenants tests.
# dockerized PostgreSQL service is started implicitly

(note that upon first run the Dockerfile will be built).

Video Tutorial

An online video tutorial is available on youtube.


If this project helped you reduce development time, you can give me cake :)
Popular Schema Projects
Popular Postgresql Projects
Popular Data Formats Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.