feat: support EXPLAIN ANALYZE on SQL Server for actual execution plans

A plain EXPLAIN maps to SET SHOWPLAN_XML, which compiles the statement
without executing it — so its plan carries estimates only. There was no
way to get a plan with real row counts.

EXPLAIN ANALYZE now maps to SET STATISTICS XML, which runs the statement
and returns a plan carrying ActualRows/ActualExecutions, matching the
PostgreSQL contract the connector already emulates for EXPLAIN.

This also fixes an existing gap: the read-only classifier already
recognises EXPLAIN ANALYZE (allowed-keywords.ts) and correctly refuses it
for DML, but the SQL Server connector had no handling for it. Both
`EXPLAIN ANALYZE <query>` and `EXPLAIN (ANALYZE) <query>` fell through to
explainQuery() and reached the server as `ANALYZE <query>` /
`(ANALYZE) <query>` — a syntax error.

Details:

1. Plan extraction reads the last recordset, not `recordset` (singular).
   STATISTICS XML interleaves each statement's plan with that statement's
   own result sets, so the plan sits at no fixed index and the singular
   accessor would hand back the query's data instead.

2. Option parsing covers the forms the classifier recognises: ANALYZE,
   ANALYZE VERBOSE, (ANALYZE), (ANALYZE, ...), (ANALYZE false).
   PostgreSQL-only options (BUFFERS, VERBOSE, COSTS, ...) have no SQL
   Server counterpart and are refused by name — silently dropping an
   option would quietly return something other than what was asked for.

   A disabled ANALYZE (false/off/0) falls back to the estimated plan.
   The classifier accepts an equals sign there (`ANALYZE = false`) and
   reads the value after a bare ANALYZE too, so both spellings are
   honoured here. Otherwise the layers disagree in the dangerous
   direction: the classifier waives its DML check for what it believes is
   a non-executing statement, while this connector routes to the path
   that executes.

3. Unlike EXPLAIN, EXPLAIN ANALYZE executes, so it is not inherently
   read-only. Under options.readonly the statement runs inside a
   transaction that always rolls back, guarded by assertNoReadOnlyEscapes
   with transactionControl set — the rollback is a real transaction a
   COMMIT could close, which is not true of explainQuery. Sharing that
   helper also blocks the pass-through data sources it covers: OPENQUERY
   and friends execute on the remote source, so a local rollback never
   reaches them, and this path executes by design.

4. The SET STATISTICS XML toggle runs on the same short-lived
   single-connection pool explainQuery() already uses, so the session
   state cannot leak onto a shared pool connection where a concurrent
   query would inherit it.

Adds 16 integration tests against a real SQL Server container.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: DANze11

src/connectors/__tests__/sqlserver.integration.test.ts

@@ -339,6 +339,197 @@ describe('SQL Server Connector Integration Tests', () => {
       ).rejects.toThrow(/requires a statement/i);
     });
 
