Add OPENQUERY(linked_server, 'query'): pass-through ad-hoc rowset over the linked-server seam, with compile-time schema discovery, first-result-set-only semantics, and the probe-confirmed parse-validation / Msg 7202 error surface.

Record the corrected scope of the leaked-connection cleanup backlog item.

Author: RyanLamansky

CLAUDE.md

@@ -177,7 +177,7 @@ Per-feature deep-dives live under `docs/claude/`. Each entry below is a trigger:
 - **Per-column / per-expression collation, coercibility precedence, Msg 468 / 457 cross-collation enforcement, recognized catalog, `#temp` collation inheritance** → [`collations.md`](docs/claude/collations.md).
 - **New top-level statement parser or dispatch-loop separator rules** → [`grammar.md`](docs/claude/grammar.md) + [`control-flow.md`](docs/claude/control-flow.md).
 - **BACPAC import** (`Simulation.ImportBacpac` instance method — multi-database via repeated calls, `BacpacImportOptions`, `ModelXmlReader` dispatcher, BCP wire format, `BacpacBuilder` test harness) → [`bacpac-loader.md`](docs/claude/bacpac-loader.md).
-- **Linked servers** (`Simulation.AddRemoteSimulation`, `sp_addlinkedserver` / `sp_dropserver`, four-part-name FROM routing through the remote's ADO.NET pipeline, `sys.servers`) → [`linked-servers.md`](docs/claude/linked-servers.md).
+- **Linked servers** (`Simulation.AddRemoteSimulation`, `sp_addlinkedserver` / `sp_dropserver`, four-part-name FROM routing through the remote's ADO.NET pipeline, `OPENQUERY(server, 'query')` ad-hoc pass-through with compile-time schema discovery, `sys.servers`) → [`linked-servers.md`](docs/claude/linked-servers.md).
 
 ## Not modeled
 

SqlServerSimulator.Tests/OpenQueryTests.cs

@@ -0,0 +1,190 @@
+using static Microsoft.VisualStudio.TestTools.UnitTesting.Assert;
+
+namespace SqlServerSimulator;
+
+[TestClass]
+public class OpenQueryTests
+{
+    private static Simulation LocalWithRemote(out Simulation remote, string remoteSetup)
+    {
+        remote = new Simulation();
+        _ = remote.ExecuteNonQuery(remoteSetup);
+
+        var local = new Simulation();
+        local.AddRemoteSimulation("RMT", remote);
+        _ = local.ExecuteNonQuery("exec sp_addlinkedserver 'RMT', 'SQL Server'");
+        return local;
+    }
+
+    [TestMethod]
+    public void Basic_ReturnsRemoteRows()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key, name varchar(20) not null); insert t values (1, 'a'), (2, 'b')");
+        AreEqual("b", local.ExecuteScalar("select name from OPENQUERY(RMT, 'select id, name from dbo.t where id = 2')"));
+    }
+
+    [TestMethod]
+    public void Basic_CountAllRows()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (1), (2), (3)");
+        AreEqual(3, local.ExecuteScalar("select count(*) from OPENQUERY(RMT, 'select id from dbo.t')"));
+    }
+
+    /// <summary>
+    /// The pass-through query is arbitrary T-SQL run on the remote, not just a
+    /// table name: WHERE / expressions / aggregation all execute remotely.
+    /// </summary>
+    [TestMethod]
+    public void Passthrough_AggregationRunsRemotely()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key, qty int not null); insert t values (1, 5), (2, 10), (3, 7)");
+        AreEqual(22, local.ExecuteScalar("select total from OPENQUERY(RMT, 'select sum(qty) as total from dbo.t')"));
+    }
+
+    [TestMethod]
+    public void Passthrough_ExpressionColumn()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (10)");
+        AreEqual(20, local.ExecuteScalar("select doubled from OPENQUERY(RMT, 'select id * 2 as doubled from dbo.t')"));
+    }
+
+    /// <summary>
+    /// OPENQUERY returns only the FIRST result set of a multi-statement
+    /// pass-through batch.
+    /// </summary>
+    [TestMethod]
+    public void FirstResultSetOnly()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.a (v int not null); insert a values (100); create table dbo.b (v int not null); insert b values (200), (300)");
+        // First SELECT yields one row (100); the second SELECT is ignored.
+        AreEqual(1, local.ExecuteScalar("select count(*) from OPENQUERY(RMT, 'select v from dbo.a; select v from dbo.b')"));
+        AreEqual(100, local.ExecuteScalar("select v from OPENQUERY(RMT, 'select v from dbo.a; select v from dbo.b')"));
+    }
+
+    [TestMethod]
+    public void Position_InJoin()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.parts (part_id int not null primary key, name varchar(20) not null); insert parts values (1, 'widget'), (2, 'gadget')");
+        _ = local.ExecuteNonQuery("create table dbo.orders (order_id int not null primary key, part_id int not null, qty int not null); insert orders values (1, 1, 5), (2, 2, 10), (3, 1, 7)");
+
+        var qty = local.ExecuteScalar("""
+            select sum(o.qty)
+            from dbo.orders o
+            inner join OPENQUERY(RMT, 'select part_id, name from dbo.parts') p on p.part_id = o.part_id
+            where p.name = 'widget'
+            """);
+        AreEqual(12, qty);
+    }
+
+    [TestMethod]
+    public void Position_InDerivedTable()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key, v int not null); insert t values (1, 10), (2, 20), (3, 30)");
+        AreEqual(50, local.ExecuteScalar("select sum(v) from (select v from OPENQUERY(RMT, 'select id, v from dbo.t where id >= 2')) d"));
+    }
+
+    [TestMethod]
+    public void Alias_WithoutAs()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (7)");
+        AreEqual(7, local.ExecuteScalar("select q.id from OPENQUERY(RMT, 'select id from dbo.t') q"));
+    }
+
+    [TestMethod]
+    public void Alias_WithAs()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (7)");
+        AreEqual(7, local.ExecuteScalar("select q.id from OPENQUERY(RMT, 'select id from dbo.t') as q"));
+    }
+
+    [TestMethod]
+    public void KeywordIsCaseInsensitive()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (5)");
+        AreEqual(5, local.ExecuteScalar("select id from openquery(RMT, 'select id from dbo.t')"));
+    }
+
+    [TestMethod]
+    public void BracketedServerName_Resolves()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (9)");
+        AreEqual(9, local.ExecuteScalar("select id from OPENQUERY([RMT], 'select id from dbo.t')"));
+    }
+
+    /// <summary>
+    /// A pass-through payload that produces no result set (empty string, a
+    /// non-SELECT statement) surfaces a clear <see cref="NotSupportedException"/>
+    /// naming the condition — the exact real-server Msg isn't probed.
+    /// </summary>
+    [TestMethod]
+    public void EmptyQuery_NoResultSet_NotSupported()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        var ex = Throws<NotSupportedException>(() => local.ExecuteScalar("select * from OPENQUERY(RMT, '')"));
+        Contains("no result set", ex.Message);
+    }
+
+    [TestMethod]
+    public void NonSelectQuery_NoResultSet_NotSupported()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        var ex = Throws<NotSupportedException>(() => local.ExecuteScalar("select * from OPENQUERY(RMT, 'declare @x int = 5')"));
+        Contains("no result set", ex.Message);
+    }
+
+    [TestMethod]
+    public void UnknownServer_Msg7202()
+    {
+        var local = new Simulation();
+        var ex = local.AssertSqlError("select * from OPENQUERY(NOPE, 'select 1 as x')", 7202);
+        Contains("Could not find server 'NOPE' in sys.servers", ex.Message);
+    }
+
+    [TestMethod]
+    public void VariableQueryArg_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        _ = local.AssertSqlError("declare @q varchar(100) = 'select id from dbo.t'; select * from OPENQUERY(RMT, @q)", 102);
+    }
+
+    [TestMethod]
+    public void StringLiteralServerArg_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        _ = local.AssertSqlError("select * from OPENQUERY('RMT', 'select id from dbo.t')", 102);
+    }
+
+    [TestMethod]
+    public void TooFewArgs_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        _ = local.AssertSqlError("select * from OPENQUERY(RMT)", 102);
+    }
+
+    [TestMethod]
+    public void TooManyArgs_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        _ = local.AssertSqlError("select * from OPENQUERY(RMT, 'select id from dbo.t', 'extra')", 102);
+    }
+
+    [TestMethod]
+    public void ConcatenatedQueryArg_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int)");
+        _ = local.AssertSqlError("select * from OPENQUERY(RMT, 'select ' + 'id from dbo.t')", 102);
+    }
+
+    /// <summary>
+    /// A column-alias list on OPENQUERY is rejected (real SQL Server: Msg 102
+    /// near the first alias identifier; the simulator raises Msg 102 near the
+    /// opening <c>(</c>). Without the guard the general FROM parser tolerates
+    /// and ignores the list, silently keeping the remote column names.
+    /// </summary>
+    [TestMethod]
+    public void ColumnAliasList_Msg102()
+    {
+        var local = LocalWithRemote(out _, "create table dbo.t (id int not null primary key); insert t values (1)");
+        _ = local.AssertSqlError("select c1 from OPENQUERY(RMT, 'select id from dbo.t') q(c1)", 102);
+    }
+}

