Skip to content

Commit 7c57b26

Browse files
docs: Remove from_config(), just expose conn.config
Simpler API: - Use existing Connection() constructor - conn.config copies from global dj.config - conn.config is always mutable for per-connection settings Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 467367e commit 7c57b26

1 file changed

Lines changed: 22 additions & 26 deletions

File tree

docs/design/thread-safe-mode.md

Lines changed: 22 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ DataJoint uses global state (`dj.config`, `dj.conn()`) that is not thread-safe.
66

77
## Solution
88

9-
Add `thread_safe` mode that makes global config read-only and requires explicit connections with mutable connection-scoped settings.
9+
Add `thread_safe` mode that makes global config read-only and provides connection-scoped mutable settings via `conn.config`.
1010

1111
## API
1212

@@ -23,64 +23,60 @@ export DJ_THREAD_SAFE=true
2323
{"thread_safe": true}
2424
```
2525

26-
### Connection.from_config()
27-
28-
Creates a connection with explicit configuration. Works in both modes.
26+
### Create Connections
2927

3028
```python
31-
conn = dj.Connection.from_config(
29+
conn = dj.Connection(
3230
host="localhost",
3331
user="user",
3432
password="password",
35-
safemode=False,
36-
display_limit=25,
3733
)
34+
35+
# Modify settings per-connection
36+
conn.config.safemode = False
37+
conn.config.display_limit = 25
38+
3839
schema = dj.Schema("my_schema", connection=conn)
3940
```
4041

41-
**Parameters:**
42-
- `host` (required): Database hostname
43-
- `user` (required): Database username
44-
- `password` (required): Database password
45-
- `port`: Database port (default: 3306)
46-
- Any other setting (e.g., `safemode`, `display_limit`, `stores`)
42+
### conn.config
4743

48-
**Config creation:** Copies global `dj.config`, then applies kwargs. Creates `conn.config` which is always mutable.
44+
Every connection has a `config` attribute that:
45+
- Copies from global `dj.config` at connection time
46+
- Is always mutable (even in thread-safe mode)
47+
- Provides connection-scoped settings
4948

5049
```python
51-
conn = dj.Connection.from_config(host="localhost", user="u", password="p")
52-
conn.config.safemode = False # Always OK: conn.config is mutable
53-
conn.config.display_limit = 25 # Always OK
50+
conn.config.safemode # Read setting
51+
conn.config.safemode = False # Write setting (always allowed)
52+
conn.config.stores = {...} # Configure stores for this connection
5453
```
5554

5655
## Behavior
5756

5857
| Operation | `thread_safe=False` | `thread_safe=True` |
5958
|-----------|--------------------|--------------------|
60-
| `dj.config` read | Works | Works (read-only) |
59+
| `dj.config` read | Works | Works |
6160
| `dj.config` write | Works | Raises `ThreadSafetyError` |
6261
| `dj.conn()` | Works | Raises `ThreadSafetyError` |
6362
| `dj.Schema("name")` | Works | Raises `ThreadSafetyError` |
64-
| `Connection.from_config()` | Works | Works |
63+
| `dj.Connection(...)` | Works | Works |
6564
| `conn.config` read/write | Works | Works |
6665
| `Schema(..., connection=conn)` | Works | Works |
6766

6867
## Read-Only Settings
6968

70-
- `thread_safe`: Always read-only after initialization (set via env var or config file only)
69+
- `thread_safe`: Always read-only (set via env var or config file only)
7170
- All of `dj.config`: Read-only when `thread_safe=True`
7271

7372
## Implementation
7473

7574
1. Add `thread_safe: bool = False` field to `Config` with `DJ_THREAD_SAFE` env alias
7675
2. Make `thread_safe` always read-only after initialization
77-
3. When `thread_safe=True`, make all `dj.config` writes raise `ThreadSafetyError`
76+
3. When `thread_safe=True`, make `dj.config` writes raise `ThreadSafetyError`
7877
4. Add guard to `dj.conn()`
7978
5. Add guard to `Schema.__init__` when `connection=None`
80-
6. Add `Connection.from_config()` class method that:
81-
- Copies global `dj.config`
82-
- Applies kwargs overrides
83-
- Creates mutable `conn.config`
79+
6. Add `conn.config` to `Connection` that copies from global `dj.config`
8480
7. Add `ThreadSafetyError` exception
8581

8682
## Exceptions
@@ -92,5 +88,5 @@ class ThreadSafetyError(DataJointError):
9288

9389
Error messages:
9490
- Config write: `"Global config is read-only in thread-safe mode. Use conn.config for connection-scoped settings."`
95-
- `dj.conn()`: `"dj.conn() is disabled in thread-safe mode. Use Connection.from_config()."`
91+
- `dj.conn()`: `"dj.conn() is disabled in thread-safe mode. Use Connection() with explicit parameters."`
9692
- Schema without connection: `"Schema requires explicit connection in thread-safe mode."`

0 commit comments

Comments
 (0)