+    it('should return an actual execution plan for EXPLAIN ANALYZE <query> (STATISTICS XML)', async () => {
+      const result = await sqlServerTest.connector.executeSQL(
+        'EXPLAIN ANALYZE SELECT * FROM users WHERE age > 30',
+        {}
+      );
+
+      expect(result.rows).toHaveLength(1);
+      const planXml = result.rows[0].plan as string;
+      expect(typeof planXml).toBe('string');
+      expect(planXml).toContain('ShowPlanXML');
+      expect(planXml).toContain('users');
+      // RunTimeInformation/ActualRows only appear in an *actual* plan
+      // (SET STATISTICS XML). SHOWPLAN_XML never emits them.
+      expect(planXml).toContain('RunTimeInformation');
+      expect(planXml).toMatch(/ActualRows/i);
+    });
+
+    it('should execute the statement under EXPLAIN ANALYZE', async () => {
+      const before = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'explain-analyze-exec@example.com'",
+        {}
+      );
+      expect(Number(before.rows[0].count)).toBe(0);
+
+      // Unlike EXPLAIN, EXPLAIN ANALYZE really runs the statement.
+      await sqlServerTest.connector.executeSQL(
+        "EXPLAIN ANALYZE INSERT INTO users (name, email, age) VALUES ('Exec', 'explain-analyze-exec@example.com', 42)",
+        {}
+      );
+
+      const after = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'explain-analyze-exec@example.com'",
+        {}
+      );
+      expect(Number(after.rows[0].count)).toBe(1);
+    });
+
+    it('should roll back writes under EXPLAIN ANALYZE in readonly mode', async () => {
+      const before = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'explain-analyze-ro@example.com'",
+        {}
+      );
+      expect(Number(before.rows[0].count)).toBe(0);
+
+      const result = await sqlServerTest.connector.executeSQL(
+        "EXPLAIN ANALYZE INSERT INTO users (name, email, age) VALUES ('RO', 'explain-analyze-ro@example.com', 42)",
+        { readonly: true }
+      );
+      // The plan still comes back...
+      expect(result.rows[0].plan as string).toContain('ShowPlanXML');
+
+      // ...but the write must not persist.
+      const after = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'explain-analyze-ro@example.com'",
+        {}
+      );
+      expect(Number(after.rows[0].count)).toBe(0);
+    });
+
+    it('should translate EXPLAIN ANALYZE even when preceded by a comment', async () => {
+      const result = await sqlServerTest.connector.executeSQL(
+        '/* real numbers please */ EXPLAIN ANALYZE SELECT * FROM users',
+        {}
+      );
+      expect(result.rows).toHaveLength(1);
+      expect(result.rows[0].plan as string).toContain('RunTimeInformation');
+    });
+
+    it('should reject SET STATISTICS smuggled into an EXPLAIN ANALYZE query', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL(
+          'EXPLAIN ANALYZE SET STATISTICS XML OFF SELECT * FROM users',
+          {}
+        )
+      ).rejects.toThrow(/SET STATISTICS/i);
+    });
+
+    it('should reject an empty EXPLAIN ANALYZE', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN ANALYZE   ', {})
+      ).rejects.toThrow(/requires a statement/i);
+    });
+
+    it('should accept the parenthesized EXPLAIN (ANALYZE) form', async () => {
+      const result = await sqlServerTest.connector.executeSQL(
+        'EXPLAIN (ANALYZE) SELECT name FROM users WHERE age > 30',
+        {}
+      );
+      expect(result.rows[0].plan as string).toContain('RunTimeInformation');
+    });
+
+    it('should treat EXPLAIN (ANALYZE false) as a plain estimated EXPLAIN', async () => {
+      // Matches the read-only classifier, which does not count disabled ANALYZE
+      // as executing. An estimated plan has no runtime counters.
+      const result = await sqlServerTest.connector.executeSQL(
+        'EXPLAIN (ANALYZE false) SELECT name FROM users WHERE age > 30',
+        {}
+      );
+      const plan = result.rows[0].plan as string;
+      expect(plan).toContain('ShowPlanXML');
+      expect(plan).not.toContain('RunTimeInformation');
+    });
+
+    it('should accept the equals spelling the read-only classifier recognizes', async () => {
+      // The classifier reads `ANALYZE = false` as a disabled ANALYZE, i.e. a
+      // plain EXPLAIN. Erroring here would reject what that layer waves through.
+      for (const sql of [
+        'EXPLAIN (ANALYZE = false) SELECT name FROM users WHERE age > 30',
+        'EXPLAIN (ANALYZE = 0) SELECT name FROM users WHERE age > 30',
+        'EXPLAIN ANALYZE = false SELECT name FROM users WHERE age > 30',
+        'EXPLAIN ANALYZE false SELECT name FROM users WHERE age > 30',
+      ]) {
+        const result = await sqlServerTest.connector.executeSQL(sql, {});
+        const plan = result.rows[0].plan as string;
+        expect(plan, sql).toContain('ShowPlanXML');
+        expect(plan, sql).not.toContain('RunTimeInformation');
+      }
+    });
+
+    it('should still enable ANALYZE for the equals spelling', async () => {
+      const result = await sqlServerTest.connector.executeSQL(
+        'EXPLAIN (ANALYZE = true) SELECT name FROM users WHERE age > 30',
+        {}
+      );
+      expect(result.rows[0].plan as string).toContain('RunTimeInformation');
+    });
+
+    it('should block pass-through data sources under readonly EXPLAIN ANALYZE', async () => {
+      // OPENQUERY executes on the remote source, so the rollback guard never
+      // reaches it — the same escape the plain EXPLAIN path blocks.
+      await expect(
+        sqlServerTest.connector.executeSQL(
+          "EXPLAIN ANALYZE SELECT * FROM OPENQUERY(remote, 'SELECT 1')",
+          { readonly: true }
+        )
+      ).rejects.toThrow(/pass-through data sources/i);
+    });
+
+    it('should block dynamic SQL under readonly EXPLAIN ANALYZE', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN ANALYZE EXEC GetUserCount', {
+          readonly: true,
+        })
+      ).rejects.toThrow(/dynamic SQL/i);
+    });
+
+    it('should not execute the statement under EXPLAIN (ANALYZE off)', async () => {
+      const before = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'analyze-off@example.com'",
+        {}
+      );
+      expect(Number(before.rows[0].count)).toBe(0);
+
+      await sqlServerTest.connector.executeSQL(
+        "EXPLAIN (ANALYZE off) INSERT INTO users (name, email, age) VALUES ('Off', 'analyze-off@example.com', 7)",
+        {}
+      );
+
+      const after = await sqlServerTest.connector.executeSQL(
+        "SELECT COUNT(*) as count FROM users WHERE email = 'analyze-off@example.com'",
+        {}
+      );
+      expect(Number(after.rows[0].count)).toBe(0);
+    });
+
+    it('should reject PostgreSQL-only EXPLAIN options with a clear message', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN (ANALYZE, BUFFERS) SELECT name FROM users', {})
+      ).rejects.toThrow(/BUFFERS/i);
+
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN ANALYZE VERBOSE SELECT name FROM users', {})
+      ).rejects.toThrow(/VERBOSE/i);
+
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN (COSTS) SELECT name FROM users', {})
+      ).rejects.toThrow(/COSTS/i);
+    });
+
+    it('should reject an unterminated EXPLAIN option list', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN (ANALYZE SELECT name FROM users', {})
+      ).rejects.toThrow(/option list/i);
+    });
+
+    it('should reject an empty EXPLAIN (ANALYZE) with no statement', async () => {
+      await expect(
+        sqlServerTest.connector.executeSQL('EXPLAIN (ANALYZE)   ', {})
+      ).rejects.toThrow(/requires a statement/i);
+    });
+
     it('should handle SQL Server IDENTITY columns', async () => {
       await sqlServerTest.connector.executeSQL(`
         CREATE TABLE identity_test (