django-tenant-schemas

The application implements a Semi Isolated Approach to multitenancy using PostgreSQL schemas. Instead of separate databases for each tenant, it uses a single database where each tenant has its own schema. This provides a balance between simplicity (managing one database) and performance (sharing connections, buffers, and memory).

Tenant Identification

Tenants are identified by their hostname (e.g., tenant.domain.com). This mapping is stored in a table within the public schema.

Request Lifecycle

1. A request arrives with a specific hostname.
2. The application matches the hostname against the tenant table in the public schema.
3. If a match is found, the PostgreSQL search_path is updated to include the tenant's specific schema.
4. All subsequent database queries for that request are executed within the tenant's schema.
5. If no matching tenant is found for the hostname, a 404 error is raised.

Shared vs. Tenant-Specific Data

• Tenant-Specific Applications: Most apps will reside in tenant-specific schemas, ensuring data isolation between customers.
• Shared Applications: Apps that should be accessible to all tenants (e.g., public datasets) should have their tables located in the public schema. The application ensures these are always available by automatically adding the public schema to the search_path.

To integrate django-tenant-schemas into your Django project, update your settings.py with the following configurations:

1. Database Engine: Change your default database engine to tenant_schemas.postgresql_backend.
2. Database Router: Add tenant_schemas.routers.TenantSyncRouter to DATABASE_ROUTERS to ensure apps are synced to the correct schema (shared vs. tenant).
3. Middleware: Add tenant_schemas.middleware.TenantMiddleware to the top of your MIDDLEWARE list. This ensures each request is routed to the correct schema based on the hostname.

Middleware Options:

• tenant_schemas.middleware.TenantMiddleware: Standard middleware. Returns 404 if the hostname doesn't match a valid tenant.
• tenant_schemas.middleware.SuspiciousTenantMiddleware: Returns a 400 Bad Request/DisallowedHost error if the hostname is unrecognized.
• tenant_schemas.middleware.DefaultTenantMiddleware: Serves the public tenant for unrecognized hostnames. You can subclass this to change the default schema.

Note: Ensure django.template.context_processors.request is included in your TEMPLATES context processors.

DATABASES = {
    'default': {
        'ENGINE': 'tenant_schemas.postgresql_backend',
        # ..
    }
}

DATABASE_ROUTERS = (
    'tenant_schemas.routers.TenantSyncRouter',
)

MIDDLEWARE = [
    'tenant_schemas.middleware.TenantMiddleware',
    # ...
]

A common pattern for centralized login:

1. Host the login view on the public tenant (using PUBLIC_SCHEMA_URLCONF).
2. After authentication, look up the user's associated tenant.
3. Redirect the user to their tenant's domain.

Warning on Session Cookies: If the public tenant and tenant subdomains differ, the session cookie might not be sent to the tenant.

• Solution A: Set SESSION_COOKIE_DOMAIN to a shared parent domain (e.g., .example.com).
• Solution B: Use a token-based redirect where the public login generates a one-time token for the tenant to consume.

from django.contrib.auth import authenticate, login
from django.shortcuts import redirect, render

def login_view(request):
    if request.method == 'POST':
        user = authenticate(
            request,
            username=request.POST['username'],
            password=request.POST['password'],
        )
        if user is not None:
            login(request, user)
            tenant = get_tenant_for_user(user)  # your lookup logic
            return redirect(f'https://{tenant.domain_url}/')
    return render(request, 'login.html')

By default, django-tenant-schemas determines the tenant by extracting it from the URL (e.g., mytenant.mydomain.com) using TenantMiddleware.

If you need alternative strategies—such as determining the tenant from an HTTP header, an OAuth token, or a fixed URL—you can implement custom middleware by subclassing BaseTenantMiddleware and implementing the get_tenant method.

Implementation Requirements:

1. Subclass BaseTenantMiddleware.
2. Implement get_tenant(self, model, hostname, request):
   • model: The tenant model class (referenced as TENANT_MODEL).
   • hostname: The hostname of the current request.
   • request: The current Django request object.
3. Return an instance of your TENANT_MODEL class.
4. Middleware Order: Place your custom middleware at the top of your MIDDLEWARE list in settings.py.

Note: You should only have one subclass of BaseTenantMiddleware per project. You can also extend existing middleware like TenantMiddleware to chain multiple strategies together by manipulating the super().get_tenant() call.