Skip to content

Commit 05b70fb

Browse files
docs: Address mixed connections and override() behavior
- Mixed scenarios: dj.config affects global connection schemas only - Explicit connection schemas have independent config - dj.config.override() affects only schemas using dj.conn() - conn.config.override() affects only that connection's schemas - In thread_safe=True: dj.config.override() raises ThreadSafetyError Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent ba637d5 commit 05b70fb

File tree

1 file changed

+63
-3
lines changed

1 file changed

+63
-3
lines changed

docs/design/thread-safe-mode.md

Lines changed: 63 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,18 +108,78 @@ self.connection.config.display.limit
108108
self.connection.config.stores
109109
```
110110

111+
### In thread_safe=False mode (default)
112+
113+
Schemas without explicit connection use global connection, controlled by `dj.config`:
114+
115+
```python
116+
schema = dj.Schema("name") # Uses dj.conn()
117+
# schema.connection.config IS dj.config (same object)
118+
# All tables controlled by dj.config uniformly
119+
120+
dj.config.safemode = False # Affects all tables in schema
121+
Mouse().delete() # Uses dj.config.safemode
122+
```
123+
124+
### Mixed connections (thread_safe=False)
125+
126+
When some schemas use global connection and others use explicit connections:
127+
128+
```python
129+
# Schema using global connection
130+
schema1 = dj.Schema("lab") # schema1.connection.config IS dj.config
131+
132+
# Schema using explicit connection
133+
conn = dj.Connection(host="localhost", user="u", password="p")
134+
schema2 = dj.Schema("analysis", connection=conn) # schema2.connection.config is independent
135+
136+
# dj.config affects only schema1
137+
dj.config.safemode = False # Affects schema1 tables
138+
Mouse().delete() # safemode=False (from dj.config)
139+
140+
# conn.config affects only schema2
141+
conn.config.safemode = True # Affects schema2 tables
142+
Analysis().delete() # safemode=True (from conn.config)
143+
144+
# They are independent
145+
dj.config.safemode # False
146+
conn.config.safemode # True
147+
```
148+
149+
### override() behavior
150+
151+
```python
152+
# Global config override - affects schemas using dj.conn()
153+
with dj.config.override(safemode=False):
154+
Mouse().delete() # safemode=False (schema1, global connection)
155+
Analysis().delete() # safemode=True (schema2, unchanged - has own config)
156+
157+
# Connection-scoped override - affects only that connection
158+
with conn.config.override(safemode=False):
159+
Mouse().delete() # safemode=True (schema1, unchanged - uses dj.config)
160+
Analysis().delete() # safemode=False (schema2, overridden)
161+
```
162+
111163
### In thread_safe=True mode
112164

113165
```python
114166
# This fails - conn() raises ThreadSafetyError
115167
schema = dj.Schema("name")
116168

117-
# This works - explicit connection
169+
# This works - explicit connection with independent config
118170
conn = dj.Connection(host="localhost", user="u", password="p")
119171
schema = dj.Schema("name", connection=conn)
120172

121-
# Tables work automatically via schema's connection
122-
Mouse().insert(...) # Uses schema.connection.config for settings
173+
# Tables use connection-scoped config
174+
conn.config.safemode = False # Only affects this connection
175+
Mouse().delete() # Uses conn.config.safemode
176+
177+
# dj.config.override() raises ThreadSafetyError (modifies global state)
178+
with dj.config.override(safemode=False): # ThreadSafetyError
179+
180+
# conn.config.override() works (connection-scoped)
181+
with conn.config.override(safemode=False): # OK
182+
Mouse().delete()
123183
```
124184

125185
## Behavior

0 commit comments

Comments
 (0)