feat(db): Configuration item versioning for optimistic locking

Author: rinkp

Makefile

@@ -44,10 +44,6 @@ migrate: replenish
 migrate-to:
 		@docker compose exec -u www-data web sh -c '. ./scripts/migrate-version.sh && ./orm migrations:migrate $$migrations --object-manager doctrine.entitymanager.$$alias'
 
-migration-list: replenish
-		@docker compose exec -u www-data -T web ./orm migrations:list --object-manager doctrine.entitymanager.orm_default
-		@docker compose exec -u www-data -T web ./orm migrations:list --object-manager doctrine.entitymanager.orm_report
-
 migration-diff: replenish
 		@docker compose exec -u root web chown www-data:www-data /code/module/Database/migrations/
 		@docker compose exec -u www-data -T web ./orm migrations:diff --object-manager doctrine.entitymanager.orm_default
@@ -58,10 +54,10 @@ migration-diff: replenish
 		@docker cp "$(shell docker compose ps -q web)":/code/module/Report/migrations ./module/Report
 		@docker compose exec -u root web chown -R root:root /code/module/Report/migrations/
 
-migration-up: replenish migration-list
+migration-up: replenish
 		@docker compose exec -u www-data web sh -c '. ./scripts/migrate-version.sh && ./orm migrations:execute --up $$migrations --object-manager doctrine.entitymanager.$$alias'
 
-migration-down: replenish migration-list
+migration-down: replenish
 		@docker compose exec -u www-data web sh -c '. ./scripts/migrate-version.sh && ./orm migrations:execute --down $$migrations --object-manager doctrine.entitymanager.$$alias'
 
 seed: replenish

module/Application/src/Model/ConfigItem.php

@@ -6,6 +6,7 @@
 
 use Application\Model\Enums\ConfigNamespaces;
 use Database\Model\Trait\TimestampableTrait;
+use Database\Model\Trait\VersionTrait;
 use DateTime;
 use Doctrine\ORM\Mapping\Column;
 use Doctrine\ORM\Mapping\Entity;
@@ -34,6 +35,11 @@
 class ConfigItem
 {
     use TimestampableTrait;
+    // We implement locking by using version numbers (optimistic locking)
+    // rather than by banning other processes from locking the same row.
+    // This is more versatile and is possible because we do not care which
+    // process in the end changes the config, as long as it is only one.
+    use VersionTrait;
 
     /**
      * Primary key item ID (to avoid reference issues).

module/Database/migrations/Version20251207150548.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Database\Migrations;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+final class Version20251207150548 extends AbstractMigration
+{
+    public function getDescription(): string
+    {
+        return 'Implement versioning of config items for optimistic locking';
+    }
+
+    public function up(Schema $schema): void
+    {
+        $this->addSql('ALTER TABLE configitem ADD version INT DEFAULT 1000 NOT NULL');
+    }
+
+    public function down(Schema $schema): void
+    {
+        $this->addSql('ALTER TABLE ConfigItem DROP version');
+    }
+}

module/Database/src/Model/Trait/VersionTrait.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Database\Model\Trait;
+
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Version;
+
+trait VersionTrait
+{
+    /**
+     * integer version
+     * From the docs:
+     * "Version numbers [should] be preferred as they can not potentially conflict in a highly concurrent environment"
+     */
+    #[Version()]
+    #[Column(type: 'integer')]
+    private int $version;
+}

scripts/migrate-list.sh

@@ -0,0 +1,11 @@
+#/bin/sh
+
+# This script prints the available migrations for a specific alias
+set -e
+
+. /code/scripts/migrate-alias.sh
+
+./orm migrations:list --no-interaction --object-manager doctrine.entitymanager.$alias
+
+export alias=$alias
+export migrations=$migrations

scripts/migrate-version.sh

@@ -4,7 +4,7 @@
 # If you put this directly in the makefile, replace $ with $$
 set -e
 
-. /code/scripts/migrate-alias.sh
+. /code/scripts/migrate-list.sh
 
 read -rp "Give (partial, unique) version name (e.g. Database\Migrations\Version20241020224949 or 20241020)): " version