Thread-safe mode for multi-tenant applications

[dimitri-yatsenko]

Summary

Add thread-safe mode for multi-tenant applications. When enabled via DJ_THREAD_SAFE=true, global state access (dj.config, dj.conn()) raises ThreadSafetyError, forcing explicit connection management via dj.Instance().

See spec: docs/design/thread-safe-mode.md

Global state audit

Reviewed all module-level mutable state for thread-safety implications:

#	Global state	Location	Resolution
1	config singleton	settings.py:979	Guarded — blocked in thread-safe mode, use Instance()
2	conn() singleton	connection.py:108	Guarded — blocked in thread-safe mode, use Instance()
3	_codec_registry	codecs.py:47-48	Safe — immutable after import (import lock + idempotent entry points)
4	Logging side effects	logging.py	Low risk — standard Python logging, no DataJoint-specific state
5	use_32bit_dims	blob.py:65	Low risk — deserialization flag, rarely changed at runtime
6	compression dict	blob.py:61	Low risk — decompressor registry, effectively read-only
7	_lazy_modules	__init__.py:92	Low risk — import caching, protected by import lock
8	ADAPTERS dict	adapters/__init__.py:16	Low risk — backend registry, effectively read-only

Implementation

• dj.Instance() class providing isolated config + connection + Schema
• ThreadSafetyError raised when accessing global singletons in thread-safe mode
• DJ_THREAD_SAFE environment variable to enable
• Codec registry documented as thread-safe by design (no per-instance isolation needed)

Usage

export DJ_THREAD_SAFE=true

inst = dj.Instance(
    host="localhost",
    user="user",
    password="password",
)
schema = inst.Schema("my_schema")

🤖 Generated with Claude Code

[mweitzel]

The DJ_THREAD_SAFE protects against the singleton API from being used, but it doesn't prevent the Instances from setting the same global config object in them.

Overall this is fantastic. Minor issue with race condition in initialization. I've issued a PR to address it.

[mweitzel]

Can this configurable via python instead of just os.env?

[mweitzel]

Something like "import, set threadsafe, then use api" without the os env needs.

[dimitri-yatsenko]

We considered adding a set_thread_safe() Python API but decided against it. Calling a function to mutate a global variable is itself not a thread-safe operation — it defeats the purpose. Thread-safe mode is an infrastructure decision that must be made before any threads spawn, so it belongs in the environment (DJ_THREAD_SAFE=true) or config file, not in runtime code.

[dimitri-yatsenko]

See reply above — we decided against a Python API for this. Mutating a global to enable thread-safety is self-contradictory. DJ_THREAD_SAFE stays as env-var/config-file only.

[mweitzel]

Here's where we need to provide the appropriate backend as well, or else it just grabs the global one.

[dimitri-yatsenko]

Fixed. Instance.__init__ now passes backend=self.config.database.backend and config_override=self.config to the Connection constructor.

[mweitzel]

I'm not sure what you mean "but Instance sets its own" ..here it is still setting _config to the same global one (from .settings import config)

[dimitri-yatsenko]

The module-level config from settings.py is created at import time from env vars and config file — it's not mutable shared state being raced on. But you're right that Connection needs to accept its config at construction: when created by an Instance, it should use the Instance's config (which may differ from the module-level one). Fixed — Connection.__init__ now accepts backend and config_override keyword arguments, matching the approach in your illustrative PR.

[mweitzel]

Because this is inside __init__, it doesn't matter if the adapter is set after creation. It still grabs from the global here, in initialization.

[dimitri-yatsenko]

Same as above — the config is fixed at import time, not a race. But the fix is the same: Connection now accepts config_override at construction so it uses the right config when created by an Instance.

[mweitzel]

This really needs to accept backend and config at instantiation.

[mweitzel]

I've issued a PR to illustrate a fix

[dimitri-yatsenko]

Done. Connection.__init__ now accepts backend and config_override keyword arguments. All three call sites (Instance.__init__, _get_singleton_connection, and dj.conn()) pass config explicitly.

[dimitri-yatsenko]

Thanks for the illustrative PR — the approach matches yours. Addressed in datajoint#1404.

[mweitzel]

This hard coded sql is mysql specific, it can be avoided if instead of _get_singleton_connection you called something like sql = connection.adapter.list_schemas_sql() ; return [r[0] for r in connection.query(sql)]

[mweitzel]

This method isn't protected by the "thread safe" os.env guard, but also doesn't need to be if it reads entirely from the instances which are passed instead of the global singleton here.

[dimitri-yatsenko]

Good catch. list_schemas_sql() already exists on the adapter interface. The hardcoded SQL also has a MySQL-specific filter (WHERE schema_name <> "information_schema") that the adapter methods handle properly. We'll update list_schemas() to use connection.adapter.list_schemas_sql().

[dimitri-yatsenko]

Right — list_schemas() already accepts an optional connection argument. When one is passed (e.g. from an Instance), it bypasses the singleton entirely. The thread-safe guard only triggers via _get_singleton_connection() when no connection is provided, which is the correct behavior.

[mweitzel]

Also, in _create_config() it warns "No datajoint.json found", but that is not relevant in that mode. You could probably have an if/else and config = None if _load_thread_safe

[dimitri-yatsenko]

The warning comes from _create_config() which runs at import time (line 972), before thread-safe mode is even checked. In thread-safe mode, Instance() calls _create_config() too — to get a fresh config with defaults from env vars. The warning is about the absence of a config file, which is relevant regardless of mode (env vars alone are a valid configuration path, but the warning helps users who forgot to create one). We could suppress it, but it's informational and doesn't affect behavior.

[mweitzel]

I see a few comments "done" or "fixed" but did you push the changes?

[dimitri-yatsenko]

Superseded by datajoint#1404