[yannik131]

Closes #1048

[yannik131]

Migration guide for me

Turning eloquent model X into enum X requires these changes:

Enum implementation

Assuming all possible model values are written into the corresponding X table upon migration

• Find values by connecting to the db (docker compose exec database psql -U biigle -d biigle -c "select * from X;") and by looking at DB::table('X')->insert statements, insertion order corresponds to values, 1-indexed
• Assign integer values to each existing case using the same values and implement
• cId() returning the value of case c for each case
• c() returning the case cfor each case
• label() returning the case name like it was previously written in the DB
• toArray() returning ['id' => xId(), 'name' => label()]

Creating the migration

Find all foreign keys and their constraint names using docker compose exec database psql -U biigle -d biigle -c "\d+ X", then

• (make sure enum and database table are 1:1 congruent on present IDs/values as a failsafe: MAYBE if migrations don't fill the tables completely?)
• drop all fk constraints
• drop the table itself

Editing old migrations

Instead of removing the tables from the migrations, it's easier to keep them and replace eloquent model method calls X::method() (all(), insert(), ...) with DB::table('X')->method().

Common needed replacements

X is the name of the model and enum, x is lowercase name, x_id is (usually) the name of the FK

• X::all() -> collect(X::cases())->map->toArray() (add ->values() if PHPStan is pedantic)
• $val = X::findOrFail($caseId) -> $val = X::tryFrom((int) $caseId); abort_if($val === null, 404);
• similarly, other model-specific query patterns X::find(), whereHas(), with(), whereRelation()
• collect([X::case1(), X::case2(), ..])-> collect(...)->map->toArray()
• FormRequest validation rules like 'x_id' => 'integer|exists:x,id' -> 'x_id' => ['integer', Rule::in(array_column(X::cases(), 'value'))]
• $this->belongsTo(X::class) -> X::from($this->x_id)
• Eloquent model has x() method -> getXAttribute(): X. This way $object->x still works
• blade files: {!! Biigle\X::x() !!} -> @json(Biigle\X::x()->toArray())
• $x->id -> $x->value
• $x->name -> $x->label()
• $object->x()->associate(Biigle\X::case()) -> $object->x_id = X::caseId()
• remove DB-specific X-tests
• XTest::create() -> X::case() (find out default case or just choose one)
• X::pluck('id', 'name') -> collect(X::cases())->mapWithKeys(fn (X $x) => [$x->label() => $x->value])
• Delete factory XFactory, replace X::factory() calls with some default X::case1Id()
• Remove eager loading statements ->with('x') from DB queries

[yannik131]

@mzur I fixed the remaining things you mentioned I think. Let me know if I missed something or if there is anything else.
On a side note, tests kept failing because #1570 was merged into master, causing a test on the CI pipeline to fail without giving me a merge conflict. Took me a while to understand I had to merge the current master to get the failing testStoreLabelTreeNotAvailableForOtherImage test 😄

[yannik131]

@mzur Created all PRs, see #1551 (comment)

[mzur]

This is finished now I guess. We want to test this (and the migrations) on the staging instance but since the de.NBI cloud is offline it will have to wait.

Copying the list of companion PRs (checked are ready):

• ananas: biigle/ananas#69
• metadata-coco: biigle/metadata-coco#16
• user-disks: biigle/user-disks#60
• user-storage: biigle/user-storage#90
• maia: biigle/maia#241
• metadata-ifdo: biigle/metadata-ifdo#11
• laserpoints: biigle/laserpoints#132
• ptp: biigle/ptp#47
• color-sort: biigle/color-sort#81
• demo: biigle/demo#14
• metrics: biigle/metrics#6
• auth-haai: biigle/auth-haai#3
• auth-lslogin: biigle/auth-lslogin#12
• auth-nfdi: biigle/auth-nfdi#3
• geo: biigle/geo#89

[mzur]

@yannik131 The maia PR is not ready yet and geo is still missing.

[mzur]

Wait, geo just wasn't linked above.

[yannik131]

I finished the maia PR (biigle/maia#241) and broke EnumMigrationHelper into smaller functions.

[mzur]

Everything looks good! I gave it a spin in our staging instance and applied the migrations to a prod-like DB snapshot and everything worked smoothly and fast.