feat: Thread-safe mode for multi-tenant applications

[dimitri-yatsenko]

Summary

Adds opt-in thread-safe mode that blocks global state access, requiring explicit connection management for multi-tenant web applications and concurrent processing.

📄 Design Specification

Key Features

Thread-Safe Mode (thread_safe setting)

• Read-only after initialization: Can only be set via DJ_THREAD_SAFE environment variable or datajoint.json config file
• When enabled, blocks all dj.config access except reading thread_safe itself
• Blocks dj.conn() singleton to prevent shared connection state

New Connection API

• Connection.from_config(): Creates connections with explicit configuration
  • Works identically whether thread_safe is on or off
  • Never falls back to global config (uses defaults for unspecified values)
  • Accepts all connection-scoped settings as parameters

Connection-Scoped Configuration (conn.config)

• ConnectionConfig class for per-connection settings
• Read/write access to: safemode, database_prefix, stores, cache, display_limit, etc.
• conn.config.override(): Context manager for temporary setting changes
• Legacy API (dj.conn()) falls back to global config for backward compatibility

Usage

# Enable thread-safe mode (deployment-time decision)
# Option 1: Environment variable
export DJ_THREAD_SAFE=true

# Option 2: datajoint.json
{"thread_safe": true}

# Create connections explicitly
conn = dj.Connection.from_config(
    host="localhost",
    user="root", 
    password="secret",
    safemode=False,
    display_limit=25
)

# Access connection-scoped settings
conn.config.safemode = False
conn.config.display_limit = 50

# Temporary overrides
with conn.config.override(safemode=False):
    # safemode disabled here
    pass
# safemode restored

# Schema requires explicit connection
schema = dj.Schema("mydb", connection=conn)

Breaking Changes

None. Thread-safe mode is opt-in and disabled by default. Existing code continues to work unchanged.

Other Fixes

• Pydantic validation: Fixed Config.__setattr__ to preserve Pydantic's validate_assignment=True
• Removed dead code: enable_python_native_blobs setting (was defined but never read)
• Removed charset setting: Database charset should be configured on the server, not client

Files Changed

• src/datajoint/settings.py - Thread-safe guards, read-only thread_safe
• src/datajoint/connection.py - ConnectionConfig, from_config(), override()
• src/datajoint/schema.py - Require explicit connection in thread-safe mode
• src/datajoint/errors.py - ThreadSafetyError exception
• tests/unit/test_thread_safe.py - Comprehensive test suite
• tests/unit/test_settings.py - Updated tests for new behavior
• docs/design/thread-safe-mode.md - Design specification

Test Plan

• All 270 unit tests pass
• Integration tests pass
• Manual testing with multi-tenant scenario

---

🤖 Generated with Claude Code

[dimitri-yatsenko]

closing for a more elegant solution