Skip to content

Commit 92ec140

Browse files
docs: highlight backend parameter (mysql/postgresql) in thread-safe spec
Add backend parameter to the Instance API table, document default ports per backend, and show usage examples for MySQL, PostgreSQL, and custom port configurations. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 5961f05 commit 92ec140

1 file changed

Lines changed: 33 additions & 4 deletions

File tree

src/reference/specs/thread-safe-mode.md

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ DataJoint provides two patterns for database access:
1717
### `dj.Instance`
1818

1919
```python
20-
dj.Instance(host, user, password, port=None, use_tls=None, **kwargs)
20+
dj.Instance(host, user, password, port=None, use_tls=None, backend=None, **kwargs)
2121
```
2222

2323
Creates an isolated config and connection pair.
@@ -27,10 +27,39 @@ Creates an isolated config and connection pair.
2727
| `host` | `str` || Database hostname (required) |
2828
| `user` | `str` || Database username (required) |
2929
| `password` | `str` || Database password (required) |
30-
| `port` | `int` | from config | Database port |
30+
| `port` | `int` | from config | Database port (see backend defaults below) |
3131
| `use_tls` | `bool \| dict` | `None` | TLS configuration |
32+
| `backend` | `str` | from config | `"mysql"` or `"postgresql"` |
3233
| `**kwargs` ||| Config overrides (see below) |
3334

35+
#### Backend selection
36+
37+
The `backend` parameter selects the database engine. When set, it also determines the default port:
38+
39+
| Backend | Default port |
40+
|---------|-------------|
41+
| `"mysql"` | 3306 |
42+
| `"postgresql"` | 5432 |
43+
44+
If `backend` is omitted, it defaults to `config.database.backend` (which itself defaults to `"mysql"` unless overridden by environment or config file). An explicit `port` always takes precedence over the backend default.
45+
46+
```python
47+
# MySQL (default)
48+
inst = dj.Instance(host="db.example.com", user="root", password="secret")
49+
50+
# PostgreSQL — port defaults to 5432
51+
inst = dj.Instance(
52+
host="db.example.com", user="postgres", password="secret",
53+
backend="postgresql",
54+
)
55+
56+
# PostgreSQL on a non-standard port
57+
inst = dj.Instance(
58+
host="db.example.com", user="postgres", password="secret",
59+
backend="postgresql", port=5433,
60+
)
61+
```
62+
3463
**Config overrides:** Any keyword argument that matches a config attribute is applied to the Instance's config. Use double underscores for nested settings:
3564

3665
```python
@@ -165,13 +194,13 @@ schema.drop() reads self.connection._config["safemode"] → False ✓
165194

166195
```python
167196
Connection(host, user, password, port, use_tls,
168-
backend="mysql", # explicit backend selection
197+
backend="mysql", # "mysql" or "postgresql"
169198
config_override=inst.config) # use this config, not the global
170199
```
171200

172201
When `config_override` is provided, the Connection uses it for all config reads (port, charset, reconnect, query cache, etc.). When omitted, it falls back to the module-level `settings.config`.
173202

174-
When `backend` is provided, it is used directly. When omitted, the backend is read from `self._config["database.backend"]`.
203+
When `backend` is provided, it selects the database adapter directly (`"mysql"``pymysql`, `"postgresql"``psycopg`). When omitted, the backend is read from `self._config["database.backend"]` (default: `"mysql"`).
175204

176205
### Connection-scoped config reads
177206

0 commit comments

Comments
 (0)