✨ improve version explanation

db/migration/1734369183234-CloudflareImagesReplacedBy.ts

@@ -12,6 +12,13 @@ export class CloudflareImagesReplacedBy1734369183234
         await queryRunner.query(`-- sql
             ALTER TABLE images 
             ADD COLUMN replacedBy INT NULL,
+            -- Necessary to create a unique constraint with filename, so that we can have multiple versions of the same image,
+            -- but not multiple images with the same filename and version.
+            -- i.e.
+            -- You can upload test.png and *replace* it with test.png, but you can't upload a *new* image named test.png,
+            -- because that would have a version of 0 and conflict with the first test.png that was uploaded
+            -- This was done because MySQL 8 doesn't support partial unique indexes (e.g. "UNIQUE(filename) WHERE replacedBy IS NULL")
+            -- Nor a unique constraint when the column is nullable (e.g. "UNIQUE(filename, replacedBy)" would allow multiple rows with ["test.png", null])
             ADD COLUMN version INT NOT NULL DEFAULT 0,
             ADD CONSTRAINT fk_images_replaced_by 
                 FOREIGN KEY (replacedBy) 

packages/@ourworldindata/types/src/dbTypes/Images.ts

@@ -16,8 +16,11 @@ export interface DbInsertImage {
     /**
      * Necessary to create a unique constraint with filename, so that we can have multiple versions of the same image,
      * but not multiple images with the same filename and version.
-     * i.e. you can upload test.png and *replace* it with test.png, but you can't upload a *new* image named test.png,
+     * i.e.
+     * You can upload test.png and *replace* it with test.png, but you can't upload a *new* image named test.png,
      * because that would have a version of 0 and conflict with the first test.png that was uploaded
+     * This was done because MySQL 8 doesn't support partial unique indexes (e.g. "UNIQUE(filename) WHERE replacedBy IS NULL")
+     * Nor a unique constraint when the column is nullable (e.g. "UNIQUE(filename, replacedBy)" would allow multiple rows with ["test.png", null])
      */
     version?: number
 }