Skip to content

Commit 726007d

Browse files
docs: Add connection flow from Schema to Tables
Explains how connections propagate: - Connection → Schema → Table classes → Table instances - Schema falls back to conn() if no connection provided - Tables inherit connection from schema via _connection class attribute - In thread_safe mode, Schema("name") fails, Schema("name", connection=conn) works Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 8a51db4 commit 726007d

File tree

1 file changed

+53
-1
lines changed

1 file changed

+53
-1
lines changed

docs/design/thread-safe-mode.md

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,17 +52,69 @@ conn.config.safemode = False # Write setting (always allowed)
5252
conn.config.stores = {...} # Configure stores for this connection
5353
```
5454

55+
## Connection Flow: Schema → Tables
56+
57+
### How connections propagate
58+
59+
```
60+
Connection
61+
62+
Schema (stores connection)
63+
64+
Table classes (inherit connection from schema)
65+
66+
Table instances (access connection via class)
67+
```
68+
69+
### Schema behavior
70+
71+
```python
72+
# If connection provided, use it
73+
schema = dj.Schema("name", connection=conn) # schema.connection = conn
74+
75+
# If no connection, fall back to global conn()
76+
schema = dj.Schema("name") # schema.connection = dj.conn()
77+
```
78+
79+
### Table behavior
80+
81+
Tables automatically inherit their connection from their schema:
82+
83+
```python
84+
@schema
85+
class Mouse(dj.Manual):
86+
definition = "..."
87+
88+
# Mouse._connection is set by @schema decorator
89+
# Mouse().connection returns Mouse._connection (from schema)
90+
```
91+
92+
### In thread_safe=True mode
93+
94+
```python
95+
# This fails - conn() raises ThreadSafetyError
96+
schema = dj.Schema("name")
97+
98+
# This works - explicit connection
99+
conn = dj.Connection(host="localhost", user="u", password="p")
100+
schema = dj.Schema("name", connection=conn)
101+
102+
# Tables work automatically via schema's connection
103+
Mouse().insert(...) # Uses schema.connection.config for settings
104+
```
105+
55106
## Behavior
56107

57108
| Operation | `thread_safe=False` | `thread_safe=True` |
58109
|-----------|--------------------|--------------------|
59110
| `dj.config` read | Works | Works |
60111
| `dj.config` write | Works | Raises `ThreadSafetyError` |
61112
| `dj.conn()` | Works | Raises `ThreadSafetyError` |
62-
| `dj.Schema("name")` | Works | Raises `ThreadSafetyError` |
113+
| `dj.Schema("name")` | Works (uses `conn()`) | Raises `ThreadSafetyError` |
63114
| `dj.Connection(...)` | Works | Works |
64115
| `conn.config` read/write | Works | Works |
65116
| `Schema(..., connection=conn)` | Works | Works |
117+
| Table operations | Use `conn.config` | Use `conn.config` |
66118

67119
## Read-Only Settings
68120

0 commit comments

Comments
 (0)