Add QueryExecutor extensibility docs for custom database types (discussion #2993)

Co-authored-by: JerryNixon <1749983+JerryNixon@users.noreply.github.com>

Author: Copilot

docs/custom-database-executor.md

@@ -0,0 +1,150 @@
+# Extending DAB with a Custom Database Executor
+
+Data API builder (DAB) natively supports Azure SQL / SQL Server, Azure SQL DW, PostgreSQL, MySQL, and Cosmos DB.
+This guide shows how to create a custom `QueryExecutor` for a database engine that DAB does not support out of the box (for example, Oracle).
+
+## Prerequisites
+
+- Familiarity with C# generics and nullable reference types.
+- The [Oracle managed driver NuGet package](https://www.nuget.org/packages/Oracle.ManagedDataAccess.Core)
+  (or the equivalent driver for your database).
+
+---
+
+## 1. Project setup
+
+Create a new class-library project and reference the `Azure.DataApiBuilder.Core` package.
+
+In your `.csproj`, enable **nullable reference types** — this is required because the
+`QueryExecutor<TConnection>` base class uses `TResult?` on unconstrained generic type
+parameters:
+
+```xml
+<PropertyGroup>
+  <Nullable>enable</Nullable>
+</PropertyGroup>
+```
+
+---
+
+## 2. Implement `OracleQueryExecutor`
+
+Inherit from `QueryExecutor<TConnection>`, supplying your concrete connection type as
+the generic argument:
+
+```csharp
+using System.Data.Common;
+using Azure.DataApiBuilder.Core.Configurations;
+using Azure.DataApiBuilder.Core.Models;
+using Azure.DataApiBuilder.Core.Resolvers;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Logging;
+using Oracle.ManagedDataAccess.Client;
+
+public class OracleQueryExecutor : QueryExecutor<OracleConnection>
+{
+    public OracleQueryExecutor(
+        DbExceptionParser dbExceptionParser,
+        ILogger<IQueryExecutor> logger,
+        RuntimeConfigProvider configProvider,
+        IHttpContextAccessor httpContextAccessor,
+        HotReloadEventHandler<HotReloadEventArgs>? handler)
+        : base(dbExceptionParser, logger, configProvider, httpContextAccessor, handler)
+    {
+    }
+
+    // Override only the methods that need Oracle-specific behavior.
+    // All other virtual methods (CreateConnection, PrepareDbCommand, etc.)
+    // fall back to the base-class implementations.
+
+    /// <inheritdoc/>
+    public override async Task<TResult?> ExecuteQueryAsync<TResult>(
+        string sqltext,
+        IDictionary<string, DbConnectionParam> parameters,
+        Func<DbDataReader, List<string>?, Task<TResult>>? dataReaderHandler,
+        string dataSourceName,
+        HttpContext? httpContext = null,
+        List<string>? args = null)
+    {
+        // Add Oracle-specific pre/post processing here if needed.
+        return await base.ExecuteQueryAsync(
+            sqltext,
+            parameters,
+            dataReaderHandler,
+            dataSourceName,
+            httpContext,
+            args);
+    }
+}
+```
+
+---
+
+## 3. Common pitfalls
+
+### Missing generic type argument
+
+```csharp
+// ❌ WRONG — "QueryExecutor" without a type argument is an open generic type
+//            and cannot be used as a base class directly.
+public class OracleQueryExecutor : QueryExecutor
+
+// ✅ CORRECT — provide the concrete connection type
+public class OracleQueryExecutor : QueryExecutor<OracleConnection>
+```
+
+### Missing `<TResult>` on the override method name
+
+```csharp
+// ❌ WRONG — "ExecuteQueryAsync(" without <TResult> declares a new non-generic
+//            method; it does not override the base class generic method.
+public override async Task<TResult?> ExecuteQueryAsync(
+
+// ✅ CORRECT — include <TResult> so the compiler matches the base signature
+public override async Task<TResult?> ExecuteQueryAsync<TResult>(
+```
+
+### Missing `<Nullable>enable</Nullable>` in the project file
+
+Without this setting, `TResult?` on an unconstrained generic type parameter is not
+valid C# syntax and produces:
+
+```text
+Cannot implicitly convert type 'TResult' to 'TResult?'.
+An explicit conversion exists (are you missing a cast?)
+```
+
+Add `<Nullable>enable</Nullable>` to the `<PropertyGroup>` of your `.csproj` file.
+
+---
+
+## 4. Registering the custom executor
+
+Wire up your executor in the dependency-injection container during startup, replacing
+the default executor for your data source type:
+
+```csharp
+services.AddSingleton<IQueryExecutor, OracleQueryExecutor>();
+```
+
+---
+
+## 5. Supported override points
+
+`QueryExecutor<TConnection>` exposes the following `virtual` members that you can
+override to customize behavior:
+
+| Member | Description |
+|---|---|
+| `CreateConnection(string)` | Create and return a new database connection. |
+| `ExecuteQueryAsync<TResult>(...)` | Async query execution with retry. |
+| `ExecuteQuery<TResult>(...)` | Sync query execution with retry. |
+| `ExecuteQueryAgainstDbAsync<TResult>(...)` | Async execution against an open connection. |
+| `ExecuteQueryAgainstDb<TResult>(...)` | Sync execution against an open connection. |
+| `PrepareDbCommand(...)` | Build the `DbCommand` from SQL text and parameters. |
+| `GetSessionParamsQuery(...)` | Return optional session-context SQL to prepend. |
+| `PopulateDbTypeForParameter(...)` | Set the `DbType` on a `DbParameter`. |
+| `SetManagedIdentityAccessTokenIfAnyAsync(...)` | Attach a Managed Identity token to the connection. |
+| `SetManagedIdentityAccessTokenIfAny(...)` | Sync variant of the above. |
+| `GetMultipleResultSetsIfAnyAsync(...)` | Process multiple result sets from a reader. |
+| `ConnectionStringBuilders` | Dictionary of data-source-name → connection-string builder. |

src/Core/Resolvers/QueryExecutor.cs

@@ -20,8 +20,73 @@
 namespace Azure.DataApiBuilder.Core.Resolvers
 {
     /// <summary>
-    /// Encapsulates query execution apis.
+    /// Encapsulates query execution APIs for a specific database connection type.
     /// </summary>
+    /// <typeparam name="TConnection">
+    /// The <see cref="DbConnection"/> subtype for the target database (for example,
+    /// <c>SqlConnection</c> for SQL Server, <c>NpgsqlConnection</c> for PostgreSQL,
+    /// or <c>OracleConnection</c> for Oracle).  The type must be a concrete class with
+    /// a public parameterless constructor.
+    /// </typeparam>
+    /// <remarks>
+    /// <para>
+    /// To add support for a new database type, create a class that inherits from
+    /// <c>QueryExecutor&lt;TConnection&gt;</c>, substituting the concrete connection type
+    /// for <c>TConnection</c>.  For example:
+    /// </para>
+    /// <code language="csharp">
+    /// // The project file must enable nullable reference types:
+    /// //   &lt;Nullable&gt;enable&lt;/Nullable&gt;
+    ///
+    /// public class OracleQueryExecutor : QueryExecutor&lt;OracleConnection&gt;
+    /// {
+    ///     public OracleQueryExecutor(
+    ///         DbExceptionParser dbExceptionParser,
+    ///         ILogger&lt;IQueryExecutor&gt; logger,
+    ///         RuntimeConfigProvider configProvider,
+    ///         IHttpContextAccessor httpContextAccessor,
+    ///         HotReloadEventHandler&lt;HotReloadEventArgs&gt;? handler)
+    ///         : base(dbExceptionParser, logger, configProvider, httpContextAccessor, handler)
+    ///     {
+    ///     }
+    ///
+    ///     // Override only the methods that require Oracle-specific behavior.
+    ///     // Note: the method name must include the generic type parameter &lt;TResult&gt;,
+    ///     // and the project must have &lt;Nullable&gt;enable&lt;/Nullable&gt; for TResult? to compile.
+    ///     public override async Task&lt;TResult?&gt; ExecuteQueryAsync&lt;TResult&gt;(
+    ///         string sqltext,
+    ///         IDictionary&lt;string, DbConnectionParam&gt; parameters,
+    ///         Func&lt;DbDataReader, List&lt;string&gt;?, Task&lt;TResult&gt;&gt;? dataReaderHandler,
+    ///         string dataSourceName,
+    ///         HttpContext? httpContext = null,
+    ///         List&lt;string&gt;? args = null)
+    ///     {
+    ///         // Add Oracle-specific logic here, then delegate to the base implementation.
+    ///         return await base.ExecuteQueryAsync(
+    ///             sqltext, parameters, dataReaderHandler, dataSourceName, httpContext, args);
+    ///     }
+    /// }
+    /// </code>
+    /// <para>
+    /// <strong>Common pitfalls:</strong>
+    /// <list type="bullet">
+    ///   <item><description>
+    ///     Omitting the generic type argument — <c>: QueryExecutor</c> is invalid;
+    ///     the correct form is <c>: QueryExecutor&lt;OracleConnection&gt;</c>.
+    ///   </description></item>
+    ///   <item><description>
+    ///     Omitting <c>&lt;TResult&gt;</c> on the override method name —
+    ///     <c>ExecuteQueryAsync(</c> will not be recognized as an override of the
+    ///     base generic method; use <c>ExecuteQueryAsync&lt;TResult&gt;(</c>.
+    ///   </description></item>
+    ///   <item><description>
+    ///     Missing <c>&lt;Nullable&gt;enable&lt;/Nullable&gt;</c> in the project file —
+    ///     without this setting, <c>TResult?</c> on an unconstrained type parameter
+    ///     produces a compile error.
+    ///   </description></item>
+    /// </list>
+    /// </para>
+    /// </remarks>
     public class QueryExecutor<TConnection> : IQueryExecutor
         where TConnection : DbConnection, new()
     {
@@ -163,6 +228,14 @@ public QueryExecutor(DbExceptionParser dbExceptionParser,
         }
 
         /// <inheritdoc/>
+        /// <remarks>
+        /// When overriding this method in a derived class, ensure that:
+        /// <list type="bullet">
+        ///   <item><description>The method name includes the generic type parameter: <c>ExecuteQueryAsync&lt;TResult&gt;</c>.</description></item>
+        ///   <item><description>The return type is <c>Task&lt;TResult?&gt;</c> (nullable).</description></item>
+        ///   <item><description>The containing project has <c>&lt;Nullable&gt;enable&lt;/Nullable&gt;</c> in its .csproj file.</description></item>
+        /// </list>
+        /// </remarks>
         public virtual async Task<TResult?> ExecuteQueryAsync<TResult>(
             string sqltext,
             IDictionary<string, DbConnectionParam> parameters,