fix(migrations) make resumable and safe against schema drift

backend/migrations/20260424_01_docx_version_display_name.sql

@@ -28,8 +28,21 @@ ALTER TABLE public.document_versions
 -- assistant edits inherit the prior version's display_name (see
 -- runEditDocument), so the version number is no longer baked into the
 -- default label — it's surfaced as a separate tag in the UI.
-UPDATE public.document_versions dv
-SET display_name = d.filename
-FROM public.documents d
-WHERE dv.display_name IS NULL
-  AND d.id = dv.document_id;
+DO $$
+BEGIN
+  -- Later migrations remove documents.filename. Keep this historical
+  -- backfill re-runnable against both the old and current schemas.
+  IF EXISTS (
+    SELECT 1
+    FROM information_schema.columns
+    WHERE table_schema = 'public'
+      AND table_name = 'documents'
+      AND column_name = 'filename'
+  ) THEN
+    UPDATE public.document_versions dv
+    SET display_name = d.filename
+    FROM public.documents d
+    WHERE dv.display_name IS NULL
+      AND d.id = dv.document_id;
+  END IF;
+END $$;

backend/migrations/20260427_01_move_storage_to_versions.sql

@@ -19,38 +19,66 @@ alter table public.document_versions
 
 -- 2. Backfill: ensure every document has at least one document_versions row
 --    (the original upload). Older docs may predate document_versions entirely.
-insert into public.document_versions (
-    document_id,
-    storage_path,
-    pdf_storage_path,
-    source,
-    version_number,
-    display_name,
-    created_at
-)
-select
-    d.id,
-    d.storage_path,
-    d.pdf_storage_path,
-    'upload',
-    1,
-    d.filename,
-    d.created_at
-from public.documents d
-left join public.document_versions dv
-    on dv.document_id = d.id and dv.source = 'upload'
-where dv.id is null
-  and d.storage_path is not null;
+do $$
+begin
+  -- The source columns are removed at the end of this migration. On a
+  -- re-run against the current schema, there is nothing left to copy.
+  if exists (
+    select 1 from information_schema.columns
+    where table_schema = 'public' and table_name = 'documents'
+      and column_name = 'storage_path'
+  ) and exists (
+    select 1 from information_schema.columns
+    where table_schema = 'public' and table_name = 'documents'
+      and column_name = 'pdf_storage_path'
+  ) and exists (
+    select 1 from information_schema.columns
+    where table_schema = 'public' and table_name = 'documents'
+      and column_name = 'filename'
+  ) then
+    insert into public.document_versions (
+        document_id,
+        storage_path,
+        pdf_storage_path,
+        source,
+        version_number,
+        display_name,
+        created_at
+    )
+    select
+        d.id,
+        d.storage_path,
+        d.pdf_storage_path,
+        'upload',
+        1,
+        d.filename,
+        d.created_at
+    from public.documents d
+    left join public.document_versions dv
+        on dv.document_id = d.id and dv.source = 'upload'
+    where dv.id is null
+      and d.storage_path is not null;
+  end if;
+end $$;
 
 -- 3. Backfill pdf_storage_path onto the existing 'upload' rows for docs
 --    that already had one but predate document_versions.pdf_storage_path.
