From 679e70e48ce93d02538ced2c52a7faa339572131 Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Fri, 13 Nov 2026 08:05:02 +0000 Subject: [PATCH] :bug: Keep file_change kind nullable so rollback keeps writing Migration 0158 created file_change with kind NOT NULL, which blocks any emergency rollback to the previous version: the old code inserts without kind and every save would fail. kind is still a reserve (reads use label IS NOT NULL), so it stays nullable until the rollback window closes; the NOT NULL comes in a later migration. The runbook keeps parity, the schema and migration tests cover the nullable column and the rollback insert, and the storage memory records the decision. AI-assisted-by: muse-spark-1.3-contributor --- .serena/memories/backend/storage.md | 2 +- .../sql/0158-partition-file-change.sql | 9 +++++++- .../backend_tests/file_change_schema_test.clj | 21 ++++++++++++------- .../migrations_partition_file_change_test.clj | 19 +++++++++++++++-- operations/2.20.0-file-change-partition.md | 8 +++++-- 5 files changed, 45 insertions(+), 14 deletions(-) diff --git a/.serena/memories/backend/storage.md b/.serena/memories/backend/storage.md index f10e74124b..0a9ca8e24c 100644 --- a/.serena/memories/backend/storage.md +++ b/.serena/memories/backend/storage.md @@ -137,7 +137,7 @@ Since `put-object!` uses backend-specific operations (`impl/resolve-backend` + ` - The automatic migration (`0158-partition-file-change`) refuses to run when `file_change` is above 10 GiB total size or 2M rows (`pg_total_relation_size` + `pg_class.reltuples`, catalog reads). It analyzes the table first, because `reltuples` is -1 without statistics. It raises with the path of `operations/2.20.0-file-change-partition.md`, because the copy happens inside the migration transaction and a big instance would restart in a loop. Below the guard it raises `statement_timeout` to 30 minutes for the copy and the index builds, and analyzes the new partitions at the end, after the copy and the indexes, so the planner does not start with empty statistics. - Its primary key is `(file_id, id)`: a partitioned table needs the partition key in the primary key, so every access filters by `file_id`. From 2.20 the four snapshot commands (`update-file-snapshot`, `delete-file-snapshot`, `lock-file-snapshot`, `unlock-file-snapshot`) require the `file-id` param, because they use it to prune the partition; without it they answer `:params-validation`. - It has a `kind` column: `1` is a snapshot (it has a label and its data lives in `file_data`) and `2` is a revision (it has no label and it holds the changes). The values are in `app.features.file-changes`. -- `kind` is a deliberate reserve, not a leftover: today no query filters by it, the queries still tell a snapshot from a revision by its label (`label IS NOT NULL`), and `kind` takes over when they are rewritten. No constraint ties `kind` and `label` together on purpose: the day `kind` is the source of truth, that constraint would have to go. +- `kind` is a deliberate reserve, not a leftover: today no query filters by it, the queries still tell a snapshot from a revision by its label (`label IS NOT NULL`), and `kind` takes over when they are rewritten. No constraint ties `kind` and `label` together on purpose: the day `kind` is the source of truth, that constraint would have to go. It stays nullable on purpose: the previous version inserts without it, and a rollback to it has to keep writing; the `NOT NULL` comes in a later migration. - Every write of the application to a row of `file_change` moves `updated_at` to the moment of the write (`lock-by!`, `unlock!`, the snapshot rename and delete, `delete-object`, the restore of a file, and the `legacy-db` snapshot write of `fdata`). The actions of the foreign keys (`ON DELETE SET NULL` on `locked_by` and `profile_id`) change the row without touching it; during the partition both tables carry the same keys, so both receive them. The runbook of the partition uses it as the watermark of its delta passes: a write of the application that leaves it behind is lost at the cutover. - `file_change_legacy` is a frozen copy of the previous layout of the partition: it keeps the rows and the indexes of the old table. A new instance (empty table) does not keep it. On an upgraded instance the table stays until the operator drops it by hand days later (`DROP TABLE file_change_legacy;`, see `operations/2.20.0-file-change-partition.md`); nothing drops it automatically. - A revision carries only the delta of a save (the changes). The features of the file are not repeated on it: nobody read them from there. diff --git a/backend/src/app/migrations/sql/0158-partition-file-change.sql b/backend/src/app/migrations/sql/0158-partition-file-change.sql index f44b12fef2..e8abe5523c 100644 --- a/backend/src/app/migrations/sql/0158-partition-file-change.sql +++ b/backend/src/app/migrations/sql/0158-partition-file-change.sql @@ -22,6 +22,10 @@ -- they are rewritten. That is why no constraint ties the two together: the -- day `kind` is the source of truth, the constraint would have to go. -- +-- It stays nullable on purpose: the previous version inserts without it, +-- and a rollback to that version has to keep writing. The `NOT NULL` comes +-- in a later migration, once the rollback window is closed. +-- -- The old table is kept aside as `file_change_legacy`: a frozen copy of the -- previous layout. It is dropped by hand, days later (or right here, when it -- is empty: on a new instance there is nothing to keep). @@ -127,7 +131,10 @@ CREATE TABLE file_change ( deleted_at timestamptz, migrations text[], locked_by uuid, - kind smallint NOT NULL, + -- Nullable on purpose: the previous version inserts without `kind`, and + -- a rollback to it has to keep writing. The `NOT NULL` comes in a later + -- migration, once the rollback window is closed. + kind smallint, CONSTRAINT file_change_kind_check CHECK (kind IN (1, 2)) ) PARTITION BY HASH (file_id); diff --git a/backend/test/backend_tests/file_change_schema_test.clj b/backend/test/backend_tests/file_change_schema_test.clj index 521d056a01..a40871ddde 100644 --- a/backend/test/backend_tests/file_change_schema_test.clj +++ b/backend/test/backend_tests/file_change_schema_test.clj @@ -84,21 +84,26 @@ WHERE attrelid = 'file_change'::regclass AND attname = 'data'"]) (mapv :type)))) - (t/is (true? (query "SELECT attnotnull AS notnull + ;; Nullable on purpose: a rollback to the previous version inserts + ;; without `kind` and has to keep writing (migration 0158). + (t/is (false? (query "SELECT attnotnull AS notnull FROM pg_attribute WHERE attrelid = 'file_change'::regclass AND attname = 'kind'")))) -(t/deftest inserting-a-row-without-a-kind-fails - ;; The column has no default on purpose: an insert that forgets it has to - ;; fail instead of storing the wrong kind silently. +(t/deftest inserting-a-row-without-a-kind-succeeds + ;; The column is nullable on purpose: the previous version inserts without + ;; it, and a rollback to that version has to keep writing. The backfill of + ;; a later NOT NULL migration turns these NULLs into 1/2. (let [profile (th/create-profile* 1) file (th/create-file* 1 {:profile-id (:id profile) :project-id (:default-project-id profile)})] - (t/is (thrown? java.sql.SQLException - (db/exec! th/*pool* ["INSERT INTO file_change (file_id, id) - VALUES (?, gen_random_uuid())" - (:id file)]))))) + (db/exec! th/*pool* ["INSERT INTO file_change (file_id, id) + VALUES (?, gen_random_uuid())" + (:id file)]) + (t/is (nil? (query "SELECT kind AS k + FROM file_change + WHERE file_id = ?" (:id file)))))) (t/deftest inserting-a-row-with-an-unknown-kind-fails (let [profile (th/create-profile* 1) diff --git a/backend/test/backend_tests/migrations_partition_file_change_test.clj b/backend/test/backend_tests/migrations_partition_file_change_test.clj index d5cc29ad37..b75310a5e8 100644 --- a/backend/test/backend_tests/migrations_partition_file_change_test.clj +++ b/backend/test/backend_tests/migrations_partition_file_change_test.clj @@ -7,8 +7,8 @@ (ns backend-tests.migrations-partition-file-change-test "Covers the data copy of 0158-partition-file-change: the rows of the old table move to the partitioned one with their columns in place, the `kind` - comes from the label (1 snapshot, 2 revision), and the legacy table keeps - the rows." + comes from the label (1 snapshot, 2 revision), it stays nullable so a + rollback keeps writing, and the legacy table keeps the rows." (:require [app.common.time :as ct] @@ -188,8 +188,23 @@ AND attname IN ('data_ref_id', 'data_backend')"]) (mapv :name))))) + (t/testing "kind stays nullable so a rollback keeps writing" + ;; The previous version inserts without `kind`: the column + ;; must accept NULL, like the runbook's staging column. + (t/is (false? (:notnull (db/exec-one! conn ["SELECT attnotnull AS notnull + FROM pg_attribute + WHERE attrelid = 'file_change'::regclass + AND attname = 'kind'"])))) + (let [rb-id (uuid/next)] + (db/insert! conn :file-change {:id rb-id :file-id fid :revn 99}) + (t/is (nil? (:kind (db/exec-one! conn ["SELECT kind + FROM file_change + WHERE file_id = ? AND id = ?" + fid rb-id])))))) + (db/exec! conn [(str "DROP SCHEMA " schema " CASCADE")]))))) + (t/deftest drops-the-legacy-table-when-it-is-empty ;; On a new instance there is nothing to keep: the migration leaves no ;; legacy table behind. The relation is asserted on its own, so a missing diff --git a/operations/2.20.0-file-change-partition.md b/operations/2.20.0-file-change-partition.md index 3a9aabd51b..30d1185a92 100644 --- a/operations/2.20.0-file-change-partition.md +++ b/operations/2.20.0-file-change-partition.md @@ -92,7 +92,8 @@ alone. `file_id` everywhere. - The table has 17 columns: `data_ref_id` and `data_backend` are gone (dead since the file storage refactor), `data` is kept (the `legacy-db` backend - reads old payloads from it) and `kind` appears (1 = snapshot, 2 = revision). + reads old payloads from it) and `kind` appears (1 = snapshot, 2 = revision, + nullable until the rollback window closes). - The old table is kept as `file_change_legacy`, a frozen copy of the previous layout, and dropped days later. - Almost all of the size of the table is dead space (see sizing), so the new @@ -305,7 +306,10 @@ CREATE TABLE file_change_new ( deleted_at timestamptz, migrations text[], locked_by uuid, - kind smallint NOT NULL, + -- Nullable on purpose, like the migration: the previous version inserts + -- without `kind`, and a rollback to it has to keep writing. The `NOT NULL` + -- comes in a later migration, once the rollback window is closed. + kind smallint, CONSTRAINT file_change_kind_check CHECK (kind IN (1, 2)) ) PARTITION BY HASH (file_id);