DB_CONNECTION_MUTATOR Does Not Switch Database

[rishabhsingh97]

Bug description

Type: Bug / Limitation
Component: Embedded Superset / Multi-tenancy / Database Connection
Version: 6.0.1

Summary
DB_CONNECTION_MUTATOR is documented as a hook to dynamically alter database connection parameters at runtime per user. However, it does not work for per-request tenant database switching.

Expected Behavior
When using embedded Superset with guest tokens, setting username in the guest token payload should allow DB_CONNECTION_MUTATOR to dynamically route each tenant's chart queries to their respective database (e.g., tenant1 → db_tenant1, tenant2 → db_tenant2) using the same dashboard and dataset.

Reproduction Steps
Configure embedded Superset with GUEST_ROLE_NAME and guest token

Add DB_CONNECTION_MUTATOR to config that switches uri.database based on username

def DB_CONNECTION_MUTATOR(uri, params, username, security_manager, source):
    import logging
    logger = logging.getLogger(__name__)

    logger.info("[DB_CONNECTION_MUTATOR] source=%s username=%s original_db=%s is_guest=%s", source, username, uri.database, security_manager.is_guest_user())

    if security_manager.is_guest_user():
        guest_user = security_manager.get_current_guest_user_if_guest()
        uri = uri.set(database=username) # for tenants with separate DBs named after their username
        logger.info("[DB_CONNECTION_MUTATOR] switched DB to: %s", uri.database)
    else:
        logger.info("[DB_CONNECTION_MUTATOR] no DB switch — not a guest user")

    return uri, params

DB_CONNECTION_MUTATOR = DB_CONNECTION_MUTATOR

Generate guest token for username tenant1 → load embedded dashboard → data loads from tenant1 DB ✓
Generate guest token for username tenant2 → load same embedded dashboard → data still loads from tenant1 DB ✗

Screenshots/recordings

Superset version

master / latest-dev

Python version

3.11

Node version

18 or greater

Browser

Chrome

Additional context

No response

Checklist

• I have searched Superset docs and Slack and didn't find a solution to my problem.
• I have searched the GitHub issue tracker and didn't find a similar bug report.
• I have checked Superset's logs for errors and if I found a relevant Python stacktrace, I included it here as text in the "additional context" section.

[dosubot]

The most likely cause of this issue is query result caching, not engine caching. Superset actually creates a fresh SQLAlchemy engine per request with NullPool [1], and DB_CONNECTION_MUTATOR is invoked fresh each time [2] — so the connection itself is being mutated correctly for each tenant.

However, by default, query result cache keys do not include the username. This means tenant2's chart request can hit tenant1's cached results if both query the same dashboard/chart with the same parameters [3].

Fix: Enable per-user query caching in your superset_config.py:

CACHE_QUERY_BY_USER = True

This adds the username to the cache key, preventing cross-tenant cache hits.

A few additional things to watch out for with guest token multi-tenancy:

1. GLOBAL_ASYNC_QUERIES + guest token RLS has documented cache key isolation bugs that can cause data leakage across guest sessions [4]. If you're using async queries, test carefully or disable this flag.

2. Empty username in guest tokens can cause RLS rules to silently fail because the security manager returns None for the guest user [5]. Make sure your guest token always has a non-empty user.username.

3. SQL Lab context bug: security_manager.current_user can return None in certain contexts. Using the username parameter passed directly to DB_CONNECTION_MUTATOR (as you're doing) is the safer approach [6].

Your logs showing the mutator firing correctly support this diagnosis — the DB switch is happening, but a cached result from tenant1 is being served to tenant2 before the query even reaches the database.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}
   

[rishabhsingh97]

@dosu still not working!
i have added - CACHE_QUERY_BY_USER = True

[rishabhsingh97]

@dosu Is is throwing correct error incase the database not exists but if exisitng is not pointing to it

[rishabhsingh97]

@dosu CACHE_QUERY_BY_USER = True working with guest user also ?

[dosubot]

CACHE_QUERY_BY_USER does work with guest users, but only if each guest token has a unique username. Here's the key issue:

The cache key uses g.user.username to differentiate users [1]. For guest users, the GuestUser class sets the username from the JWT token's user claim, defaulting to "guest_user" if not provided [2]:

self.username = user.get("username", "guest_user")

So if your guest tokens for tenant1 and tenant2 both resolve to the same username (e.g., both are "guest_user", or both happen to share a username), they'll share the same cache key — and tenant2 will get tenant1's cached results.

The fix: Ensure each tenant's guest token has a distinct username value, e.g.:

guest_token_payload = {
    "user": {
        "username": f"tenant_{tenant_id}",  # MUST be unique per tenant
        "first_name": "Guest",
        "last_name": "User"
    },
    "resources": [...],
    "rls_rules": [...]
}

Also important: cache checks happen BEFORE DB_CONNECTION_MUTATOR is ever called [3]. On a cache hit, Superset returns the cached result immediately without creating a database connection at all — so the mutator never fires. This explains why you see the mutator correctly throwing errors for non-existent databases (cache miss → mutator runs → error) but getting wrong data for existing databases (cache hit → stale result returned → mutator never called).

To summarize what you need:

1. CACHE_QUERY_BY_USER = True ✅ (you already have this)
2. Unique username per tenant in every guest token — this is the missing piece
3. Optionally, add a GUEST_TOKEN_VALIDATOR_HOOK to reject tokens without unique usernames [4]

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}