SqlServerSimulator/Errors/SimulatedSqlException.SchemaErrors.cs

@@ -27,6 +27,15 @@ internal static SimulatedSqlException InvalidCompatibilityLevel() =>
 
     internal static SimulatedSqlException ThereIsAlreadyAnObject(string name) => new($"There is already an object named '{name}' in the database.", 2714, 16, 6);
 
+    /// <summary>
+    /// Mimics SQL Server error 7202: an <c>OPENQUERY</c> (or four-part name)
+    /// references a linked-server name that isn't registered in
+    /// <c>sys.servers</c>. Wording probe-confirmed against SQL Server 2025;
+    /// Class 11 State 2.
+    /// </summary>
+    internal static SimulatedSqlException LinkedServerNotFound(string serverName) =>
+        new($"Could not find server '{serverName}' in sys.servers. Verify that the correct server name was specified. If necessary, execute the stored procedure sp_addlinkedserver to add the server to sys.servers.", 7202, 11, 2);
+
     /// <summary>
     /// Mimics SQL Server error 911: <c>USE &lt;db&gt;</c> targets a database
     /// that doesn't exist in this <see cref="Simulation"/>. Wording

SqlServerSimulator/Parser/Selection.LinkedServer.cs

@@ -1,5 +1,6 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
+using SqlServerSimulator.Parser.Tokens;
 using SqlServerSimulator.Storage;
 
 namespace SqlServerSimulator.Parser;