-update public.document_versions dv
-set pdf_storage_path = d.pdf_storage_path
-from public.documents d
-where dv.document_id = d.id
-  and dv.source = 'upload'
-  and dv.pdf_storage_path is null
-  and d.pdf_storage_path is not null;
+do $$
+begin
+  if exists (
+    select 1 from information_schema.columns
+    where table_schema = 'public' and table_name = 'documents'
+      and column_name = 'pdf_storage_path'
+  ) then
+    update public.document_versions dv
+    set pdf_storage_path = d.pdf_storage_path
+    from public.documents d
+    where dv.document_id = d.id
+      and dv.source = 'upload'
+      and dv.pdf_storage_path is null
+      and d.pdf_storage_path is not null;
+  end if;
+end $$;
 
 -- 4. Backfill current_version_id for any document missing one — point it
 --    at the most recent version (assistant_edit / user_upload preferred,

backend/migrations/20260602_01_add_document_version_file_metadata.sql

@@ -13,16 +13,35 @@ ALTER TABLE public.document_versions
   ADD COLUMN IF NOT EXISTS size_bytes integer,
   ADD COLUMN IF NOT EXISTS page_count integer;
 
-UPDATE public.document_versions dv
-SET
-  file_type = COALESCE(NULLIF(btrim(dv.file_type), ''), d.file_type),
-  size_bytes = COALESCE(dv.size_bytes, d.size_bytes),
-  page_count = COALESCE(dv.page_count, d.page_count)
-FROM public.documents d
-WHERE dv.document_id = d.id
-  AND (
-    dv.file_type IS NULL
-    OR btrim(dv.file_type) = ''
-    OR dv.size_bytes IS NULL
-    OR dv.page_count IS NULL
-  );
+DO $$
+BEGIN
+  -- These source columns are removed by a later migration. On a re-run
+  -- against the current schema, the per-version values are already canonical.
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = 'documents'
+      AND column_name = 'file_type'
+  ) AND EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = 'documents'
+      AND column_name = 'size_bytes'
+  ) AND EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = 'documents'
+      AND column_name = 'page_count'
+  ) THEN
+    UPDATE public.document_versions dv
+    SET
+      file_type = COALESCE(NULLIF(btrim(dv.file_type), ''), d.file_type),
+      size_bytes = COALESCE(dv.size_bytes, d.size_bytes),
+      page_count = COALESCE(dv.page_count, d.page_count)
+    FROM public.documents d
+    WHERE dv.document_id = d.id
+      AND (
+        dv.file_type IS NULL
+        OR btrim(dv.file_type) = ''
+        OR dv.size_bytes IS NULL
+        OR dv.page_count IS NULL
+      );
+  END IF;
+END $$;

backend/migrations/20260602_02_add_document_version_filename_temp.sql

@@ -6,8 +6,20 @@
 ALTER TABLE public.document_versions
   ADD COLUMN IF NOT EXISTS filename text;
 
-UPDATE public.document_versions
-SET filename = display_name
-WHERE (filename IS NULL OR btrim(filename) = '')
-  AND display_name IS NOT NULL
-  AND btrim(display_name) <> '';
+DO $$
+BEGIN
+  -- display_name is renamed/dropped by later migrations. Only backfill while
+  -- the transitional source column is still present.
+  IF EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public'
+      AND table_name = 'document_versions'
+      AND column_name = 'display_name'
+  ) THEN
+    UPDATE public.document_versions
+    SET filename = display_name
+    WHERE (filename IS NULL OR btrim(filename) = '')
+      AND display_name IS NOT NULL
+      AND btrim(display_name) <> '';
+  END IF;
+END $$;

backend/migrations/20260613_02_projects_overview_rpc.sql

@@ -4,6 +4,11 @@
 -- Returns the project list, owner display name, and per-project counts in one
 -- database call for the /projects table.
 
+-- Later migrations extend this function's output columns. PostgreSQL cannot
+-- replace a RETURNS TABLE row type in place, so remove that later shape before
+-- replaying this historical definition.
+DROP FUNCTION IF EXISTS public.get_projects_overview(text, text);
+
 create or replace function public.get_projects_overview(
   p_user_id text,
   p_user_email text default null

backend/migrations/20260613_05_workflows_overview_rpc.sql

@@ -3,6 +3,10 @@
 -- Workflows overview read model.
 -- Returns owned and shared workflows in one database call.
 
+-- Later migrations add output columns. DROP first because CREATE OR REPLACE
+-- cannot alter a function's RETURNS TABLE row type.
+DROP FUNCTION IF EXISTS public.get_workflows_overview(text, text, text);
+
 create or replace function public.get_workflows_overview(
   p_user_id text,
   p_user_email text default null,

backend/migrations/20260710_01_library_documents.sql

@@ -1,5 +1,4 @@
 -- Migration date: 2026-07-10
-
 alter table public.documents
   add column if not exists library_kind text default 'file';