feat: Implement thread-safe mode with Instance class

- Add Instance class that encapsulates config + connection
- Add ThreadSafetyError exception for global state access
- Add _ConfigProxy to delegate dj.config to global config
- Add _get_singleton_connection for lazy connection creation
- Update dj.conn(), dj.Schema(), dj.FreeTable() to use singleton
- Connection now stores _config reference for instance isolation
- Add DJ_THREAD_SAFE environment variable support
- Add comprehensive tests for thread-safe mode

When DJ_THREAD_SAFE=true:
- dj.config raises ThreadSafetyError
- dj.conn() raises ThreadSafetyError
- dj.Schema() raises ThreadSafetyError (without explicit connection)
- dj.FreeTable() raises ThreadSafetyError (without explicit connection)
- dj.Instance() always works for isolated contexts

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: dimitri-yatsenko

docs/design/thread-safe-mode.md

@@ -6,30 +6,34 @@ DataJoint uses global state (`dj.config`, `dj.conn()`) that is not thread-safe.
 
 ## Solution
 
-Introduce **Instance** objects that encapsulate config and connection. The `dj` module provides access to a lazily-loaded singleton instance. New isolated instances are created with `dj.Instance()`.
+Introduce **Instance** objects that encapsulate config and connection. The `dj` module provides a global config that can be modified before connecting, and a lazily-loaded singleton connection. New isolated instances are created with `dj.Instance()`.
 
 ## API
 
-### Legacy API (singleton instance)
+### Legacy API (global config + singleton connection)
 
 ```python
 import datajoint as dj
 
+# Configure credentials (no connection yet)
+dj.config.database.user = "user"
+dj.config.database.password = "password"
 dj.config.safemode = False
-dj.conn()  # Triggers singleton creation, returns connection
+
+# First call to conn() or Schema() creates the singleton connection
+dj.conn()  # Creates connection using dj.config credentials
 schema = dj.Schema("my_schema")
 
 @schema
 class Mouse(dj.Manual):
     definition = "..."
 ```
 
-Internally, `dj.config`, `dj.conn()`, and `dj.Schema()` are aliases to the singleton instance:
-- `dj.config` → `dj._singleton_instance.config`
-- `dj.conn()` → `dj._singleton_instance.connection`
-- `dj.Schema()` → `dj._singleton_instance.Schema()`
-
-The singleton is created lazily on first access to any of these.
+Internally:
+- `dj.config` → delegates to `_global_config` (with thread-safety check)
+- `dj.conn()` → returns `_singleton_connection` (created lazily)
+- `dj.Schema()` → uses `_singleton_connection`
+- `dj.FreeTable()` → uses `_singleton_connection`
 
 ### New API (isolated instance)
 
@@ -86,12 +90,13 @@ table = inst.FreeTable("db.table")    # Uses inst.connection
 export DJ_THREAD_SAFE=true
 ```
 
-`thread_safe` is read from environment/config file at module import time.
+`thread_safe` is checked dynamically on each access to global state.
 
-When `thread_safe=True`, accessing the singleton raises `ThreadSafetyError`:
+When `thread_safe=True`, accessing global state raises `ThreadSafetyError`:
 - `dj.config` raises `ThreadSafetyError`
 - `dj.conn()` raises `ThreadSafetyError`
-- `dj.Schema()` raises `ThreadSafetyError`
+- `dj.Schema()` raises `ThreadSafetyError` (without explicit connection)
+- `dj.FreeTable()` raises `ThreadSafetyError` (without explicit connection)
 - `dj.Instance()` works - isolated instances are always allowed
 
 ```python
@@ -110,26 +115,26 @@ inst.Schema("name")           # OK
 
 | Operation | `thread_safe=False` | `thread_safe=True` |
 |-----------|--------------------|--------------------|
-| `dj.config` | `_singleton.config` | `ThreadSafetyError` |
-| `dj.conn()` | `_singleton.connection` | `ThreadSafetyError` |
-| `dj.Schema()` | `_singleton.Schema()` | `ThreadSafetyError` |
+| `dj.config` | `_global_config` | `ThreadSafetyError` |
+| `dj.conn()` | `_singleton_connection` | `ThreadSafetyError` |
+| `dj.Schema()` | Uses singleton | `ThreadSafetyError` |
+| `dj.FreeTable()` | Uses singleton | `ThreadSafetyError` |
 | `dj.Instance()` | Works | Works |
 | `inst.config` | Works | Works |
 | `inst.connection` | Works | Works |
 | `inst.Schema()` | Works | Works |
 
-## Singleton Lazy Loading
+## Lazy Loading
 