@@ -83,4 +84,124 @@ private static List<byte[]> StreamRemoteRows(LinkedServer server, string databas
     }
 
     private static string EscapeIdent(string ident) => ident.Replace("]", "]]", StringComparison.Ordinal);
+
+    /// <summary>
+    /// Parses an <c>OPENQUERY(server, 'query')</c> FROM / JOIN source. Enters
+    /// with <see cref="ParserContext.Token"/> on the <c>OPENQUERY</c> name;
+    /// on return <see cref="ParserContext.Token"/> sits on the first token
+    /// past the closing <c>)</c> (ready for the caller's in-place alias
+    /// handling). Exactly two arguments: a bare identifier (plain or
+    /// bracketed) naming the linked server, and a bare string literal
+    /// carrying the pass-through query. Anything else (a literal / dotted
+    /// name in the server slot, a variable / concatenation / extra arg in
+    /// the query slot) fails as Msg 102 because the token after each slot
+    /// isn't the expected separator. The linked server is resolved eagerly:
+    /// an unregistered name raises Msg 7202. The pass-through query then
+    /// runs once on the remote to discover its result-set schema (columns
+    /// aren't known until the query executes).
+    /// </summary>
+    internal static Selection ParseOpenQuery(ParserContext context)
+    {
+        if (context.GetNextRequired() is not Operator { Character: '(' })
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+
+        if (context.GetNextRequired() is not Name serverToken)
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+        var serverName = serverToken.Value;
+
+        if (context.GetNextRequired() is not Operator { Character: ',' })
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+
+        if (context.GetNextRequired() is not Literal queryLiteral || queryLiteral.Value.Type.Category != SqlTypeCategory.String)
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+        var queryText = queryLiteral.Value.AsString;
+
+        if (context.GetNextRequired() is not Operator { Character: ')' })
+            throw SimulatedSqlException.SyntaxErrorNear(context);
+        context.MoveNextOptional();
+
+        // OPENQUERY reads external remote state, so its FROM-less-style
+        // baked schema mustn't be cached across executions with a different
+        // remote. Disqualify the batch from plan-cache promotion.
+        context.Batch.HasSessionScopedReference = true;
+
+        if (!context.Batch.Connection.Simulation.ActiveLinkedServers.TryGetValue(serverName, out var server))
+            throw SimulatedSqlException.LinkedServerNotFound(serverName);
+
+        var (schema, columnNames) = DiscoverOpenQuerySchema(server, queryText);
+        return ForOpenQuery(server, queryText, schema, columnNames);
+    }
+
+    /// <summary>
+    /// Wraps an <c>OPENQUERY</c> pass-through query as a
+    /// <see cref="Selection"/> usable as a <see cref="FromSource.LateralPlan"/>.
+    /// Unlike the four-part-name <see cref="ForLinkedServer"/>, the schema is
+    /// discovered once at parse time and passed in here; each
+    /// <see cref="Execute"/> RE-RUNS the query on the remote and streams the
+    /// first result set's rows (it does not cache the schema-discovery pass's
+    /// rows). So a side-effecting pass-through payload runs once for schema
+    /// discovery plus once per outer execution — acceptable for the SELECT
+    /// payloads OPENQUERY targets.
+    /// </summary>
+    internal static Selection ForOpenQuery(LinkedServer server, string queryText, SqlType[] schema, string[] columnNames) =>
+        new(
+            schema,
+            columnNames,
+            hasOrderBy: false,
+            hasTopOrOffsetOrFetch: false,
+            rowSource: (_, _) => StreamOpenQueryRows(server, queryText));
+
+    /// <summary>
+    /// Runs the pass-through query on the remote and captures the first
+    /// result set's schema + column names (OPENQUERY returns only the first
+    /// result set). A query that yields no result set (empty string, a
+    /// non-SELECT statement) raises <see cref="NotSupportedException"/> — the
+    /// exact real-server Msg for this case isn't probed, so the simulator
+    /// names the condition rather than fabricating a number.
+    /// </summary>
+    [SuppressMessage("Security", "CA2100:Review SQL queries for security vulnerabilities", Justification = "OPENQUERY's second argument is a pass-through query string by design — the caller intends it to run verbatim on the remote. The remote command runs against a sibling Simulation in the same process; there's no external SQL surface to inject against.")]
+    private static (SqlType[] Schema, string[] ColumnNames) DiscoverOpenQuerySchema(LinkedServer server, string queryText)
+    {
+        // An all-whitespace / empty pass-through string reaches the remote
+        // command as an uninitialized CommandText (which raises its own
+        // InvalidOperationException); short-circuit to the uniform no-result
+        // message instead so every no-rowset payload surfaces the same way.
+        if (string.IsNullOrWhiteSpace(queryText))
+            throw OpenQueryNoResultSet(server.Name);
+
+        using var conn = server.Target.CreateDbConnection();
+        conn.Open();
+        using var cmd = conn.CreateCommand();
+        cmd.CommandText = queryText;
+        foreach (var outcome in server.Target.CreateResultSetsForCommand(cmd))
+        {
+            if (outcome is SimulatedSqlResultSet rs)
+                return (rs.Schema, rs.ColumnNames);
+        }
+        throw OpenQueryNoResultSet(server.Name);
+    }
+
+    private static NotSupportedException OpenQueryNoResultSet(string serverName) =>
+        new($"OPENQUERY pass-through query on linked server '{serverName}' returned no result set. Only queries that produce a result set are supported.");
+
+    /// <summary>
+    /// Re-runs the pass-through query on the remote and materializes the
+    /// first result set's encoded rows (buffered before the remote
+    /// connection disposes). Only the first result set is returned, matching
+    /// OPENQUERY's semantics.
+    /// </summary>
+    [SuppressMessage("Security", "CA2100:Review SQL queries for security vulnerabilities", Justification = "OPENQUERY's second argument is a pass-through query string by design — the caller intends it to run verbatim on the remote. The remote command runs against a sibling Simulation in the same process; there's no external SQL surface to inject against.")]
+    private static List<byte[]> StreamOpenQueryRows(LinkedServer server, string queryText)
+    {
+        using var conn = server.Target.CreateDbConnection();
+        conn.Open();
+        using var cmd = conn.CreateCommand();
+        cmd.CommandText = queryText;
+        foreach (var outcome in server.Target.CreateResultSetsForCommand(cmd))
+        {
+            if (outcome is SimulatedSqlResultSet rs)
+                return [.. rs.RowBytes];
+        }
+        return [];
+    }
 }