fix(node): Prevent PostgresJs integration from emitting duplicate spans per query (#21364)

postgres.js calls handle() from then/catch/finally, but only the first
invocation executes SQL (guarded by this.executed). The patched handle
was creating a new span on every call, inflating span count 2-3x.

Fixes #21355

---------

Co-authored-by: Claude claude-opus-4-6 <noreply@anthropic.com>

Author: andreiborza

packages/core/src/integrations/postgresjs.ts

@@ -217,8 +217,10 @@ function _wrapSingleQueryHandle(
 
   // IMPORTANT: We must replace the handle function directly, not use a Proxy,
   // because Query.then() internally calls this.handle(), which would bypass a Proxy wrapper.
-  const wrappedHandle = async function (this: unknown, ...args: unknown[]): Promise<unknown> {
-    if (!_shouldCreateSpans(options)) {
+  const wrappedHandle = async function (this: { executed?: boolean }, ...args: unknown[]): Promise<unknown> {
+    // postgres.js calls handle() from then/catch/finally — only the first call executes SQL,
+    // subsequent calls are no-ops (guarded by this.executed). Skip span creation for no-ops.
+    if (this.executed || !_shouldCreateSpans(options)) {
       return originalHandle.apply(this, args);
     }
 

packages/core/test/lib/integrations/postgresjs.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { _reconstructQuery, _sanitizeSqlQuery, instrumentPostgresJsSql } from '../../../src/integrations/postgresjs';
+import * as tracing from '../../../src/tracing';
 import * as spanUtils from '../../../src/utils/spanUtils';
 
 describe('PostgresJs portable instrumentation', () => {
@@ -554,6 +555,42 @@ describe('PostgresJs portable instrumentation', () => {
         // handle was wrapped
         expect((mockQuery.handle as any).__sentryWrapped).toBe(true);
       });
+
+      it('only creates one span even when handle() is called multiple times', async () => {
+        const mockSpan = { setAttribute: vi.fn(), setAttributes: vi.fn(), end: vi.fn() };
+        const startSpanManualSpy = vi
+          .spyOn(tracing, 'startSpanManual')
+          .mockImplementation((_opts, callback) => callback(mockSpan as any, () => {}));
+
+        const originalHandle = vi.fn().mockResolvedValue([]);
+        const mockQuery = {
+          handle: originalHandle,
+          strings: ['SELECT 1'],
+          resolve: vi.fn(),
+          reject: vi.fn(),
+          executed: false,
+        };
+        const mockSql = vi.fn().mockReturnValue(mockQuery);
+
+        const instrumented = instrumentPostgresJsSql(mockSql, { requireParentSpan: false });
+        instrumented(['SELECT 1']);
+
+        const wrappedHandle = mockQuery.handle as (...args: unknown[]) => Promise<unknown>;
+
+        // First call — executed is false, should create a span
+        await wrappedHandle.call(mockQuery);
+        expect(startSpanManualSpy).toHaveBeenCalledTimes(1);
+
+        // Simulate postgres.js setting executed = true after first handle()
+        mockQuery.executed = true;
+
+        // Second and third calls (from .then/.catch/.finally) — should NOT create more spans
+        await wrappedHandle.call(mockQuery);
+        await wrappedHandle.call(mockQuery);
+        expect(startSpanManualSpy).toHaveBeenCalledTimes(1);
+
+        startSpanManualSpy.mockRestore();
+      });
     });
 
     it('does not wrap non-query results from sql call', () => {

packages/node/src/integrations/tracing/postgresjs.ts

@@ -281,11 +281,14 @@ export class PostgresJsInstrumentation extends InstrumentationBase<PostgresJsIns
         resolve: unknown;
         reject: unknown;
         strings?: string[];
+        executed?: boolean;
       },
       ...args: unknown[]
     ): Promise<unknown> {
-      // Skip if this query came from an instrumented sql instance (already handled by wrapper)
-      if ((this as Record<symbol, unknown>)[QUERY_FROM_INSTRUMENTED_SQL]) {
+      // Skip if this query came from an instrumented sql instance (already handled by wrapper),
+      // or if handle() was already called (postgres.js calls handle() from then/catch/finally —
+      // only the first call executes SQL, subsequent calls are no-ops).
+      if (this.executed || (this as Record<symbol, unknown>)[QUERY_FROM_INSTRUMENTED_SQL]) {
         return originalHandle.apply(this, args);
       }