-The singleton instance is created lazily on first access:
+The global config is created at module import time. The singleton connection is created lazily on first access:
 
 ```python
-dj.config          # Creates singleton, returns _singleton.config
-dj.conn()          # Creates singleton, returns _singleton.connection
-dj.Schema("name")  # Creates singleton, returns _singleton.Schema("name")
+dj.config.database.user = "user"  # Modifies global config (no connection yet)
+dj.config.database.password = "pw"
+dj.conn()          # Creates singleton connection using global config
+dj.Schema("name")  # Uses existing singleton connection
 ```
 
-All three trigger creation of the same singleton instance.
-
 ## Usage Example
 
 ```python
@@ -167,7 +172,7 @@ Mouse().delete()  # Uses inst.config.safemode
 ```python
 class Instance:
     def __init__(self, host, user, password, port=3306, **kwargs):
-        self.config = Config()  # Fresh config with defaults
+        self.config = _create_config()  # Fresh config with defaults
         # Apply any config overrides from kwargs
         self.connection = Connection(host, user, password, port, ...)
         self.connection._config = self.config
@@ -179,58 +184,74 @@ class Instance:
         return FreeTable(self.connection, full_table_name)
 ```
 
-### 2. Singleton with lazy loading
+### 2. Global config and singleton connection
 
 ```python
 # Module level
-_thread_safe = _load_thread_safe_from_env_or_config()
-_singleton_instance = None
+_global_config = _create_config()  # Created at import time
+_singleton_connection = None       # Created lazily
 
-def _get_singleton():
-    if _thread_safe:
+def _check_thread_safe():
+    if _load_thread_safe():
         raise ThreadSafetyError(
             "Global DataJoint state is disabled in thread-safe mode. "
             "Use dj.Instance() to create an isolated instance."
         )
