Skip to content

Commit 818f993

Browse files
docs: Simplify migration guide, remove excessive reversibility language
- Add backup reminder at top instead of per-phase rollback instructions - Remove "Reversible" column from phases table - Consolidate Quick Reference sections - Remove redundant "Safe/Careful" phase groupings Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 469a2e1 commit 818f993

1 file changed

Lines changed: 15 additions & 29 deletions

File tree

src/how-to/migrate-from-0x.md

Lines changed: 15 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,22 @@
22

33
Upgrade existing pipelines from DataJoint 0.x to DataJoint 2.0.
44

5+
> **Before you start:** Back up your database and use version control for code.
6+
57
## Migration Phases
68

7-
| Phase | What | Changes | Reversible |
8-
|-------|------|---------|------------|
9-
| 1. Code | Query syntax, API methods | Python code only | 100% |
10-
| 2. Settings | Config files | Files only | 100% |
11-
| 3. Numeric Types | Type names in definitions | Column comments | 100% |
12-
| 4. Blob/Attach (Internal) | Internal blob columns | Column comments | 100% |
13-
| 5. External Blob/Attach | External storage columns | FK → JSON | Yes |
14-
| 6. Filepath | Filepath columns | FK → JSON | Yes |
15-
| 7. AdaptedTypes | Custom AttributeAdapter classes | Code + column comments | 100% |
9+
| Phase | What | Changes |
10+
|-------|------|---------|
11+
| 1. Code | Query syntax, API methods, type names | Python code |
12+
| 2. Settings | Config files | Files |
13+
| 3. Numeric Types | Type labels in database | Column comments |
14+
| 4. Blob/Attach (Internal) | Internal blob columns | Column comments |
15+
| 5. External Blob/Attach | External storage columns | FK → JSON |
16+
| 6. Filepath | Filepath columns | FK → JSON |
17+
| 7. AdaptedTypes | Custom AttributeAdapter classes | Code + column comments |
1618

17-
**Phases 1-4** are trivial. Phases 3-4 only modify column comments—the actual
18-
data and column types are unchanged. You can return to DataJoint 0.x at any
19-
time without data loss.
19+
**Phases 1-4** are straightforward. Phases 3-4 only modify column comments—the
20+
actual data and column types are unchanged.
2021

2122
**Phases 5-6** convert foreign key references to external storage tables into
2223
JSON entries. The critical step is configuring stores to generate the same
@@ -176,7 +177,6 @@ grep -rn "fetch(format=" --include="*.py"
176177
grep -rn "definition\s*=" --include="*.py" -A 20 | grep -E ":\s*(int|float|smallint|tinyint|bigint|double)"
177178
```
178179

179-
**Rollback:** `git checkout` to revert code.
180180

181181
---
182182

@@ -214,7 +214,6 @@ echo "password" > .secrets/database.password
214214
chmod 600 .secrets/database.password
215215
```
216216

217-
**Rollback:** Delete `datajoint.json`, use `dj_local_conf.json`.
218217

219218
---
220219

@@ -493,43 +492,30 @@ migrate_adapted_types(schema, dry_run=True) # Preview
493492
migrate_adapted_types(schema) # Apply
494493
```
495494

496-
**Safe:** Only modifies column comments. Data unchanged. Requires code changes.
497-
498495
---
499496

500497
## Quick Reference
501498

502-
### Safe Phases (1-4, 7)
503-
504-
Phases 3-4 and 7 only modify column comments. Return to 0.x anytime.
499+
### Types (Phase 1, 3-4)
505500

506501
| 0.x | 2.0 |
507502
|-----|-----|
508503
| `int` | `int32` |
509504
| `float` | `float64` |
510505
| `longblob` | `<blob>` |
511506
| `attach` | `<attach>` |
512-
513-
### Careful Phases (5-6)
514-
515-
Convert FK references to JSON. Verify path compatibility first.
516-
517-
| 0.x | 2.0 |
518-
|-----|-----|
519507
| `blob@store` | `<blob@store>` |
520508
| `attach@store` | `<attach@store>` |
521509
| `filepath@store` | `<filepath@store>` |
522510

523-
### Code Changes (Phase 1)
511+
### API Changes (Phase 1)
524512

525513
| 0.x | 2.0 |
526514
|-----|-----|
527515
| `.fetch('KEY')` | `.keys()` |
528516
| `.fetch(as_dict=True)` | `.to_dicts()` |
529517
| `.fetch(format='frame')` | `.to_pandas()` |
530518

531-
Use an AI coding assistant to find and update deprecated patterns.
532-
533519
### AdaptedTypes (Phase 7)
534520

535521
| 0.x | 2.0 |

0 commit comments

Comments
 (0)