fix(sql): chunk the key-value IN list at the dialect's bind ceiling (Driver.Sql-002, Driver.Sql.Dialect-002)

ISqlDialect gains MaxBindParameters — the per-command ceiling the seam was missing while modelling everything else that differs per backend: 2098 usable of SQL Server's 2100 (sp_executesql spends two), 1000 for Oracle's IN-list limit (ORA-01795, tighter than its 64k bind count), 65535 for the Postgres Bind message. SqlGroupPlanner.AddKeyValuePlans now emits several plans for one group when its distinct keys exceed that ceiling, instead of one statement the provider refuses after the connection opened — which left every tag in an EAV group publishing BadCommunicationError on every poll, permanently, and reported the database endpoint as down. Chunks share the group key; members follow their own key so a shared keyValue never splits. SqlPollReader is unchanged: it runs one command per plan and slices each plan's own Members back, proven by a fixture read at a ceiling of 1.
2026-08-10 08:02:44 -04:00
parent 74594e6083
commit 886ce1b87c
14 changed files with 509 additions and 16 deletions
@@ -6,9 +6,10 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Sql;

 /// <summary>
 ///     The provider seam (design §2.2). ADO.NET's <see cref="System.Data.Common"/> base types abstract
-///     connections, commands, parameters and readers; they do <b>not</b> abstract the three things that differ
-///     per backend — <b>identifier quoting</b>, the <b>metadata-catalog SQL</b>, and <b>row-limit syntax</b>.
-///     Those live here, so no dialect assumption leaks into the reader, the poll planner, or the schema browser.
+///     connections, commands, parameters and readers; they do <b>not</b> abstract the four things that differ
+///     per backend — <b>identifier quoting</b>, the <b>metadata-catalog SQL</b>, <b>row-limit syntax</b>, and
+///     the <b>per-command bind-parameter ceiling</b>. Those live here, so no dialect assumption leaks into the
+///     reader, the poll planner, or the schema browser.
 ///     <para><b>This interface is the driver's SQL-injection boundary.</b> Every runtime <em>value</em> is
 ///     bound as a <see cref="DbParameter"/> and never reaches a command text. Identifiers cannot be
 ///     parameterized in SQL, so the few that must appear as text are emitted through
@@ -106,6 +107,24 @@ public interface ISqlDialect
    /// <param name="command">The command to configure.</param>
    void ConfigureCommand(DbCommand command);

+    /// <summary>
+    ///     The most bound parameters this backend accepts in <b>one</b> command — 2098 usable of SQL Server's
+    ///     2100, 1000 entries in an Oracle <c>IN</c> expression list, 65535 on the Postgres wire protocol.
+    ///     Callers that build a variable-length parameter list must chunk at this number.
+    ///     <para><b>Why it belongs on the seam.</b> It differs per backend exactly as quoting, catalog SQL and
+    ///     row-limit syntax do, and a call site that guesses a provider limit it does not own is the defect
+    ///     this interface exists to prevent. Its absence was a shipped one: <c>SqlGroupPlanner</c> emitted one
+    ///     parameter per distinct <c>keyValue</c> with no bound, so a key-value (EAV) group above the cap was
+    ///     rejected by the provider <em>after</em> the connection opened and every tag in it published
+    ///     <c>BadCommunicationError</c> on every poll, permanently (Driver.Sql-002 /
+    ///     Driver.Sql.Dialect-002).</para>
+    ///     <para><b>The number is a ceiling on what the planner may emit, not the raw provider constant</b> —
+    ///     a dialect whose provider spends parameters of its own subtracts them here, so a caller filling the
+    ///     value exactly always produces an executable command. Must be at least 1; a dialect reporting less
+    ///     is rejected at the call site rather than looping or emitting an empty <c>IN ()</c>.</para>
+    /// </summary>
+    int MaxBindParameters { get; }
+
    /// <summary>Cheapest statement that proves the connection is alive (<c>SELECT 1</c>; Oracle needs <c>FROM DUAL</c>).</summary>
    string LivenessSql { get; }

@@ -103,6 +103,16 @@ public sealed class OracleDialect : ISqlDialect
        if (command is OracleCommand oracle) oracle.BindByName = true;
    }

+    /// <summary>
+    ///     1000 — <b>the tightest of the three ceilings, and the one that actually binds.</b> Oracle allows
+    ///     64k bind variables per statement, but an <c>IN</c> <em>expression list</em> is limited to 1000
+    ///     entries (<c>ORA-01795</c>), and the key-value model's <c>IN (:p_k0, …)</c> list is the only
+    ///     variable-length parameter list this driver emits. The seam therefore reports the limit the caller
+    ///     will hit rather than the larger one it never reaches — a dialect that reported 64000 here would be
+    ///     technically accurate and would still produce a statement the server refuses.
+    /// </summary>
+    public int MaxBindParameters => 1000;
+
    /// <summary>Oracle has no bare <c>SELECT</c>; every projection needs a table, and <c>DUAL</c> is the one-row one.</summary>
    public string LivenessSql => "SELECT 1 FROM DUAL";

@@ -64,6 +64,14 @@ public sealed class PostgresDialect : ISqlDialect
        // Intentionally empty: see the summary.
    }

+    /// <summary>
+    ///     65535 — the extended-query protocol carries the parameter count as a signed/unsigned 16-bit field
+    ///     in <c>Bind</c>, so that is a protocol ceiling rather than a server setting, and Npgsql raises it
+    ///     client-side before a round-trip. Far above anything a poll group reaches in practice; it is here so
+    ///     the planner never has to special-case "this dialect has no meaningful limit".
+    /// </summary>
+    public int MaxBindParameters => 65535;
+
    /// <inheritdoc/>
    public string LivenessSql => "SELECT 1";

@@ -59,6 +59,15 @@ public sealed class SqlServerDialect : ISqlDialect
        // Intentionally empty: see the summary.
    }

+    /// <summary>
+    ///     2098 — SQL Server's hard cap is <b>2100 parameters per statement</b>, and
+    ///     <c>Microsoft.Data.SqlClient</c> spends two of them itself: a parameterized command is executed
+    ///     through <c>sp_executesql</c>, whose first two arguments are the statement text and the parameter
+    ///     declaration list. A caller filling 2100 would therefore be rejected with
+    ///     <c>"The incoming request has too many parameters"</c> for a limit it appeared to respect.
+    /// </summary>
+    public int MaxBindParameters => 2098;
+
    /// <inheritdoc/>
    public string LivenessSql => "SELECT 1";