Glossary¶

Terms used across the developer's guide, in alphabetical order.

Client¶

The row in the shared database that describes one tenant: name, slug, status, database strategy and its parameters. Model: django_db_tenants.models.Client. See the Client model reference.

Config version¶

A string that changes every time a Client row is saved (Client.config_version(), built from updated_at). Each process compares it with the version it registered, and re-registers the tenant's connection when they differ. See Runtime registration.

Control host¶

A host name listed in DB_TENANTS["CONTROL_HOSTS"]. Requests to it get no tenant and are served from the shared database, typically for the admin site (the control plane).

Database strategy¶

The class that decides how a tenant's database is reached, created and dropped, chosen per client in Client.db_strategy (a django-strategy-field StrategyField) and configured by Client.db_params. The built-in one, TemplateOverlay, lays the client's parameters over the template alias connection. See Database strategies.

Exempt path¶

A URL path prefix listed in DB_TENANTS["EXEMPT_PATHS"] (default /healthz). The middleware skips tenant resolution for it.

Fernet¶

The symmetric encryption scheme from the cryptography package. The library uses it to encrypt Client.db_params (database passwords and other strategy secrets) at rest. See Encryption.

Provisioning¶

Onboarding a client's database: create it (through the client's database strategy), run migrations on it and mark the client active. Done by provision(), the provision_tenant command or the admin action. See Provisioning.

Resolver¶

A callable resolver(request) -> Client | None that tells the middleware which tenant a request belongs to. Set with DB_TENANTS["RESOLVER"]. See Resolvers.

Runtime registration¶

Adding a tenant's connection settings, built by the client's database strategy, to django.db.connections while the process runs, by ensure_db_registered(). See Architecture.

Shared apps¶

The Django apps listed in DB_TENANTS["SHARED_APPS"] (default: only django_db_tenants). Their tables live only in the shared database.

Shared database¶

The database behind the template alias. It holds the client registry and, by default, a copy of the tenant-app tables for control-host logins.

Template alias¶

The DATABASES alias (DB_TENANTS["TEMPLATE_ALIAS"], default "default") that is the shared database and the starting point of tenant connections: every database strategy receives a copy of its settings, and the built-in TemplateOverlay lays the client's db_params over them.

Tenant¶

A customer whose data lives in its own database. Represented by a Client row; inside the code "tenant" and "client" name the same thing.

Tenant alias¶

The django.db.connections alias of a tenant's database. It is always the client's slug.

Tenant apps¶

Every installed app that is not a shared app, including django.contrib.auth, sessions and contenttypes. Their tables live in each tenant database.

Tenant context¶

The tenant active for the running code, held in a ContextVar. Set by the middleware for a request, or by tenant_context() / @with_tenant for other code. The database router reads it. See Context.

Tenant database¶

The database of one tenant, named by Client.db_name and reachable under the tenant alias.