-    global _singleton_instance
-    if _singleton_instance is None:
-        _singleton_instance = Instance(
-            host=_load_from_env_or_config("database.host"),
-            user=_load_from_env_or_config("database.user"),
-            password=_load_from_env_or_config("database.password"),
+
+def _get_singleton_connection():
+    _check_thread_safe()
+    global _singleton_connection
+    if _singleton_connection is None:
+        _singleton_connection = Connection(
+            host=_global_config.database.host,
+            user=_global_config.database.user,
+            password=_global_config.database.password,
             ...
         )
-    return _singleton_instance
+        _singleton_connection._config = _global_config
+    return _singleton_connection
 ```
 
-### 3. Legacy API as aliases
+### 3. Legacy API with thread-safety checks
 
 ```python
-# dj.config -> singleton.config
+# dj.config -> global config with thread-safety check
 class _ConfigProxy:
     def __getattr__(self, name):
-        return getattr(_get_singleton().config, name)
+        _check_thread_safe()
+        return getattr(_global_config, name)
     def __setattr__(self, name, value):
-        setattr(_get_singleton().config, name, value)
+        _check_thread_safe()
+        setattr(_global_config, name, value)
 
 config = _ConfigProxy()
 
-# dj.conn() -> singleton.connection
+# dj.conn() -> singleton connection
 def conn():
-    return _get_singleton().connection
-
-# dj.Schema() -> singleton.Schema()
-def Schema(name, **kwargs):
-    return _get_singleton().Schema(name, **kwargs)
-
-# dj.FreeTable() -> singleton.FreeTable()
-def FreeTable(full_table_name):
-    return _get_singleton().FreeTable(full_table_name)
+    return _get_singleton_connection()
+
+# dj.Schema() -> uses singleton connection
+def Schema(name, connection=None, **kwargs):
+    if connection is None:
+        _check_thread_safe()
+        connection = _get_singleton_connection()
+    return _Schema(name, connection=connection, **kwargs)
+
+# dj.FreeTable() -> uses singleton connection
+def FreeTable(conn_or_name, full_table_name=None):
+    if full_table_name is None:
+        # Called as FreeTable("db.table")
+        _check_thread_safe()
+        return _FreeTable(_get_singleton_connection(), conn_or_name)
+    else:
+        # Called as FreeTable(conn, "db.table")
+        return _FreeTable(conn_or_name, full_table_name)
 ```
 
 ### 4. Refactor internal code
 
 All internal code uses `self.connection._config` instead of global `config`:
+- Connection stores reference to its config as `self._config`
 - Tables access config via `self.connection._config`
 - This works uniformly for both singleton and isolated instances
 

src/datajoint/__init__.py

@@ -23,6 +23,7 @@
     "config",
     "conn",
     "Connection",
+    "Instance",
     "Schema",
     "VirtualModule",
     "virtual_schema",
@@ -52,6 +53,7 @@
     "errors",
     "migrate",
     "DataJointError",
+    "ThreadSafetyError",
     "logger",
     "cli",
     "ValidationResult",
@@ -72,17 +74,158 @@
     NpyRef,
 )
 from .blob import MatCell, MatStruct
-from .connection import Connection, conn
-from .errors import DataJointError
+from .connection import Connection
+from .errors import DataJointError, ThreadSafetyError
 from .expression import AndList, Not, Top, U
+from .instance import Instance, _ConfigProxy, _get_singleton_connection, _global_config, _check_thread_safe
 from .logging import logger
 from .objectref import ObjectRef
-from .schemas import Schema, VirtualModule, list_schemas, virtual_schema
-from .settings import config
-from .table import FreeTable, Table, ValidationResult
+from .schemas import Schema as _Schema, VirtualModule, list_schemas, virtual_schema
+from .table import FreeTable as _FreeTable, Table, ValidationResult
 from .user_tables import Computed, Imported, Lookup, Manual, Part
 from .version import __version__
 
+# =============================================================================
+# Singleton-aware API
+# =============================================================================
+# config is a proxy that delegates to the singleton instance's config
+config = _ConfigProxy()
+
+
+def conn(
+    host: str | None = None,
+    user: str | None = None,
+    password: str | None = None,
+    *,
+    reset: bool = False,
+    use_tls: bool | dict | None = None,
+) -> Connection:
+    """
+    Return a persistent connection object.
+
+    When called without arguments, returns the singleton connection.
+    When connection parameters are provided, creates a new Connection.
+
+    Parameters
+    ----------
+    host : str, optional
+        Database hostname.
+    user : str, optional
+        Database username.
+    password : str, optional
+        Database password.
+    reset : bool, optional
+        If True, reset existing connection. Default False.
+    use_tls : bool or dict, optional
+        TLS encryption option.
+
+    Returns
+    -------
+    Connection
+        Database connection.
+
+    Raises
+    ------
+    ThreadSafetyError
+        If thread_safe mode is enabled and using singleton.
+    """
+    # If any connection params provided, use legacy behavior
+    if host is not None or user is not None or password is not None or reset:
+        from .connection import conn as _legacy_conn
+
+        return _legacy_conn(host, user, password, reset=reset, use_tls=use_tls)
+
+    # Otherwise use singleton connection
+    return _get_singleton_connection()
+
+
+def Schema(
+    schema_name: str | None = None,
+    context: dict | None = None,
+    *,
+    connection: Connection | None = None,
+    create_schema: bool = True,
+    create_tables: bool | None = None,
+    add_objects: dict | None = None,
+) -> _Schema:
+    """
+    Create a Schema for binding table classes to a database schema.
+
+    When connection is not provided, uses the singleton connection.
+
+    Parameters
+    ----------
+    schema_name : str, optional
+        Database schema name.
+    context : dict, optional
+        Namespace for foreign key lookup.
+    connection : Connection, optional
+        Database connection. Defaults to singleton connection.
+    create_schema : bool, optional
+        If False, raise error if schema doesn't exist. Default True.
+    create_tables : bool, optional
+        If False, raise error when accessing missing tables.
+    add_objects : dict, optional
+        Additional objects for declaration context.
+
+    Returns
+    -------
+    Schema
+        A Schema bound to the specified connection.
+
+    Raises
+    ------
+    ThreadSafetyError
+        If thread_safe mode is enabled and using singleton.
+    """
+    if connection is None:
+        # Use singleton connection - will raise ThreadSafetyError if thread_safe=True
+        _check_thread_safe()
+        connection = _get_singleton_connection()
+
+    return _Schema(
+        schema_name,
+        context=context,
+        connection=connection,
+        create_schema=create_schema,
+        create_tables=create_tables,
+        add_objects=add_objects,
+    )
+
+
+def FreeTable(conn_or_name, full_table_name: str | None = None) -> _FreeTable:
+    """
+    Create a FreeTable for accessing a table without a dedicated class.
+
+    Can be called in two ways:
+    - ``FreeTable("schema.table")`` - uses singleton connection
+    - ``FreeTable(connection, "schema.table")`` - uses provided connection
+
+    Parameters
+    ----------
+    conn_or_name : Connection or str
+        Either a Connection object, or the full table name if using singleton.
+    full_table_name : str, optional
+        Full table name when first argument is a connection.
+
+    Returns
+    -------
+    FreeTable
+        A FreeTable instance for the specified table.
+
+    Raises
+    ------
+    ThreadSafetyError
+        If thread_safe mode is enabled and using singleton.
+    """
+    if full_table_name is None:
+        # Called as FreeTable("db.table") - use singleton connection
+        _check_thread_safe()
+        return _FreeTable(_get_singleton_connection(), conn_or_name)
+    else:
+        # Called as FreeTable(conn, "db.table") - use provided connection
+        return _FreeTable(conn_or_name, full_table_name)
+
 # =============================================================================
 # Lazy imports — heavy dependencies loaded on first access
 # =============================================================================