fix: re-emit COMMENT when a function or procedure is dropped and recreated (#677) (#678)

When a function change requires DROP + CREATE (return type, OUT params,
parameter names) or a procedure body changes (always DROP + CREATE), the
plan only emitted COMMENT ON when the comment text differed. Since DROP
discards the comment, an unchanged comment was lost after apply and the
next plan reported a spurious diff.

Emit COMMENT ON after every DROP + CREATE whenever the new routine has a
comment, so a single apply converges.

Fixes #677

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: tianzhou

internal/diff/function.go

@@ -122,8 +122,9 @@ func generateModifyFunctionsSQL(diffs []*functionDiff, targetSchema string, coll
 			}
 			collector.collectStatements(alterContext, statements)
 
-			// Check if comment also changed alongside body changes
-			if oldFunc.Comment != newFunc.Comment {
+			// DROP FUNCTION discards the comment, so re-emit it whenever the new
+			// function has one, even if it is unchanged (issue #677).
+			if newFunc.Comment != "" {
 				generateFunctionComment(newFunc, targetSchema, DiffTypeFunction, DiffOperationAlter, collector)
 			}
 		} else {

internal/diff/procedure.go

@@ -89,8 +89,9 @@ func generateModifyProceduresSQL(diffs []*procedureDiff, targetSchema string, co
 
 		collector.collectStatements(alterContext, statements)
 
-		// Check if comment also changed alongside body changes
-		if oldProc.Comment != newProc.Comment {
+		// DROP PROCEDURE discards the comment, so re-emit it whenever the new
+		// procedure has one, even if it is unchanged (issue #677).
+		if newProc.Comment != "" {
 			generateProcedureComment(newProc, targetSchema, DiffTypeProcedure, DiffOperationAlter, collector)
 		}
 	}

testdata/diff/create_function/issue_326_return_type_change/diff.sql

@@ -8,3 +8,5 @@ LANGUAGE sql
 VOLATILE
 AS $$ SELECT length(param1);
 $$;
+
+COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';

testdata/diff/create_function/issue_326_return_type_change/new.sql

@@ -3,3 +3,6 @@ CREATE OR REPLACE FUNCTION somefunction(
 ) RETURNS integer
 LANGUAGE sql
 AS $$ SELECT length(param1); $$;
+
+-- Issue #677: unchanged comment must survive the DROP + CREATE cycle
+COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';

testdata/diff/create_function/issue_326_return_type_change/old.sql

@@ -3,3 +3,5 @@ CREATE OR REPLACE FUNCTION somefunction(
 ) RETURNS text
 LANGUAGE sql
 AS $$ SELECT param1; $$;
+
+COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';

testdata/diff/create_function/issue_326_return_type_change/plan.json

@@ -3,7 +3,7 @@
   "pgschema_version": "1.13.4",
   "created_at": "1970-01-01T00:00:00Z",
   "source_fingerprint": {
-    "hash": "59a96fc0ed0cbfa32f92a9d869bbbc6e38359d50afcd5ea6eb4f388717c48135"
+    "hash": "7b9f39d2d87004e53be9715527178d0c2f2b5e92a87034c3828c87bd0a3af0ad"
   },
   "groups": [
     {
@@ -19,6 +19,12 @@
           "type": "function",
           "operation": "alter",
           "path": "public.somefunction"
+        },
+        {
+          "sql": "COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';",
+          "type": "function",
+          "operation": "alter",
+          "path": "public.somefunction"
         }
       ]
     }

testdata/diff/create_function/issue_326_return_type_change/plan.sql

@@ -8,3 +8,5 @@ LANGUAGE sql
 VOLATILE
 AS $$ SELECT length(param1);
 $$;
+
+COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';

testdata/diff/create_function/issue_326_return_type_change/plan.txt

@@ -1,10 +1,11 @@
-Plan: 1 to modify.
+Plan: 2 to modify.
 
 Summary by type:
-  functions: 1 to modify
+  functions: 2 to modify
 
 Functions:
   ~ somefunction
+  ~ somefunction
 
 DDL to be executed:
 --------------------------------------------------
@@ -19,3 +20,5 @@ LANGUAGE sql
 VOLATILE
 AS $$ SELECT length(param1);
 $$;
+
+COMMENT ON FUNCTION somefunction(text) IS 'Returns text based on param1';

testdata/diff/create_procedure/alter_procedure/diff.sql

@@ -21,3 +21,19 @@ BEGIN
     COMMIT;
 END;
 $$;
+
+COMMENT ON PROCEDURE process_payment(integer, numeric, text) IS 'Marks an order as paid';
+
+DROP PROCEDURE IF EXISTS log_event(IN message text);
+
+CREATE OR REPLACE PROCEDURE log_event(
+    IN message text
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    INSERT INTO event_log (message, logged_at) VALUES (message, NOW());
+END;
+$$;
+
+COMMENT ON PROCEDURE log_event(text) IS 'Appends a message to event_log';

testdata/diff/create_procedure/alter_procedure/new.sql

@@ -18,4 +18,17 @@ BEGIN
 
     COMMIT;
 END;
-$$;
+$$;
+-- Issue #677: unchanged comment must survive the DROP + CREATE cycle
+COMMENT ON PROCEDURE process_payment(integer, numeric, text) IS 'Marks an order as paid';
+
+-- Issue #677: body-only change keeps the same signature, so pgschema plans
+-- DROP + CREATE; the unchanged comment must be re-emitted afterwards.
+CREATE PROCEDURE log_event(message text)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+    INSERT INTO event_log (message, logged_at) VALUES (message, NOW());
+END;
+$$;
+COMMENT ON PROCEDURE log_event(text) IS 'Appends a message to event_log';