Database strategies¶

A database strategy decides how a tenant's database is reached, created and dropped. Each Client names its strategy in db_strategy; the strategy reads its parameters from the client's encrypted db_params and its db_name.

db_strategy is a StrategyField from django-strategy-field: the column stores the dotted path of a class, and reading the attribute returns an instance bound to the client:

client.db_strategy  # <TemplateOverlay object>, built as TemplateOverlay(client)
client.db_strategy.client is client  # True
client.get_db_strategy()  # same, but raises ImproperlyConfigured if the class cannot be imported

Who calls the strategy¶

ensure_db_registered() always resets TEST["NAME"] to None on what the strategy returns, so no strategy can make a test run reuse the template's test database.

TemplateOverlay¶

The built-in strategy, always registered and the default for every client: the template alias connection with the client's parameters laid over it. Its db_params are shaped like a Django DATABASES entry without NAME, which comes from client.db_name.

Missing keys, empty strings and null inherit the template's value. NAME is always client.db_name. Any other key fails validation:

{'db_params': ['Template connection + overrides does not accept NAME. Allowed keys: CONN_HEALTH_CHECKS, ..., PORT, USER.']}

Examples of db_params:

{}
{"HOST": "db2.internal", "USER": "acme", "PASSWORD": "s3cret", "OPTIONS": {"sslmode": "require"}}
{"ENGINE": "django.db.backends.mysql", "HOST": "mysql.internal", "PORT": "3306"}

Creating and dropping databases uses the resulting connection: its server and its account, which needs the right to create and drop databases.

Write your own strategy¶

Subclass DatabaseStrategy (or TemplateOverlay to keep its behaviour), declare the db_params keys it accepts, and register it.

Example: take the password from an environment variable named in db_params, so the secret is not stored in the database:

# myproject/tenancy.py
import os

from django.core.exceptions import ImproperlyConfigured
from django_db_tenants.strategies import TemplateOverlay


class EnvironmentPassword(TemplateOverlay):
    label = "Template + password from environment"
    param_keys = TemplateOverlay.settings_keys - {"PASSWORD"} | {"PASSWORD_ENV", "MAINTENANCE_DB"}

    def connection_settings(self, template):
        settings = super().connection_settings(template)
        variable = self.params.get("PASSWORD_ENV")
        if variable:
            try:
                settings["PASSWORD"] = os.environ[variable]
            except KeyError:
                raise ImproperlyConfigured(f"{variable} is not set") from None
        return settings

# settings.py
DB_TENANTS = {"DATABASE_STRATEGIES": ["myproject.tenancy.EnvironmentPassword"]}

python manage.py provision_tenant acme --name ACME --db-name acme \
    --db-strategy myproject.tenancy.EnvironmentPassword --db-params '{"PASSWORD_ENV": "ACME_DB_PASSWORD"}'

The test suite ships this exact strategy (tests/_extra/testutils/strategies.py).

The contract¶

Inside a strategy, self.client is the Client and self.params its db_params (a dict).

The DbConnectionFactory protocol declares these members. Client.get_db_strategy() is typed with it, so the callers above depend on the interface, not on DatabaseStrategy. Strategies still subclass DatabaseStrategy: the db_strategy field accepts only its registered subclasses.

Registration¶

The Client.db_strategy field accepts only registered classes, both in the admin select and in full_clean().

Registering a strategy never creates a migration: the field's choices are not part of the schema.

When a strategy class disappears¶

A client row whose strategy class cannot be imported still loads (lists, admin), with db_strategy set to None. Using it raises ImproperlyConfigured naming the missing class, and full_clean() reports the field as invalid. Keep removed strategies importable until no client uses them.

Changing a client's strategy or parameters¶

Saving the client changes its config version, so every process re-registers the connection with the new settings the next time it meets the client.

DEFAULT_STRATEGY = (
    "django_db_tenants.strategies.TemplateOverlay"
)

registry = Registry(
    DatabaseStrategy, label_attribute="label"
)

label = ''

param_keys: frozenset[str] | None = None

client = client

params: dict[str, Any]

validate() -> None

connection_settings(
    template: dict[str, Any],
) -> dict[str, Any]

create_database(if_not_exists: bool = True) -> bool

drop_database() -> None

label = 'Template connection + overrides'

settings_keys = frozenset(
    {
        "ENGINE",
        "HOST",
        "PORT",
        "USER",
        "PASSWORD",
        "OPTIONS",
        "CONN_MAX_AGE",
        "CONN_HEALTH_CHECKS",
    }
)

param_keys = settings_keys | {'MAINTENANCE_DB'}

validate() -> None

connection_settings(
    template: dict[str, Any],
) -> dict[str, Any]

create_database(if_not_exists: bool = True) -> bool

drop_database() -> None

template_settings() -> dict[str, Any]